documenteer 2.0.0a4__tar.gz → 2.1.1__tar.gz

{documenteer-2.0.0a4 → documenteer-2.1.1}/CHANGELOG.md

@@ -2,6 +2,143 @@
 
 <!-- scriv-insert-here -->
 
+<a id='changelog-2.1.1'></a>
+## 2.1.1 (2025-07-17)
+
+### Bug fixes
+
+- When adding or updating authors in `technote.toml`, Documenteer avoids setting null values. TOML represents null values as absent keys, but previous versions of Documenteer included null `ror` values.
+
+<a id='changelog-2.1.0'></a>
+## 2.1.0 (2025-07-16)
+
+### New features
+
+- Improved and extended the nitpick ignore configurations for both user guides and technotes. The new configuration engine uses a common set of utility functions to generate the ignore patterns. Additionally, Documenteer makes better use of regex patterns to ignore linking issues to APIs that are not documented with Sphinx, such as `fastapi`, `httpx`, and `pydantic`. This should reduce the number of nitpick warnings in user guides and technotes, and generally reduce the need for manual nitpick ignores in projects.
+
+- Added [`sphinx-sitemap`](https://sphinx-sitemap.readthedocs.io/en/latest/index.html) for generating sitemaps in Rubin user guides and technotes. This will improve search engine and LLM/agent indexing of documentation. In user guides, the sitemap is linked in the HTML `head` for better discoverability.
+- A new extension, `documenteer.ext.robots`, helps you generate a `robots.txt` file to inform web crawlers about access to documentation sites. In this initial version, the `robots.txt` file is generated when a `sitemap.xml` file is available in order to link to that sitemap. The extension won't overwrite an existing `robots.txt` file.
+- Documenteer's Sphinx extensions (`documenteer.ext.*`) now use Sphinx's built-in logging system, `sphinx.util.logging`, instead of the standard Python logging module.
+
+- Rubin user guides (`documenteer.conf.guide`) now include Plausible.io analytics integration for privacy-preserving website analytics. The Plausible domain is configured by default to `lsst.io`, which is the common tracking domain for all Rubin Observatory technical documentation.
+
+### Bug fixes
+
+- The Redoc site extension (`documenteer.ext.redoc`) now skips rendering early if the OpenAPI configuration is an empty list to avoid unnecessary processing.
+
+<a id='changelog-2.0.0'></a>
+## 2.0.0 (2025-07-10)
+
+### Backwards-incompatible changes
+
+- All Science Pipelines-related tooling and Sphinx extensions have been removed from Documenteer and moved to a new Science Pipelines package called `sphinxutils` (https://github.com/lsst-dm/sphinxutils). Removed components include:
+
+  - `documenteer.stackdocs`
+  - Configurations `documenteer.conf.pipelines` and `documenteer.conf.pipelinespkg`
+  - CLI commands `stack-docs` and `package-docs`
+  - Sphinx extensions:
+    - `documenteer.ext.lssttasks`
+    - `documenteer.ext.packagetoctree`
+    - `documenteer.ext.autocppapi`
+    - `documenteer.ext.autodocreset`
+
+- Dropped support for Python 3.11. Python 3.12 or later is now required.
+
+- Removed `documenteer.requestutils`, `documenteer.packagemetadata`, and `documenteer.utils` from the public API.
+
+### New features
+
+- User guide configuration improvements:
+
+  - New custom automodapi templates for Pydantic BaseModels and exceptions. The exception template ensures that inherited members of exceptions are documented. The Pydantic BaseModel template ensures that inherited members from the `BaseModel` class itself are _not_ documented. These templates were originally developed as part of [Gafaelfawr](https://github.com/lsst-sqre/gafaelfawr). Now users of the user guide configuration benefit from these templates without any additional configuration.
+
+  - The `[guide]` installation extra and `documenteer.conf.guide` configuration now include `autodoc_pydantic` for improved documentation of Pydantic models in Python API references.
+
+  - The `documenteer.conf.guide` configuration now ignores common Sphinx warnings when including references to projects that don't use Sphinx/Intersphinx for their documentation, including Pydantic and FastAPI.
+
+  - Updated to pydata-sphinx-theme 0.16.
+
+  - Added [sphinx-favicon](https://sphinx-favicon.readthedocs.io/en/stable/index.html) for managing favicons in user guides.
+
+  - For embedding a redoc page for API documentation, Documenteer now provides its own `documenteer.ext.redoc` extension. This replaces the previous `sphinxcontrib.redoc` extension, which is not being actively maintained. This new extension is automatically configured through `documenteer.conf.guide`, and therefore should not require any changes for most user guide projects. `documenteer.ext.redoc` drops support for referencing an OpenAPI specification file from a web URL. FastAPI projects can use `documenteer.ext.openapi` to generate an OpenAPI specification file from the FastAPI app.
+
+- In Markdown content for technotes and guides, Mermaid diagrams can now be written in code fences using the `mermaid` language tag. This is also supported in GitHub's Markdown renderer. The traditional method of using the `mermaid` directive syntax is still supported.
+
+- Documenteer's `technote` and `guide` configurations now ignore pending Sphinx API deprecation warnings by default. This is to prevent the warnings from cluttering the build output, and are only useful for the Documenteer developers since the Sphinx version is constrained by Documenteer.
+
+- The `documenteer` `add-authors` and `sync-authors` CLI commands now use the Ook web API to get author information, rather than directly reading `authordb.yaml` from lsst/lsst-texmf.
+
+- The entire `documenteer` code base is now type annotated.
+
+### Bug fixes
+
+- Updated `sphinxcontrib-mermaid` to >= 1, which fixes an incompatibility with Sphinx 8.1.0 and allows unpinning the Mermaid JS version.
+
+- Pinned Sphinx < 8.2 to avoid a bug/incompatibility with the `sphinxcontrib-bibtex` extension.
+
+- Documenteer's Sphinx extensions now provide proper extension metadata to support version-based cache busting and parallel builds.
+
+### Other changes
+
+- The code base is now linted and formatted with ruff.
+
+- Added testing against Sphinx 8 and Python 3.13 in GitHub Actions.
+
+- Updated the technote creation documentation to reference `@Squarebot`, updated from `sqrbot-jr`.
+
+- Removed the pre-commit hook for prettier and now run prettier directly from the tox lint environment. This change is necessary because the prettier hook for pre-commit is no longer supported.
+
+- Adopted [ts-graphviz/setup-graphviz](https://github.com/ts-graphviz/setup-graphviz) for installing Graphviz in GitHub Actions CI workflows.
+
+- Updated how license information is encoded in `pyproject.toml`.
+
+- Switched to dependency groups for development dependencies in `pyproject.toml`. With this change, Documenteer no longer publishes a `dev` extra to PyPI.
+
+- Documenteer no longer depends on setuptools as a runtime dependency thanks to pybtex version 0.25 and `documenteer.ext.redoc`.
+
+<a id='changelog-1.4.5'></a>
+## 1.4.5 (2025-06-25)
+
+### Other changes
+
+- Update to lsst-sqre/build-and-publish-to-pypi@v3 for publishing to PyPI.
+
+<a id='changelog-1.4.4'></a>
+## 1.4.4 (2025-06-25)
+
+### Bug fixes
+
+- Fix the configuration of the `sphinx-prompt` extension to be `sphinx_prompt` in the `documenteer.conf.guide` configuration. Constrain the sphinx-prompt version to be `>1.10.0,<2.0.0` to avoid issues with the `sphinx_prompt` extension not being recognized.
+
+### Other changes
+
+- Add testing against Python 3.13 and Sphinx 8.
+
+<a id='changelog-1.4.3'></a>
+## 1.4.3 (2025-02-19)
+
+### Bug fixes
+
+- Pin Sphinx < 8.2 to avoid a bug/incompatibility with the `sphinxcontrib-bibtex` extension.
+
+### Other changes
+
+- Prettier is now run directly through the tox lint environment rather than through pre-commit since the pre-commit plugin is deprecated and no longer operable.
+
+<a id='changelog-1.4.2'></a>
+## 1.4.2 (2024-10-15)
+
+### Bug fixes
+
+- Pin `sphinxcontrib-mermaid` to >= 1 to address an incompatibility with Sphinx==8.1.0. Also unpin the version of Mermaid itself.
+
+<a id='changelog-1.4.1'></a>
+## 1.4.1 (2024-10-10)
+
+### Bug fixes
+
+- Pin Sphinx to < 8.1.0. [Sphinx 8.1.0](https://github.com/sphinx-doc/sphinx/compare/v8.0.2...v8.1.0) contains [a commit](https://github.com/sphinx-doc/sphinx/pull/12762/files#diff-a4c6bf1492ef480b94af82c988f64ca56fa256fab0ed043a5ad3d4043f89a645L14) that removes the `ExtensionError` export from the `sphinx.util` package. This currently breaks the [sphinxcontrib-mermaid](https://github.com/mgaitan/sphinxcontrib-mermaid) dependency.
+
 <a id='changelog-1.4.0'></a>
 ## 1.4.0 (2024-07-11)
 

{documenteer-2.0.0a4 → documenteer-2.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: documenteer
-Version: 2.0.0a4
+Version: 2.1.1
 Summary: Rubin Observatory / LSST Sphinx documentation tools, extensions, and configurations.
 License-Expression: MIT
 Project-URL: Homepage, https://documenteer.lsst.io
@@ -57,6 +57,7 @@ Requires-Dist: sphinxcontrib-jquery; extra == "guide"
 Requires-Dist: sphinxext-rediraffe; extra == "guide"
 Requires-Dist: sphinxcontrib-youtube; extra == "guide"
 Requires-Dist: sphinx-favicon; extra == "guide"
+Requires-Dist: sphinx-sitemap; extra == "guide"
 Provides-Extra: technote
 Requires-Dist: technote<0.10.0,>=0.9.0; extra == "technote"
 Requires-Dist: sphinx-prompt; extra == "technote"
@@ -65,18 +66,19 @@ Requires-Dist: sphinx-diagrams; extra == "technote"
 Requires-Dist: sphinx_design; extra == "technote"
 Requires-Dist: myst-nb; extra == "technote"
 Requires-Dist: sphinxcontrib-youtube; extra == "technote"
+Requires-Dist: sphinx-sitemap; extra == "technote"
 Dynamic: license-file
 
 [![Documentation](https://img.shields.io/badge/documenteer-lsst.io-brightgreen.svg)](https://documenteer.lsst.io)
 [![PyPI](https://img.shields.io/pypi/v/documenteer.svg?style=flat-square)](https://pypi.python.org/pypi/documenteer)
-[![For Python 3.7+](https://img.shields.io/pypi/pyversions/documenteer.svg?style=flat-square)](https://pypi.python.org/pypi/documenteer)
+[![For Python 3.12+](https://img.shields.io/pypi/pyversions/documenteer.svg?style=flat-square)](https://pypi.python.org/pypi/documenteer)
 [![MIT license](https://img.shields.io/pypi/l/documenteer.svg?style=flat-square)](https://pypi.python.org/pypi/documenteer)
 [![CI](https://github.com/lsst-sqre/documenteer/actions/workflows/ci.yaml/badge.svg)](https://github.com/lsst-sqre/documenteer/actions/workflows/ci.yaml)
 [![Weekly CI](https://github.com/lsst-sqre/documenteer/actions/workflows/ci-cron.yaml/badge.svg)](https://github.com/lsst-sqre/documenteer/actions/workflows/ci-cron.yaml)
 
 # Documenteer
 
-Documenteer provides tools, extensions, and configurations for Rubin Observatory's Sphinx documentation projects, [user guides](https://documenteer.lsst.io/guides/index.html), [technotes](https://developer.lsst.io/project-docs/technotes.html) and EUPS-packaged stacks (such as the [LSST Science Pipelines](https://pipelines.lsst.io)).
+Documenteer provides tools, extensions, and configurations for Rubin Observatory's Sphinx documentation projects, including [user guides](https://documenteer.lsst.io/guides/index.html) and [technotes](https://developer.lsst.io/project-docs/technotes.html).
 
 For more information about Documenteer, see the documentation at https://documenteer.lsst.io.
 
@@ -95,9 +97,3 @@ For [technical note projects](https://documenteer.lsst.io/technotes/index.html):
 ```sh
 pip install "documenteer[technote]"
 ```
-
-For the [stack projects](https://documenteer.lsst.io/pipelines/index.html) (such as the [LSST Science Pipelines](https://pipelines.lsst.io)):
-
-```sh
-pip install "documenteer[pipelines]"
-```

{documenteer-2.0.0a4 → documenteer-2.1.1}/README.md

@@ -1,13 +1,13 @@
 [![Documentation](https://img.shields.io/badge/documenteer-lsst.io-brightgreen.svg)](https://documenteer.lsst.io)
 [![PyPI](https://img.shields.io/pypi/v/documenteer.svg?style=flat-square)](https://pypi.python.org/pypi/documenteer)
-[![For Python 3.7+](https://img.shields.io/pypi/pyversions/documenteer.svg?style=flat-square)](https://pypi.python.org/pypi/documenteer)
+[![For Python 3.12+](https://img.shields.io/pypi/pyversions/documenteer.svg?style=flat-square)](https://pypi.python.org/pypi/documenteer)
 [![MIT license](https://img.shields.io/pypi/l/documenteer.svg?style=flat-square)](https://pypi.python.org/pypi/documenteer)
 [![CI](https://github.com/lsst-sqre/documenteer/actions/workflows/ci.yaml/badge.svg)](https://github.com/lsst-sqre/documenteer/actions/workflows/ci.yaml)
 [![Weekly CI](https://github.com/lsst-sqre/documenteer/actions/workflows/ci-cron.yaml/badge.svg)](https://github.com/lsst-sqre/documenteer/actions/workflows/ci-cron.yaml)
 
 # Documenteer
 
-Documenteer provides tools, extensions, and configurations for Rubin Observatory's Sphinx documentation projects, [user guides](https://documenteer.lsst.io/guides/index.html), [technotes](https://developer.lsst.io/project-docs/technotes.html) and EUPS-packaged stacks (such as the [LSST Science Pipelines](https://pipelines.lsst.io)).
+Documenteer provides tools, extensions, and configurations for Rubin Observatory's Sphinx documentation projects, including [user guides](https://documenteer.lsst.io/guides/index.html) and [technotes](https://developer.lsst.io/project-docs/technotes.html).
 
 For more information about Documenteer, see the documentation at https://documenteer.lsst.io.
 
@@ -26,9 +26,3 @@ For [technical note projects](https://documenteer.lsst.io/technotes/index.html):
 ```sh
 pip install "documenteer[technote]"
 ```
-
-For the [stack projects](https://documenteer.lsst.io/pipelines/index.html) (such as the [LSST Science Pipelines](https://pipelines.lsst.io)):
-
-```sh
-pip install "documenteer[pipelines]"
-```

{documenteer-2.0.0a4 → documenteer-2.1.1}/docs/changelog.md

@@ -2,6 +2,143 @@
 
 <!-- scriv-insert-here -->
 
+<a id='changelog-2.1.1'></a>
+## 2.1.1 (2025-07-17)
+
+### Bug fixes
+
+- When adding or updating authors in `technote.toml`, Documenteer avoids setting null values. TOML represents null values as absent keys, but previous versions of Documenteer included null `ror` values.
+
+<a id='changelog-2.1.0'></a>
+## 2.1.0 (2025-07-16)
+
+### New features
+
+- Improved and extended the nitpick ignore configurations for both user guides and technotes. The new configuration engine uses a common set of utility functions to generate the ignore patterns. Additionally, Documenteer makes better use of regex patterns to ignore linking issues to APIs that are not documented with Sphinx, such as `fastapi`, `httpx`, and `pydantic`. This should reduce the number of nitpick warnings in user guides and technotes, and generally reduce the need for manual nitpick ignores in projects.
+
+- Added [`sphinx-sitemap`](https://sphinx-sitemap.readthedocs.io/en/latest/index.html) for generating sitemaps in Rubin user guides and technotes. This will improve search engine and LLM/agent indexing of documentation. In user guides, the sitemap is linked in the HTML `head` for better discoverability.
+- A new extension, `documenteer.ext.robots`, helps you generate a `robots.txt` file to inform web crawlers about access to documentation sites. In this initial version, the `robots.txt` file is generated when a `sitemap.xml` file is available in order to link to that sitemap. The extension won't overwrite an existing `robots.txt` file.
+- Documenteer's Sphinx extensions (`documenteer.ext.*`) now use Sphinx's built-in logging system, `sphinx.util.logging`, instead of the standard Python logging module.
+
+- Rubin user guides (`documenteer.conf.guide`) now include Plausible.io analytics integration for privacy-preserving website analytics. The Plausible domain is configured by default to `lsst.io`, which is the common tracking domain for all Rubin Observatory technical documentation.
+
+### Bug fixes
+
+- The Redoc site extension (`documenteer.ext.redoc`) now skips rendering early if the OpenAPI configuration is an empty list to avoid unnecessary processing.
+
+<a id='changelog-2.0.0'></a>
+## 2.0.0 (2025-07-10)
+
+### Backwards-incompatible changes
+
+- All Science Pipelines-related tooling and Sphinx extensions have been removed from Documenteer and moved to a new Science Pipelines package called `sphinxutils` (https://github.com/lsst-dm/sphinxutils). Removed components include:
+
+  - `documenteer.stackdocs`
+  - Configurations `documenteer.conf.pipelines` and `documenteer.conf.pipelinespkg`
+  - CLI commands `stack-docs` and `package-docs`
+  - Sphinx extensions:
+    - `documenteer.ext.lssttasks`
+    - `documenteer.ext.packagetoctree`
+    - `documenteer.ext.autocppapi`
+    - `documenteer.ext.autodocreset`
+
+- Dropped support for Python 3.11. Python 3.12 or later is now required.
+
+- Removed `documenteer.requestutils`, `documenteer.packagemetadata`, and `documenteer.utils` from the public API.
+
+### New features
+
+- User guide configuration improvements:
+
+  - New custom automodapi templates for Pydantic BaseModels and exceptions. The exception template ensures that inherited members of exceptions are documented. The Pydantic BaseModel template ensures that inherited members from the `BaseModel` class itself are _not_ documented. These templates were originally developed as part of [Gafaelfawr](https://github.com/lsst-sqre/gafaelfawr). Now users of the user guide configuration benefit from these templates without any additional configuration.
+
+  - The `[guide]` installation extra and `documenteer.conf.guide` configuration now include `autodoc_pydantic` for improved documentation of Pydantic models in Python API references.
+
+  - The `documenteer.conf.guide` configuration now ignores common Sphinx warnings when including references to projects that don't use Sphinx/Intersphinx for their documentation, including Pydantic and FastAPI.
+
+  - Updated to pydata-sphinx-theme 0.16.
+
+  - Added [sphinx-favicon](https://sphinx-favicon.readthedocs.io/en/stable/index.html) for managing favicons in user guides.
+
+  - For embedding a redoc page for API documentation, Documenteer now provides its own `documenteer.ext.redoc` extension. This replaces the previous `sphinxcontrib.redoc` extension, which is not being actively maintained. This new extension is automatically configured through `documenteer.conf.guide`, and therefore should not require any changes for most user guide projects. `documenteer.ext.redoc` drops support for referencing an OpenAPI specification file from a web URL. FastAPI projects can use `documenteer.ext.openapi` to generate an OpenAPI specification file from the FastAPI app.
+
+- In Markdown content for technotes and guides, Mermaid diagrams can now be written in code fences using the `mermaid` language tag. This is also supported in GitHub's Markdown renderer. The traditional method of using the `mermaid` directive syntax is still supported.
+
+- Documenteer's `technote` and `guide` configurations now ignore pending Sphinx API deprecation warnings by default. This is to prevent the warnings from cluttering the build output, and are only useful for the Documenteer developers since the Sphinx version is constrained by Documenteer.
+
+- The `documenteer` `add-authors` and `sync-authors` CLI commands now use the Ook web API to get author information, rather than directly reading `authordb.yaml` from lsst/lsst-texmf.
+
+- The entire `documenteer` code base is now type annotated.
+
+### Bug fixes
+
+- Updated `sphinxcontrib-mermaid` to >= 1, which fixes an incompatibility with Sphinx 8.1.0 and allows unpinning the Mermaid JS version.
+
+- Pinned Sphinx < 8.2 to avoid a bug/incompatibility with the `sphinxcontrib-bibtex` extension.
+
+- Documenteer's Sphinx extensions now provide proper extension metadata to support version-based cache busting and parallel builds.
+
+### Other changes
+
+- The code base is now linted and formatted with ruff.
+
+- Added testing against Sphinx 8 and Python 3.13 in GitHub Actions.
+
+- Updated the technote creation documentation to reference `@Squarebot`, updated from `sqrbot-jr`.
+
+- Removed the pre-commit hook for prettier and now run prettier directly from the tox lint environment. This change is necessary because the prettier hook for pre-commit is no longer supported.
+
+- Adopted [ts-graphviz/setup-graphviz](https://github.com/ts-graphviz/setup-graphviz) for installing Graphviz in GitHub Actions CI workflows.
+
+- Updated how license information is encoded in `pyproject.toml`.
+
+- Switched to dependency groups for development dependencies in `pyproject.toml`. With this change, Documenteer no longer publishes a `dev` extra to PyPI.
+
+- Documenteer no longer depends on setuptools as a runtime dependency thanks to pybtex version 0.25 and `documenteer.ext.redoc`.
+
+<a id='changelog-1.4.5'></a>
+## 1.4.5 (2025-06-25)
+
+### Other changes
+
+- Update to lsst-sqre/build-and-publish-to-pypi@v3 for publishing to PyPI.
+
+<a id='changelog-1.4.4'></a>
+## 1.4.4 (2025-06-25)
+
+### Bug fixes
+
+- Fix the configuration of the `sphinx-prompt` extension to be `sphinx_prompt` in the `documenteer.conf.guide` configuration. Constrain the sphinx-prompt version to be `>1.10.0,<2.0.0` to avoid issues with the `sphinx_prompt` extension not being recognized.
+
+### Other changes
+
+- Add testing against Python 3.13 and Sphinx 8.
+
+<a id='changelog-1.4.3'></a>
+## 1.4.3 (2025-02-19)
+
+### Bug fixes
+
+- Pin Sphinx < 8.2 to avoid a bug/incompatibility with the `sphinxcontrib-bibtex` extension.
+
+### Other changes
+
+- Prettier is now run directly through the tox lint environment rather than through pre-commit since the pre-commit plugin is deprecated and no longer operable.
+
+<a id='changelog-1.4.2'></a>
+## 1.4.2 (2024-10-15)
+
+### Bug fixes
+
+- Pin `sphinxcontrib-mermaid` to >= 1 to address an incompatibility with Sphinx==8.1.0. Also unpin the version of Mermaid itself.
+
+<a id='changelog-1.4.1'></a>
+## 1.4.1 (2024-10-10)
+
+### Bug fixes
+
+- Pin Sphinx to < 8.1.0. [Sphinx 8.1.0](https://github.com/sphinx-doc/sphinx/compare/v8.0.2...v8.1.0) contains [a commit](https://github.com/sphinx-doc/sphinx/pull/12762/files#diff-a4c6bf1492ef480b94af82c988f64ca56fa256fab0ed043a5ad3d4043f89a645L14) that removes the `ExtensionError` export from the `sphinx.util` package. This currently breaks the [sphinxcontrib-mermaid](https://github.com/mgaitan/sphinxcontrib-mermaid) dependency.
+
 <a id='changelog-1.4.0'></a>
 ## 1.4.0 (2024-07-11)
 

{documenteer-2.0.0a4 → documenteer-2.1.1}/docs/dev/api/index.rst

@@ -7,4 +7,3 @@ Python API
 
    documenteer.conf
    documenteer.ext
-   documenteer.requestsutils

{documenteer-2.0.0a4 → documenteer-2.1.1}/pyproject.toml

@@ -62,7 +62,8 @@ guide = [
     "sphinxcontrib-jquery",
     "sphinxext-rediraffe",
     "sphinxcontrib-youtube",
-    "sphinx-favicon"
+    "sphinx-favicon",
+    "sphinx-sitemap",
 ]
 technote = [
     # Theme and extensions for technotes
@@ -72,7 +73,8 @@ technote = [
     "sphinx-diagrams",
     "sphinx_design",
     "myst-nb",
-    "sphinxcontrib-youtube"
+    "sphinxcontrib-youtube",
+    "sphinx-sitemap",
 ]
 
 [dependency-groups]

{documenteer-2.0.0a4 → documenteer-2.1.1}/src/documenteer/conf/_utils.py

@@ -8,14 +8,16 @@ from git import Repo
 from sphinx.errors import ConfigError
 
 __all__ = [
-    "get_asset_path",
+    "GitRepository",
     "extend_static_paths_with_asset_extension",
+    "get_asset_path",
+    "get_common_nitpick_ignore",
+    "get_common_nitpick_ignore_regex",
     "get_template_dir",
-    "GitRepository",
 ]
 
 
-def _get_assert_dir() -> Path:
+def _get_assets_directory() -> Path:
     """Get the absolute path to the Documenteer assets directory."""
     return Path(__file__).parent.joinpath("../assets")
 
@@ -44,7 +46,7 @@ def get_asset_path(name: str) -> str:
            get_asset_path("rubin-titlebar-imagotype-light.svg"),
        ]
     """
-    asset_path = _get_assert_dir().joinpath(name).resolve()
+    asset_path = _get_assets_directory().joinpath(name).resolve()
     if not asset_path.exists():
         raise ConfigError(
             f"Documenteer asset {name!r} does not exist.\n"
@@ -60,7 +62,7 @@ def extend_static_paths_with_asset_extension(
     """Extend a Sphinx ``html_static_path`` configuration list with the
     files of a given extension in Documenteer's assets directory.
     """
-    asset_dir = _get_assert_dir()
+    asset_dir = _get_assets_directory()
     new_paths = [str(p) for p in asset_dir.glob(f"*.{extension}")]
     html_static_path.extend(new_paths)
 
@@ -144,3 +146,69 @@ def extend_excludes_for_non_index_source(
     for p in cwd.glob(f"**/*.{extension}"):
         if p.name != f"index.{extension}":
             exclude_patterns.append(str(p.relative_to(cwd)))  # noqa: PERF401
+
+
+def get_common_nitpick_ignore() -> list[tuple[str, str]]:
+    """Get a list of common nitpick ignore tuples for Sphinx.
+
+    This is useful for ignoring common warnings that are not relevant to
+    the documentation project.
+
+    Returns
+    -------
+    list[tuple[str, str]]
+        A list of tuples where each tuple contains the domain and the target
+        to ignore.
+    """
+    return [
+        # Ignore missing cross-references for modules that don't provide
+        # intersphinx.  The documentation itself should use double-quotes
+        # instead of single-quotes to not generate a reference, but automatic
+        # references are generated from the type signatures and can't be
+        # avoided.
+        ("py:obj", "ConfigDict"),
+        (
+            "py:obj",
+            "safir.pydantic.validate_exactly_one_of.<locals>.validator",
+        ),
+        # asyncio.Lock is documented, and that's what all the code references,
+        # but the combination of Sphinx extensions we're using confuse
+        # themselves and there doesn't seem to be any way to fix this.
+        ("py:class", "asyncio.locks.Lock"),
+        ("py:class", "pathlib._local.Path"),
+    ]
+
+
+def get_common_nitpick_ignore_regex() -> list[tuple[str, str]]:
+    """Get a list of common nitpick ignore regex tuples for Sphinx.
+
+    This is useful for ignoring common warnings that are not relevant to
+    the documentation project.
+
+    Returns
+    -------
+    list[tuple[str, str]]
+        A list of tuples where each tuple contains the domain and the target
+        to ignore.
+    """
+    # These packages aren't documented with Sphinx, so we can't link to them
+    # with intersphinx.
+    packages = [
+        "fastapi",
+        "httpx",
+        "kubernetes_asyncio",
+        "pydantic",
+        "pydantic_settings",
+        "starlette",
+    ]
+    patterns = [("py:*", rf"{package}(?:\..*)?") for package in packages]
+
+    # Additional patterns that are common to ignore.
+    patterns.extend(
+        [
+            # Bug in sphinx.ext.autodoc for pydantic models.
+            ("py:*", r".*\.all fields"),
+        ]
+    )
+
+    return patterns

{documenteer-2.0.0a4 → documenteer-2.1.1}/src/documenteer/conf/guide.py

@@ -16,6 +16,10 @@ from documenteer.conf import (
     get_asset_path,
     get_template_dir,
 )
+from documenteer.conf._utils import (
+    get_common_nitpick_ignore,
+    get_common_nitpick_ignore_regex,
+)
 
 # This configuration is broken down into these sections:
 #
@@ -85,6 +89,9 @@ __all__ = [
     "html_css_files",
     "html_show_sourcelink",
     "favicons",
+    "sitemap_url_scheme",
+    "sitemap_show_lastmod",
+    "sitemap_excludes",
     # API
     "automodapi_toctreedirnm",
     "always_document_param_types",
@@ -159,6 +166,8 @@ extensions = [
     "sphinx_automodapi.automodapi",
     "sphinx_automodapi.smart_resolver",
     "sphinx_favicon",
+    "sphinx_sitemap",
+    "documenteer.ext.robots",
     "documenteer.ext.jira",
     "documenteer.ext.lsstdocushare",
     "documenteer.ext.mockcoderefs",
@@ -215,52 +224,10 @@ default_role = "py:obj"
 nitpicky = _conf.nitpicky
 
 # Warnings to ignore
-nitpick_ignore: list[tuple[str, str]] = [
-    # Ignore missing cross-references for modules that don't provide
-    # intersphinx.  The documentation itself should use double-quotes instead
-    # of single-quotes to not generate a reference, but automatic references
-    # are generated from the type signatures and can't be avoided.
-    ("py:class", "fastapi.applications.FastAPI"),
-    ("py:class", "fastapi.datastructures.DefaultPlaceholder"),
-    ("py:class", "fastapi.exceptions.HTTPException"),
-    ("py:class", "fastapi.params.Depends"),
-    ("py:class", "fastapi.routing.APIRoute"),
-    ("py:class", "httpx.AsyncClient"),
-    ("py:exc", "fastapi.HTTPException"),
-    ("py:exc", "fastapi.exceptions.RequestValidationError"),
-    ("py:exc", "httpx.HTTPError"),
-    ("py:obj", "ConfigDict"),
-    ("py:obj", "fastapi.routing.APIRoute"),
-    ("py:class", "kubernetes_asyncio.client.api_client.ApiClient"),
-    ("py:class", "pydantic.main.BaseModel"),
-    ("py:class", "pydantic.networks.AnyHttpUrl"),
-    ("py:class", "pydantic.networks.IPvAnyNetwork"),
-    ("py:class", "pydantic.types.SecretStr"),
-    ("py:class", "pydantic.utils.Representation"),
-    ("py:class", "pydantic_core._pydantic_core.Url"),
-    ("py:class", "pydantic_core._pydantic_core.ValidationError"),
-    ("py:class", "pydantic_settings.main.BaseSettings"),
-    ("py:class", "pydantic_settings.sources.CliSettingsSource"),
-    ("py:obj", "safir.pydantic.validate_exactly_one_of.<locals>.validator"),
-    ("py:class", "starlette.datastructures.URL"),
-    ("py:class", "starlette.middleware.base.BaseHTTPMiddleware"),
-    ("py:class", "starlette.requests.Request"),
-    ("py:class", "starlette.responses.Response"),
-    ("py:class", "starlette.routing.Route"),
-    ("py:class", "starlette.routing.BaseRoute"),
-    ("py:exc", "starlette.exceptions.HTTPException"),
-    # asyncio.Lock is documented, and that's what all the code references, but
-    # the combination of Sphinx extensions we're using confuse themselves and
-    # there doesn't seem to be any way to fix this.
-    ("py:class", "asyncio.locks.Lock"),
-]
+nitpick_ignore = get_common_nitpick_ignore()
 _conf.append_nitpick_ignore(nitpick_ignore)
 
-nitpick_ignore_regex: list[tuple[str, str]] = [
-    ("py:class", r"kubernetes_asyncio\.client\.models\..*"),
-    # Bug in autodoc_pydantic.
-    ("py:obj", r".*\.all fields"),
-]
+nitpick_ignore_regex = get_common_nitpick_ignore_regex()
 _conf.append_nitpick_ignore_regex(nitpick_ignore_regex)
 
 # A list of paths that contain extra templates (or templates that overwrite
@@ -319,6 +286,10 @@ html_theme_options = {
     },
     "pygments_light_style": "xcode",
     "pygments_dark_style": "github-dark",
+    "analytics": {
+        "plausible_analytics_domain": "lsst.io",
+        "plausible_analytics_url": "https://plausible.io/js/script.file-downloads.hash.outbound-links.js",
+    },
 }
 
 if _conf.github_url:
@@ -384,6 +355,13 @@ html_css_files = ["rubin-pydata-theme.css"]
 # If true, links to the reST sources are added to the pages.
 html_show_sourcelink = False
 
+# Sitemap generation
+sitemap_url_scheme = "{link}"
+sitemap_show_lastmod = True
+sitemap_excludes = [
+    "search.html",
+]
+
 # ============================================================================
 # #API API reference configurations
 # ============================================================================

{documenteer-2.0.0a4 → documenteer-2.1.1}/src/documenteer/conf/technote.py

@@ -14,6 +14,8 @@ from documenteer.conf import (
     get_template_dir,
 )
 
+from ._utils import get_common_nitpick_ignore, get_common_nitpick_ignore_regex
+
 # Suppress warnings about deprecated features in future Sphinx versions.
 # This is noise for users because Documenteer itself constrains the Sphinx
 # version.
@@ -50,6 +52,7 @@ extensions.extend(  # noqa: F405
         "sphinx_prompt",
         "sphinx_design",
         "sphinxcontrib.youtube",
+        "sphinx_sitemap",
     ]
 )
 
@@ -119,3 +122,17 @@ if _id is not None:
     html_context["editions_url"] = (  # noqa: F405
         f"https://{_id.lower()}.lsst.io/v/"
     )
+
+nitpick_ignore_regex.extend(get_common_nitpick_ignore_regex())  # noqa: F405
+nitpick_ignore.extend(get_common_nitpick_ignore())  # noqa: F405
+
+# Configure sitemap.xml
+sitemap_url_scheme = "{link}"
+sitemap_show_lastmod = True
+sitemap_excludes = [
+    # These auto-generated pages aren't relevant in technotes, which are
+    # meant to be single-page documents.
+    "search.html",
+    "genindex.html",
+    "py-modindex.html",
+]

{documenteer-2.0.0a4 → documenteer-2.1.1}/src/documenteer/ext/jira.py

@@ -4,18 +4,17 @@ This module is heavily influenced by sphinx-issue (Steven Loria). See
 /licenses/sphinx-issue.txt for licensing information.
 """
 
-import logging
 from typing import Any
 
 from docutils import nodes, utils
 from docutils.parsers.rst.states import Inliner
 from sphinx.application import Sphinx
+from sphinx.util.logging import getLogger
 from sphinx.util.typing import ExtensionMetadata
 
 from ..version import __version__
 
-log = logging.getLogger(__name__)
-log.addHandler(logging.NullHandler())
+log = getLogger(__name__)
 
 
 def _make_ticket_node(