Update docs for first release (#120)

* exclude doctree from actual docs
* Update docs for first release

Author: PicoCentauri

README.rst

@@ -28,7 +28,7 @@ C++, making it ideal for high-performance production environments.
 
 For details, tutorials, and examples, please have a look at our `documentation`_.
 
-.. _`documentation`: https://lab-cosmo.github.io/torch-pme/latest
+.. _`documentation`: https://lab-cosmo.github.io/torch-pme
 
 .. marker-installation
 
@@ -39,18 +39,16 @@ You can install *torch-pme* using pip with
 
 .. code-block:: bash
 
-    git clone https://github.com/lab-cosmo/torch-pme
-    cd torch-pme
-    pip install .
+    pip install torch-pme
 
-You can then ``import torchpme`` and use it in your projects!
+and ``import torchpme`` to use it in your projects!
 
-We also provide bindings to `metatensor <https://docs.metatensor.org/latest/>`_ which
+We also provide bindings to `metatensor <https://docs.metatensor.org>`_ which
 can optionally be installed together and used as ``torchpme.metatensor`` via
 
 .. code-block:: bash
 
-    pip install .[metatensor]
+    pip install torch-pme[metatensor]
 
 .. marker-issues
 

docs/extensions/versions_list.py

@@ -0,0 +1,126 @@
+import docutils
+from packaging.version import parse as version_parse
+from sphinx.util.docutils import SphinxDirective
+
+
+DOC_ROOT = "https://lab-cosmo.github.io/torch-pme"
+
+
+class VersionList(SphinxDirective):
+    """
+    Directive for a list of previous versions of the documentation.
+
+    This is rendered by manually generating ReST using sphinx-design directives.
+    """
+
+    has_content = True
+    required_arguments = 0
+    optional_arguments = 0
+    option_spec = {
+        "tag-prefix": str,
+        "url-suffix": str,
+    }
+
+    def run(self):
+        # group together versions with the same major & minor components
+        grouped_versions = {}
+        content = self.parse_content_to_nodes()
+        for node in content:
+            if not isinstance(node, VersionNode):
+                raise ValueError(
+                    "only `.. version::` is allowed inside `.. version-list::`"
+                )
+
+            version = version_parse(node.version)
+            group = (version.major, version.minor)
+            if group not in grouped_versions:
+                grouped_versions[group] = []
+
+            grouped_versions[group].append(node)
+
+        # generate ReST with the desired markup
+        generated_content = """
+.. grid::
+    :margin: 0 0 0 0\n"""
+
+        for group_i, (version_short, group) in enumerate(grouped_versions.items()):
+
+            if group_i < 3:
+                generated_content += f"""
+    .. grid-item::
+        :columns: 12 6 3 3
+        :class: sd-p-1
+
+        .. dropdown:: Version {version_short[0]}.{version_short[1]}
+            :class-body: sd-mb-0  sd-pb-0
+            :class-title: font-size-small\n"""
+            elif group_i == 3:
+                generated_content += """
+    .. grid-item::
+        :columns: 12 6 3 3
+        :class: sd-p-1
+
+        .. dropdown:: Older versions
+            :class-body: sd-mb-0  sd-pb-0
+            :class-title: font-size-small\n"""
+
+            for node in group:
+                version = node.version
+                tag_prefix = self.options["tag-prefix"]
+
+                url_suffix = (
+                    node.url_suffix
+                    if node.url_suffix is not None
+                    else self.options["url-suffix"]
+                )
+
+                generated_content += f"""
+            .. card:: {version}
+                :class-body: sd-p-2
+                :class-title: sd-mb-0
+                :text-align: center
+                :link: {DOC_ROOT}/{tag_prefix}{version}/{url_suffix}
+                :link-type: url\n"""
+
+        # parse the generated ReST
+        return self.parse_text_to_nodes(generated_content)
+
+
+class VersionNode(docutils.nodes.Node):
+    """
+    Node for a single version directive. This is only used to transmit information
+    between the ``.. version::`` directive and the version list, and never rendered on
+    its own.
+    """
+
+    def __init__(self, version, url_suffix):
+        self.version = version
+        self.url_suffix = url_suffix
+
+
+class VersionItem(SphinxDirective):
+    """
+    A single item in a version list. This can override the url suffix if a different url
+    was used for this version.
+    """
+
+    has_content = False
+    required_arguments = 1
+    optional_arguments = 0
+    final_argument_whitespace = False
+    option_spec = {
+        "url-suffix": str,
+    }
+
+    def run(self):
+        return [
+            VersionNode(
+                version=self.arguments[0],
+                url_suffix=self.options.get("url-suffix"),
+            )
+        ]
+
+
+def setup(app):
+    app.add_directive("version-list", VersionList)
+    app.add_directive("version", VersionItem)

docs/requirements.txt

@@ -1,5 +1,6 @@
 furo
 sphinx > 7.0
+sphinx-design
 sphinx-gallery
 sphinx-toggleprompt
 tomli

docs/src/conf.py

@@ -16,6 +16,7 @@
 suppress_warnings = ["config.cache"]
 
 ROOT = os.path.abspath(os.path.join("..", ".."))
+sys.path.append(os.path.join(ROOT, "docs", "extensions"))
 
 # We use a second (pseudo) sphinx project located in `docs/generate_examples` to run the
 # examples and generate the actual output for our shinx-gallery. This is necessary
@@ -63,6 +64,12 @@ def setup(app):
     generate_examples()
 
 
+rst_prolog = f"""
+.. |version| replace:: {torchpme.__version__}
+
+"""
+
+
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
@@ -72,7 +79,10 @@ def setup(app):
     "sphinx.ext.viewcode",
     "sphinx_gallery.gen_gallery",
     "sphinx_toggleprompt",
+    "sphinx_design",
     "chemiscope.sphinx",
+    # local extensions
+    "versions_list",
 ]
 
 # List of patterns, relative to source directory, that match files and

docs/src/references/index.rst

@@ -3,6 +3,17 @@
 API reference
 =============
 
+.. note::
+
+  This is the documentation for version |version|. For other versions, we refer to the
+  following pages:
+
+  .. version-list::
+     :tag-prefix: v
+     :url-suffix: references/index.html
+
+     .. version:: 0.1.0
+
 The main references for public functions and classes inside ``torch-pme``. For example
 refer to the :ref:`userdoc-how-to` section.
 

tox.ini

@@ -93,4 +93,4 @@ extras =
     examples
     metatensor
 commands =
-    sphinx-build {posargs:-E} -W -b html docs/src docs/build/html
+    sphinx-build {posargs:-E} -d docs/build/doctrees -W -b html docs/src docs/build/html