Merge pull request #226 from lsst-sqre/tickets/DM-44193

DM-44193: Add [sphinx.redirects] table to documenteer.toml

CHANGELOG.md

@@ -2,6 +2,29 @@
 
 <!-- scriv-insert-here -->
 
+<a id='changelog-1.3.0'></a>
+## 1.3.0 (2024-05-03)
+
+### New features
+
+- Added a `[sphinx.redirects]` table to `documenteer.toml`. This provides support for configuring page redirects from the TOML configuratin. Redirects are useful if pages move because of a content re-organization. This feature is based on [sphinx-rediraffe](https://github.com/wpilibsuite/sphinxext-rediraffe).
+
+- Added the [sphinxcontrib-youtube](https://sphinxcontrib-youtube.readthedocs.io/en/latest/index.html) for embedded YouTube and Vimeo videos into documentation pages. This extension is available for both user guides (`documenteer.conf.guide`) and technotes (`documenteer.conf.technotes`).
+
+### Bug fixes
+
+- Technotes ignore files in the repository with `.md`, `.rst`, and `.ipynb` extensions if they aren't the index file. Since technotes are single-page documents, only the index file should be used as a source file. This change lets authors include auxiliary notebooks with their technotes without having to explicitly exclude them from the technote build process. This is implemented with `technote.conf.extend_excludes_for_non_index_source`.
+
+- In `documenteer.ext.lssttasks`, attempt to import `_pseudo_parse_arglist` from `sphinx.domains.python._annotations` before falling back to the `sphinx.domains.python` module. Ultimately this is a workaround.
+
+- Fix setting the rebuild condition for the `documenteer.ext.githubbibcache` extension.
+
+- Fixed the monospace text baseline alignment issue in Safari for technotes by updating to technote 0.8.0. In this version, the font size of the code is set to be 0.9em so that the browser doesn't push the text below the baseline in case its larger than the Source Sans body text. This version also changes the font size on the html element to 100% and instead increases the baseline body text size to 1.1rem on the body element. This change should help technotes respect the user's browser font size settings while also making the rem unit work as expected.
+
+### Other changes
+
+- Added `defusedxml` as a dev dependency. This is used by Sphinx's `sphinx.testing.fixtures`, but isn't included as a dependency by Sphinx itself. This change ensures that `defusedxml` is installed when running the tests.
+
 <a id='changelog-1.2.2'></a>
 ## 1.2.2 (2024-04-11)
 

docs/conf.py

@@ -1,13 +1,3 @@
 # 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",
-}
+from documenteer.conf.guide import *  # noqa: F403

docs/documenteer.toml

@@ -44,3 +44,12 @@ technote = "https://technote.lsst.io/"
 ignore = [
     "https://mermaid-js.github.io"
 ]
+
+[sphinx.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"

docs/guides/index.rst

@@ -26,6 +26,7 @@ Documenteer provides a configuration profile for creating branded user guides wi
    pyproject-configuration
    openapi
    rst-epilog
+   page-redirects
    extend-conf-py
 
 .. toctree::
@@ -36,6 +37,7 @@ Documenteer provides a configuration profile for creating branded user guides wi
    diagrams
    badges
    tabsets
+   video-embeds
 
 .. toctree::
    :maxdepth: 2

docs/guides/page-redirects.rst

@@ -0,0 +1,42 @@
+###########################################
+Redirecting pages when reorganizing content
+###########################################
+
+As a documentation site grows, its natural for content to need to move.
+If pages are moved or renamed, you should create a redirect from the old page path to the new one so that users won't be orphaned by out-of-date links and bookmarks.
+Documenteer supports this with the :ref:`guide-sphinx-redirects` table in the :file:`documenteer.toml` configuration file.
+
+Adding a page redirect in documenteer.toml
+==========================================
+
+As an example, consider the page at :file:`old-page.rst` has moved to :file:`some-dir/new-page.rst`.
+To create a redirect from the old page to the new one, add the following to the :file:`documenteer.toml` file:
+
+.. code-block:: toml
+   :caption: documenteer.toml
+
+   [sphinx.redirects]
+   "old-page.rst" = "some-dir/new-page.rst"
+
+These paths are relative to the documentation project's root directory (where :file:`conf.py` and :guide:`documenteer.toml` are located) and include the file extension (e.g., :file:`.rst` or :file:`.md`).
+
+The table accepts an arbitrary number of redirects:
+
+.. code-block:: toml
+   :captin: documenteer.toml
+
+   [sphinx.redirects]
+   "old-page.rst" = "some-dir/new-page.rst"
+   "foo.rst" = "bar.rst"
+
+Redirects for deleted pages
+===========================
+
+Besides pages that have been moved, you can use this feature for pages that have been deleted.
+Choose an existing path that is most relevant to the deleted page and redirect it to the new location.
+
+.. code-block:: toml
+   :caption: documenteer.toml
+
+   [sphinx.redirects]
+   "deleted-page.rst" = "index.rst"

docs/guides/toml-reference.rst

@@ -372,10 +372,27 @@ The default value is ``api``, which is a good standard for Python projects with
 If the Python API is oriented towards contributors, such as in an application or service, you can change the default:
 
 .. code-block:: toml
+   :caption: documenteer.toml
 
    [sphinx]
    python_api_dir = "dev/api/contents"
 
+.. _guide-sphinx-redirects:
+
+[sphinx.redirects]
+==================
+
+|optional|
+
+A table of paths to redirect to other paths. Use this setting to redirect old page locations to the new locations when a documentation site is reorganized.
+
+.. code-block:: toml
+   :caption: documenteer.toml
+
+   [sphinx.redirects]
+   "old/path" = "new/path"
+   "old/path2" = "new/path2"
+
 [sphinx.theme]
 ==============
 

docs/guides/video-embeds.rst

@@ -0,0 +1,60 @@
+###############
+Embedded videos
+###############
+
+Videos and screencasts are a great way to show user interfaces in your documentation.
+Rubin Observatory has a Vimeo account where we store our documentation and user support videos.
+Rubin user guides have built-in directives, ``youtube`` and ``vimeo``, to embed video players into the documentation page.
+
+Embedding a Vimeo video
+=======================
+
+To embed a Vimeo video, use the ``vimeo`` directive with the video ID as the argument:
+
+.. tab-set::
+
+   .. tab-item:: reStructuredText
+      :sync: rst
+
+      .. code-block:: rst
+
+         .. vimeo:: 800911530
+
+   .. tab-item:: markdown
+      :sync: md
+
+      .. code-block:: markdown
+
+         :::vimeo 800911530
+
+The video ID is the number at the end of the video URL.
+For example, the video URL for the video with ID ``800911530`` is ``https://vimeo.com/800911530``.
+
+Embedding a YouTube video
+=========================
+
+To embed a YouTube video, use the ``youtube`` directive with the video ID as the argument:
+
+.. tab-set::
+
+   .. tab-item:: reStructuredText
+      :sync: rst
+
+      .. code-block:: rst
+
+         .. youtube:: yKqEDFvmYwY
+
+   .. tab-item:: markdown
+      :sync: md
+
+      .. code-block:: markdown
+
+         :::vimeo yKqEDFvmYwY
+
+The video ID is the string at the end of the video URL.
+For example, the video URL for the video with ID ``yKqEDFvmYwY`` is ``https://www.youtube.com/watch?v=yKqEDFvmYwY``.
+
+More information
+================
+
+- `sphinxcontrib-youtube <https://sphinxcontrib-youtube.readthedocs.io/en/latest/index.html>`__ is the Sphinx extension used to embed YouTube and Vimeo videos. See this documentation for additional options for using this extension.

pyproject.toml

@@ -76,6 +76,7 @@ guide = [
     "sphinxcontrib-redoc",
     "sphinxcontrib-jquery",
     "sphinxext-rediraffe",
+    "sphinxcontrib-youtube"
 ]
 pipelines = [
     # Theme and extensions for pipelines.lsst.io
@@ -107,7 +108,8 @@ technote = [
     "sphinxcontrib-mermaid",
     "sphinx-diagrams",
     "sphinx_design",
-    "myst-nb"
+    "myst-nb",
+    "sphinxcontrib-youtube"
 ]
 
 [project.urls]

src/documenteer/conf/_toml.py

@@ -276,6 +276,14 @@ class SphinxModel(BaseModel):
 
     linkcheck: LinkCheckModel = Field(default_factory=lambda: LinkCheckModel())
 
+    redirects: Dict[str, str] = Field(
+        description=(
+            "Mapping of paths to redirect to other paths. These redirects "
+            "are implemented with sphinx-rediraffe."
+        ),
+        default_factory=dict,
+    )
+
 
 class ConfigRoot(BaseModel):
     """The root model for a documenteer.toml configuration file."""
@@ -409,6 +417,14 @@ def rst_epilog(self) -> str:
         else:
             return self.rst_epilog_path.read_text()
 
+    @property
+    def redirects(self) -> Dict[str, str]:
+        """Redirects defined in the [sphinx.redirects] TOML configuration."""
+        if self.conf.sphinx:
+            return self.conf.sphinx.redirects
+        else:
+            return dict()
+
     def _get_pyproject_metadata(self, package_name: str) -> Message:
         if sys.version_info >= (3, 10) or sys.version_info < (3, 8):
             pkg_metadata = cast(Message, metadata(package_name))

src/documenteer/conf/guide.py

@@ -141,6 +141,7 @@
     "sphinx-prompt",
     "sphinx_jinja",
     "sphinxcontrib.redoc",
+    "sphinxcontrib.youtube",
     "sphinxext.rediraffe",
     "sphinx.ext.napoleon",
     "sphinx_autodoc_typehints",
@@ -456,4 +457,4 @@
 # #REDIRECTS Sphinx-rediraffe support
 # https://sphinxext-rediraffe.readthedocs.io/en/latest/
 # ============================================================================
-rediraffe_redirects: dict[str, str] = {}
+rediraffe_redirects: dict[str, str] = _conf.redirects

src/documenteer/conf/technote.py

@@ -41,6 +41,7 @@
         "sphinxcontrib.mermaid",
         "sphinx_prompt",
         "sphinx_design",
+        "sphinxcontrib.youtube",
     ]
 )