Merge pull request #193 from lsst-sqre/tickets/DM-41296

DM-41296: Migrate out of documenteer.sphinxext namespace
lsst-sqre · Oct 26, 2023 · 4a53207 · 4a53207
2 parents 0bee9bf + cde778d
commit 4a53207
Show file tree

Hide file tree

Showing 69 changed files with 260 additions and 1,728 deletions.
diff --git a/changelog.d/20231024_170151_jsick_DM_41296.md b/changelog.d/20231024_170151_jsick_DM_41296.md
@@ -0,0 +1,18 @@
+### Backwards-incompatible changes
+
+- Delete the `refresh-lsst-bib` CLI command. Technotes now automatically vendor lsst-texmf's bib files and cache them using `documenteer.ext.githubbibcache`.
+- Delete the `build-stack-docs` CLI command, which was replaced by the `stack-docs` and `package-docs` CLIs in Documenteer 0.3.0.
+- The `documenteer.conf.pipelines` and `documenteer.conf.pipelinespkg` configuration modules now derive from `documenteer.conf.guide`. In doing so, the Pipelines documentation configuration works the same as Rubin Guides, but with additional configuration for pipelines-specific Sphinx extensions and other configurations. With this change, the `lsst-sphinx-bootstrap-theme` is no longer used by Documenteer.
+- The `documenteer.sphinxext` module has been removed and the existing Sphinx extensions within it are now available from `documenteer.ext`. It's no longer possible to use `documenteer.sphinxext` to automatically load all Documenteer Sphinx extensions. Extensions need to now be added individually to the `extensions` configuration variable in `conf.py`. The migrated extension modules are:
+
+  - `documenteer.ext.bibtex`
+  - `documenteer.ext.jira`
+  - `documenteer.ext.lsstdocushare`
+  - `documenteer.ext.lssttasks`
+  - `documenteer.ext.mockcoderefs`
+  - `documenteer.ext.packagetoctree`
+
+### New features
+
+- Add `sphinx-jinja` to the Rubin guides configuration by default.
+- Add `sphinx-rediraffe` to the Rubin guides configuration by default.
diff --git a/docs/Makefile b/docs/Makefile
@@ -24,7 +24,7 @@ help:
 
 clean:
 	rm -rf $(BUILDDIR)/*
-	rm -rf api/*
+	rm -rf dev/api/contents*
 
 html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html

diff --git a/docs/_rst_epilog.rst b/docs/_rst_epilog.rst
@@ -62,10 +62,10 @@
 
 .. |documenteer.toml| replace:: :doc:`documenteer.toml </guides/toml-reference>`
 .. |documenteer.conf.guide| replace:: :doc:`documenteer.conf.guide </guides/configuration-preset>`
-.. |package-docs| replace:: :doc:`package-docs </pipelines/package-docs-cli>`
-.. |stack-docs| replace:: :doc:`stack-docs </pipelines/stack-docs-cli>`
-.. |stack-docs-build| replace:: :doc:`stack-docs build </pipelines/stack-docs-cli>`
-.. |stack-docs-clean| replace:: :doc:`stack-docs clean </pipelines/stack-docs-cli>`
+.. |package-docs| replace:: :doc:`package-docs </guides/pipelines/package-docs-cli>`
+.. |stack-docs| replace:: :doc:`stack-docs </guides/pipelines/stack-docs-cli>`
+.. |stack-docs-build| replace:: :doc:`stack-docs build </guides/pipelines/stack-docs-cli>`
+.. |stack-docs-clean| replace:: :doc:`stack-docs clean </guides/pipelines/stack-docs-cli>`
 
 .. links to sphinx directives
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -1,3 +1,13 @@
 # See the documenteer.toml for overrides of the Rubin user guide presets
 
 from documenteer.conf.guide import *
+
+rediraffe_redirects = {
+    "pipelines/build-overview.rst": "guides/pipelines/build-overview.rst",
+    "pipelines/configuration.rst": "guides/pipelines/configuration.rst",
+    "pipelines/cpp-api-linking.rst": "guides/pipelines/cpp-api-linking.rst",
+    "pipelines/index.rst": "guides/pipelines/index.rst",
+    "pipelines/install.rst": "guides/pipelines/install.rst",
+    "pipelines/package-docs-cli.rst": "guides/pipelines/package-docs-cli.rst",
+    "pipelines/stack-docs-cli.rst": "guides/pipelines/stack-docs-cli.rst",
+}
diff --git a/docs/dev/api/documenteer.ext.rst b/docs/dev/api/documenteer.ext.rst
@@ -7,3 +7,19 @@ documenteer.ext
 .. automodapi:: documenteer.ext.autodocreset
 
 .. automodapi:: documenteer.ext.openapi
+
+.. automodapi:: documenteer.ext.bibtex
+   :no-inherited-members:
+   :no-inheritance-diagram:
+
+.. automodapi:: documenteer.ext.jira
+   :no-inheritance-diagram:
+
+.. automodapi:: documenteer.ext.lsstdocushare
+   :no-inheritance-diagram:
+
+.. automodapi:: documenteer.ext.mockcoderefs
+   :no-inheritance-diagram:
+
+.. automodapi:: documenteer.ext.packagetoctree
+   :no-inheritance-diagram:
diff --git a/docs/dev/api/documenteer.sphinxconfig.rst b/docs/dev/api/documenteer.sphinxconfig.rst
diff --git a/docs/dev/api/documenteer.sphinxext.rst b/docs/dev/api/documenteer.sphinxext.rst
diff --git a/docs/dev/api/index.rst b/docs/dev/api/index.rst
@@ -1,13 +1,12 @@
-####################
-Python API reference
-####################
+##########
+Python API
+##########
 
 .. toctree::
+   :titlesonly:
 
    documenteer.conf
    documenteer.ext
    documenteer.requestsutils
-   documenteer.sphinxconfig
-   documenteer.sphinxext
    documenteer.sphinxrunner
    documenteer.stackdocs
diff --git a/docs/dev/index.rst b/docs/dev/index.rst
@@ -16,7 +16,7 @@ Development
    theme
 
 .. toctree::
-   :caption: Reference
    :maxdepth: 2
+   :caption: Reference
 
    api/index
diff --git a/docs/guides/index.rst b/docs/guides/index.rst
@@ -37,6 +37,14 @@ Documenteer provides a configuration profile for creating branded user guides wi
    badges
    tabsets
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Science Pipelines
+   :name: toc-guides-pipelines
+   :titlesonly:
+
+   pipelines/index
+
 .. toctree::
    :maxdepth: 2
    :caption: Reference

diff --git a/docs/pipelines/build-overview.rst → docs/guides/pipelines/build-overview.rst b/docs/pipelines/build-overview.rst → docs/guides/pipelines/build-overview.rst
diff --git a/docs/pipelines/configuration.rst → docs/guides/pipelines/configuration.rst b/docs/pipelines/configuration.rst → docs/guides/pipelines/configuration.rst
@@ -74,11 +74,11 @@ Configuration source reference
 documenteer.conf.pipelines source
 ---------------------------------
 
-.. literalinclude:: ../../src/documenteer/conf/pipelines.py
+.. literalinclude:: ../../../src/documenteer/conf/pipelines.py
 
 .. _pipelinespkg-conf-source:
 
 documenteer.conf.pipelinespkg source
 ------------------------------------
 
-.. literalinclude:: ../../src/documenteer/conf/pipelinespkg.py
+.. literalinclude:: ../../../src/documenteer/conf/pipelinespkg.py
diff --git a/docs/pipelines/cpp-api-linking.rst → docs/guides/pipelines/cpp-api-linking.rst b/docs/pipelines/cpp-api-linking.rst → docs/guides/pipelines/cpp-api-linking.rst
diff --git a/docs/pipelines/index.rst → docs/guides/pipelines/index.rst b/docs/pipelines/index.rst → docs/guides/pipelines/index.rst
diff --git a/docs/pipelines/install.rst → docs/guides/pipelines/install.rst b/docs/pipelines/install.rst → docs/guides/pipelines/install.rst
diff --git a/docs/pipelines/package-docs-cli.rst → docs/guides/pipelines/package-docs-cli.rst b/docs/pipelines/package-docs-cli.rst → docs/guides/pipelines/package-docs-cli.rst
diff --git a/docs/pipelines/stack-docs-cli.rst → docs/guides/pipelines/stack-docs-cli.rst b/docs/pipelines/stack-docs-cli.rst → docs/guides/pipelines/stack-docs-cli.rst
diff --git a/docs/index.rst b/docs/index.rst
@@ -42,13 +42,13 @@ Installation
 
          pip install "documenteer[technote]"
 
-      For :doc:`LSST Science Pipelines projects and other EUPS stacks </pipelines/index>`:
+      For :doc:`LSST Science Pipelines projects and other EUPS stacks </guides/pipelines/index>`:
 
       .. code-block:: sh
 
          pip install "documenteer[pipelines]"
 
-      See :doc:`/pipelines/install` for more information.
+      See :doc:`/guides/pipelines/install` for more information.
 
    .. tab-item:: conda
 
@@ -91,7 +91,6 @@ This section describes how to use Documenteer for specific types of projects, fr
 
    Rubin user guides <guides/index>
    Technical notes <technotes/index>
-   Science Pipelines <pipelines/index>
 
 Sphinx extensions
 =================

diff --git a/docs/sphinx-extensions/autocppapi.rst b/docs/sphinx-extensions/autocppapi.rst
@@ -17,7 +17,7 @@ To use this directive, add the ``documenteer.ext.autocppapi`` extension to your
 
    The ``autocppapi`` extension needs Doxylink to be installed and also included in the extensions listing.
    If you installed ``autocppapi`` through the :ref:`"pipelines" extra <pip-install>`, Doxylink will be installed for you.
-   Doxylink is automatically configured in Pipelines documentation builds to point to a Doxygen site that's embedded during the build process (see :doc:`/pipelines/build-overview`).
+   Doxylink is automatically configured in Pipelines documentation builds to point to a Doxygen site that's embedded during the build process (see :doc:`/guides/pipelines/build-overview`).
    Otherwise, you can manually add Doxylink to your project's depenencies:
 
    .. prompt:: bash

diff --git a/docs/sphinx-extensions/autodocreset.rst b/docs/sphinx-extensions/autodocreset.rst
@@ -6,7 +6,7 @@ The autodocreset extension for resetting automodapi's autodoc enhancements
 
 The `sphinx-automodapi`_ extension includes an ``autodoc_enhancements`` module that replaces autodoc's built-in "attr getter" for ``type``.
 While this enhancement is useful for Python meta programming, it can also be incompatible with Pybind11 static properties, which are present in the LSST Science Pipelines.
-This Sphinx extension resets automodapi's autodoc enhancements and is included by default in the :doc:`Pipelines Sphinx configuration </pipelines/configuration>`.
+This Sphinx extension resets automodapi's autodoc enhancements and is included by default in the :doc:`Pipelines Sphinx configuration </guides/pipelines/configuration>`.
 
 .. _sphinx-automodapi: https://sphinx-automodapi.readthedocs.io/en/latest/
 

diff --git a/docs/sphinx-extensions/docushare-reference.rst b/docs/sphinx-extensions/docushare-reference.rst
@@ -6,11 +6,11 @@ LSST document reference roles
 
 Documenteer provides reStructuredText roles that simplify linking to LSST documents according to their handle.
 
-To use these roles, add the ``documenteer.sphinext.lsstdocushare`` extension to your :file:`conf.py` file:
+To use these roles, add the ``documenteer.ext.lsstdocushare`` extension to your :file:`conf.py` file:
 
 .. code-block:: python
 
-   extensions = ["documenteer.sphinxext.lsstdocushare"]
+   extensions = ["documenteer.ext.lsstdocushare"]
 
 Summary
 =======

diff --git a/docs/sphinx-extensions/githubbibcache.rst b/docs/sphinx-extensions/githubbibcache.rst
@@ -36,14 +36,14 @@ In your project's :file:`conf.py` file, set up the extensions like this:
       :caption: conf.py
 
       extensions = [
-          "documenteer.sphinxext.bibtex",
+          "documenteer.ext.bibtex",
           "documenteer.ext.githubbibcache",
           "sphinxcontrib.bibtex",
       ]
 
       bibtex_default_style = "lsst_aa"
 
-   The style configuration specifies the style provided by ``documenteer.sphinxext.bibtex``.
+   The style configuration specifies the style provided by ``documenteer.ext.bibtex``.
 
 Specify the GitHub repositories and their BibTeX files
 ======================================================

diff --git a/docs/sphinx-extensions/jira-reference.rst b/docs/sphinx-extensions/jira-reference.rst
@@ -6,11 +6,11 @@ Jira reference roles
 
 Documenteer provides reStructuredText roles to simplify linking to issues in LSST's Jira ticketing system at https://jira.lsstcorp.org.
 
-To use these roles, add the ``documenteer.sphinxext.jira`` extension to your :file:`conf.py` file:
+To use these roles, add the ``documenteer.ext.jira`` extension to your :file:`conf.py` file:
 
 .. code-block:: python
 
-   extensions = ["documenteer.sphinxext.jira"]
+   extensions = ["documenteer.ext.jira"]
 
 Roles
 =====

diff --git a/docs/sphinx-extensions/lsst-pybtex-style.rst b/docs/sphinx-extensions/lsst-pybtex-style.rst
@@ -5,17 +5,17 @@ BibTeX style extension for Rubin Observatory
 ############################################
 
 sphinxcontrib-bibtex_ is an excellent way to include academic citations in Sphinx documentation projects.
-Documenteer provides support for `LSST's common BibTeX bibliography files <https://github.com/lsst/lsst-texmf/tree/main/texmf/bibtex/bib>`__ (maintained in `lsst-texmf <https://github.com/lsst/lsst-texmf>`__) through its ``documenteer.sphinxext.bibtex`` extension.
+Documenteer provides support for `LSST's common BibTeX bibliography files <https://github.com/lsst/lsst-texmf/tree/main/texmf/bibtex/bib>`__ (maintained in `lsst-texmf <https://github.com/lsst/lsst-texmf>`__) through its ``documenteer.ext.bibtex`` extension.
 Specifically, this extension provides support for ``docushare`` fields in those bib files.
 
 Usage
 =====
 
-To use this Sphinx extension, add ``documenteer.sphinxext.bibtex`` to your :file:`conf.py` file:
+To use this Sphinx extension, add ``documenteer.ext.bibtex`` to your :file:`conf.py` file:
 
 .. code-block:: python
 
-   extensions = ["documenteer.sphinxext.bibtex"]
+   extensions = ["documenteer.ext.bibtex"]
 
    bibtex_default_style = "lsst_aa"
 

diff --git a/docs/sphinx-extensions/lssttasks.rst b/docs/sphinx-extensions/lssttasks.rst
@@ -4,13 +4,13 @@ Sphinx extensions for the LSST Science Pipelines task framework
 
 These extensions allow you to document and reference tasks in the LSST Science Pipelines.
 
-Enable these extensions by adding ``documenteer.sphinxext.lssttasks`` to the Sphinx project's ``extensions`` configuration list.
+Enable these extensions by adding ``documenteer.ext.lssttasks`` to the Sphinx project's ``extensions`` configuration list.
 
-To use this Sphinx extension, add ``documenteer.sphinxext.lssttasks`` to your :file:`conf.py` file:
+To use this Sphinx extension, add ``documenteer.ext.lssttasks`` to your :file:`conf.py` file:
 
 .. code-block:: python
 
-   extensions = ["documenteer.sphinxext.lssttasks"]
+   extensions = ["documenteer.ext.lssttasks"]
 
 The ``documenteer.conf.pipelines`` and ``documenteer.conf.pipelinespkg`` configurations automatically add these extensions to LSST Science Pipelines package documentation projects.
 

diff --git a/docs/sphinx-extensions/package-toctree.rst b/docs/sphinx-extensions/package-toctree.rst
@@ -6,13 +6,13 @@ Package toctree extension for LSST Stack documentation
 
 Documenteer provides the :dir:`package-toctree` :dir:`module-toctree` directives that are useful building dynamic toctrees of package and module documentation in stack documentation projects like the LSST Science Pipelines (https://pipelines.lsst.io).
 
-To use this Sphinx extension, add ``documenteer.sphinxext.packagetoctree`` to your :file:`conf.py` file:
+To use this Sphinx extension, add ``documenteer.ext.packagetoctree`` to your :file:`conf.py` file:
 
 .. code-block:: python
 
-   extensions = ["documenteer.sphinxext.packagetoctree"]
+   extensions = ["documenteer.ext.packagetoctree"]
 
-To learn more about the build process for stack documentation projects, see :doc:`/pipelines/build-overview`.
+To learn more about the build process for stack documentation projects, see :doc:`/guides/pipelines/build-overview`.
 
 Summary
 =======

diff --git a/docs/sphinx-extensions/remote-code-block.rst b/docs/sphinx-extensions/remote-code-block.rst
@@ -6,11 +6,11 @@ The remote code block extension
 
 Documenteer provides a :dir:`remote-code-block` directive that works like :dir:`literalinclude`, but supports getting content from the web.
 
-To use this directive, add the ``documenteer.sphinext.remotecodeblock`` extension to your :file:`conf.py` file:
+To use this directive, add the ``documenteer.ext.remotecodeblock`` extension to your :file:`conf.py` file:
 
 .. code-block:: python
 
-   extensions = ["documenteer.sphinxext.remotecodeblock"]
+   extensions = ["documenteer.ext.remotecodeblock"]
 
 Directive
 =========

diff --git a/docs/technotes/index.rst b/docs/technotes/index.rst
@@ -11,11 +11,6 @@ Documenteer provides centralized configuration and tooling for technotes.
 
    configuration
 
-.. toctree::
-   :caption: CLI tools
-
-   refresh-lsst-bib
-
 .. seealso::
 
    To learn more about technotes:

diff --git a/docs/technotes/refresh-lsst-bib.rst b/docs/technotes/refresh-lsst-bib.rst