From 43c9508385230be3805a3509e31c00ed93eedf4d Mon Sep 17 00:00:00 2001 From: Philip Loche Date: Thu, 5 Dec 2024 19:03:17 +0100 Subject: [PATCH] Update docs for first release --- README.rst | 12 ++- docs/extensions/versions_list.py | 126 +++++++++++++++++++++++++++++++ docs/requirements.txt | 1 + docs/src/conf.py | 10 +++ docs/src/references/index.rst | 11 +++ 5 files changed, 153 insertions(+), 7 deletions(-) create mode 100644 docs/extensions/versions_list.py diff --git a/README.rst b/README.rst index 2358d029..ab0e7f6d 100644 --- a/README.rst +++ b/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 `_ which +We also provide bindings to `metatensor `_ 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 diff --git a/docs/extensions/versions_list.py b/docs/extensions/versions_list.py new file mode 100644 index 00000000..138a90f1 --- /dev/null +++ b/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) diff --git a/docs/requirements.txt b/docs/requirements.txt index 44ae3f86..49e142b3 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,5 +1,6 @@ furo sphinx > 7.0 +sphinx-design sphinx-gallery sphinx-toggleprompt tomli diff --git a/docs/src/conf.py b/docs/src/conf.py index 08065783..ed13ab08 100644 --- a/docs/src/conf.py +++ b/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 diff --git a/docs/src/references/index.rst b/docs/src/references/index.rst index c4b1461d..85bd304f 100644 --- a/docs/src/references/index.rst +++ b/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.