[librsvg: 16/21] Finish describing "librsvg as a product"

[Marge Bot <marge-bot src gnome org>]

commit cba35b6c19c20d36fee3c09a1896de06ae838251
Author: Federico Mena Quintero <federico gnome org>
Date:   Wed Aug 17 18:15:51 2022 -0500

    Finish describing "librsvg as a product"
    
    Part-of: <https://gitlab.gnome.org/GNOME/librsvg/-/merge_requests/729>

 devel-docs/index.rst   |  2 +-
 devel-docs/product.rst | 80 +++++++++++++++++++++++++++++++++++++++++++-------
 2 files changed, 71 insertions(+), 11 deletions(-)
---
diff --git a/devel-docs/index.rst b/devel-docs/index.rst
index 5319320de..b8470b4c1 100644
--- a/devel-docs/index.rst
+++ b/devel-docs/index.rst
@@ -5,7 +5,7 @@ Development guide for librsvg
    product
    contributing
    ci
-   :maxdepth: 2
+   :maxdepth: 1
    :caption: Contents:
 
 Welcome to the developer's guide for librsvg.  This is for people who
diff --git a/devel-docs/product.rst b/devel-docs/product.rst
index ee089fec3..aa4914dde 100644
--- a/devel-docs/product.rst
+++ b/devel-docs/product.rst
@@ -2,30 +2,90 @@ Librsvg as a product
 ====================
 
 A full build of librsvg produces several *artifacts*.  For this
-discussion, we will talk about the "library part" of the build, and
-the "rsvg-convert" part.
+discussion, we will talk about the "library part" of the build, the
+"rsvg-convert" part, and everything else for miscellaneous artifacts.
 
-The "library part" of the build produces the following:
 
-- A shared library ``librsvg-2.so``.  This is usually installed as
-  part of the system's libraries.  For example, the GTK toolkit
-  assumes that librsvg's library is installed in the system, and uses
-  it to load SVG assets like icons.
+The library part
+----------------
+
+Librsvg is part of the `GNOME platform libraries
+<https://developer.gnome.org/documentation/introduction/overview/libraries.html>`_,
+and needs to maintain API and ABI stability across versions.
+
+The build produces these:
+
+- A shared library ``librsvg-2.so`` (the file extension will be
+  different on MacOS or Windows).  This is usually installed as part
+  of the system's libraries.  For example, the GTK toolkit assumes
+  that librsvg's library is installed in the system, and uses it to
+  load SVG assets like icons.
 
 - A group of C header files (``*.h``) that will be installed in the
   system's location for header files.  C and C++ programs can use
   these directly.
 
 - A ``librsvg-2.pc`` file for `pkg-config
-  <https://www.freedesktop.org/wiki/Software/pkg-config/>`.  This lets
+  <https://www.freedesktop.org/wiki/Software/pkg-config/>`_.  This lets
   compilation scripts find the location of the installed library and
   header files.
 
 - ``.gir`` and ``.typelib`` files for `GObject Introspection
-  <https://gi.readthedocs.io/en/latest/>`.  These are machine-readable
+  <https://gi.readthedocs.io/en/latest/>`_.  These are machine-readable
   descriptions of the API/ABI in the `.so` library, which are used by
   language bindings to make librsvg's functionality available to many
   programming languages.
 
-- A ``.vapi`` description of the API for the `Vala <https://vala.dev/>` compiler.
+- A ``.vapi`` description of the API for the `Vala
+  <https://vala.dev/>`_ compiler.
+
+Apart from that, the Rust code for the library defines a ``librsvg``
+crate that can be used by Rust programs.  Rust will automatically
+build the code and link it into such a program, so this is not
+considered part of librsvg's normal build artifacts.  However, its API
+stability promise still applies, but not as strictly as for the C API.
+When librsvg gets `published to crates.io`_, it will follow Rust's
+usual semantic versioning scheme for API compatibility.
+
+.. _published to crates.io: https://gitlab.gnome.org/GNOME/librsvg/-/issues/635
+
+
+The `rsvg-convert` part
+-----------------------
+
+``rsvg-convert`` is a command-line tool to render SVG documents to
+various output formats.  It is a very widely-used tool, and many
+scripts and systems depend on it maintaining a stable set of
+command-line options.
+
+The build produces these:
+
+- The ``rsvg-convert`` executable.  This is the tool that most
+  end-users interact with.
+
+- A Unix manual page for ``rsvg-convert(1)``.
+
+
+Everything else
+---------------
+
+- A ``libpixbufloader-svg.so`` module for `gdk-pixbuf
+  <https://docs.gtk.org/gdk-pixbuf/>`_.  This allows programs to use
+  the gdk-pixbuf API to load SVG documents, as if they were raster
+  files like JPEG or PNG.
+
+- A ``librsvg.thumbnailer`` configuration file, to tell GNOME's
+  thumbnailing mechanism that it can just use gdk-pixbuf when trying
+  to create a thumbnail for an SVG file.  These thumbnails can then
+  get displayed in file managers.
+
+- `Documentation for the C API
+  <https://gnome.pages.gitlab.gnome.org/librsvg/Rsvg-2.0/index.html>`_,
+  published online and also installed on the system in a place where
+  GNOME's `DevHelp <https://gitlab.gnome.org/GNOME/devhelp>`_ can find
+  it.
 
+- `Documentation for the Rust API
+  <https://gnome.pages.gitlab.gnome.org/librsvg/doc/librsvg/index.html>`_,
+  published online.  This is not built from the normal `make` process,
+  but independently as part of the :doc:`ci` pipeline.