documenteer 2.2.0__tar.gz → 2.3.0__tar.gz

documenteer-2.3.0/.claude/.gitignore

@@ -0,0 +1,2 @@
+settings.local.json
+tasks/*.md

{documenteer-2.2.0 → documenteer-2.3.0}/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 <!-- scriv-insert-here -->
 
+<a id='changelog-2.3.0'></a>
+## 2.3.0 (2025-09-03)
+
+### New features
+
+- Improved configuration defaults for `documenteer.conf.guide` and `documenteer.conf.technote`:
+
+  - Add `sentry_sdk` to default non-intersphinx packages
+  - Ignore `TypeAliasType` due to sphinx bug
+  - Ignore `asyncio.Event`, it has the same problem as `asyncio.Lock`
+
+- [ASCL](https://ascl.net) identifiers in bibliography entries are now hyperlinked.
+
+### Bug fixes
+
+- Vendored `parse_line_num_spec` from Sphinx to accommodate differences between Sphinx 7 and 8.
+- Fix `nitpick_ignore_regex` regexes, they weren't being applied due to a missing `.`
+
+### Other changes
+
+- Added documentation on creating bibliographies in technotes.
+
 <a id='changelog-2.2.0'></a>
 ## 2.2.0 (2025-08-06)
 

documenteer-2.3.0/CLAUDE.md

@@ -0,0 +1,98 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Documenteer is a Python package that provides Sphinx documentation tools, extensions, and configurations for Rubin Observatory/LSST projects. It supports two main documentation types:
+- **User guides**: Complete documentation sites using pydata-sphinx-theme
+- **Technotes**: Single-document technical notes using the technote theme
+
+## Development Commands
+
+### Setup and Installation
+```bash
+make init                    # Initialize development environment
+pip install -e ".[technote,guide]" --group dev  # Install with all extras
+```
+
+### Testing and Quality Assurance
+```bash
+tox -e py-test-sphinx8      # Run tests with Sphinx 8.x
+tox -e coverage-report      # Generate coverage report
+tox -e typing-sphinx8       # Run mypy type checking
+tox -e lint                 # Run linting (pre-commit hooks + prettier)
+tox -e demo                 # Build demo technote projects (end-to-end test)
+tox -e packaging            # Check PyPI packaging
+```
+
+### Documentation
+```bash
+tox -e docs                 # Build documentation
+tox -e docs-lint            # Check documentation links
+```
+
+### Cleanup
+```bash
+make clean                  # Remove build artifacts
+```
+
+## Architecture
+
+### Core Components
+
+**Configuration System** (`src/documenteer/conf/`):
+- `guide.py`: Sphinx configuration preset for user guides
+- `technote.py`: Sphinx configuration preset for technotes
+- `_toml.py`: TOML-based configuration models using Pydantic
+- Uses pydata-sphinx-theme for guides, [technote](https://github.com/lsst-sqre/technote) package for technotes
+
+**Sphinx Extensions** (`src/documenteer/ext/`):
+- `jira.py`: JIRA ticket references
+- `lsstdocushare.py`: LSST DocuShare document links
+- `openapi.py`: OpenAPI documentation integration
+- `githubbibcache.py`: GitHub-based bibliography caching
+- `bibtex.py`: Enhanced BibTeX support
+- `remotecodeblock.py`: Remote code inclusion
+- `mockcoderefs.py`: Mock code references for testing
+- `redoc.py`: Redoc integration for HTTP API documentation
+- `robots.py`: robots.txt generation
+
+**CLI Tools** (`src/documenteer/cli.py`):
+- `technote add-author`: Add authors to technote.toml from authordb
+- `technote sync-authors`: Sync author info from central database
+- `technote migrate`: Migrate legacy technotes to modern format
+
+**Services** (`src/documenteer/services/`):
+- `technoteauthor.py`: Author management for technotes
+- `technotemigration.py`: Legacy technote migration logic
+
+### Key Design Patterns
+
+- **Configuration as Code**: Sphinx configurations are Python modules that can be imported
+- **Pydantic Models**: TOML configuration validation using type-safe models
+- **Extension Architecture**: Modular Sphinx extensions for specific Rubin/LSST needs
+- **Theme Integration**: Tight integration with pydata-sphinx-theme and technote themes
+
+### Testing Strategy
+
+- Uses tox for multi-environment testing across Sphinx versions
+- Sphinx test roots in `tests/roots/` for extension testing
+- Coverage reporting with branch coverage
+- Type checking with mypy
+- Pre-commit hooks for code quality
+
+### Code Style
+
+- Follows ruff formatting (run lint command to automatically format)
+- Numpydoc docstrings with types omitted (Sphinx documentation uses type annotations)
+
+### Asset Management
+
+Static assets are managed in `src/documenteer/assets/` including:
+- Custom CSS and SCSS for Rubin branding
+- JavaScript enhancements
+- Favicon and logo assets
+- Font files (Source Sans Pro)
+
+Built assets are compiled using webpack with PostCSS processing.

{documenteer-2.2.0 → documenteer-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: documenteer
-Version: 2.2.0
+Version: 2.3.0
 Summary: Rubin Observatory / LSST Sphinx documentation tools, extensions, and configurations.
 License-Expression: MIT
 Project-URL: Homepage, https://documenteer.lsst.io

{documenteer-2.2.0 → documenteer-2.3.0}/demo/rst-technote/index.rst

@@ -29,7 +29,7 @@ A list:
 - Second item
 - Third item
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin facilisis pharetra neque, at semper nulla mattis auctor. Proin semper mollis enim eget interdum. Mauris eleifend eget diam vitae bibendum. Praesent ut aliquet odio, sodales imperdiet nisi. Nam interdum imperdiet tortor sed fringilla. Maecenas efficitur mi sodales nulla commodo rutrum. Ut ornare diam quam, sed commodo turpis aliquam et. In nec enim consequat, suscipit tortor sit amet, luctus ante. Integer dictum augue diam, non pulvinar massa euismod in. Morbi viverra condimentum auctor. Nullam et metus mauris. Cras risus ex, porta sit amet nibh et, dapibus auctor leo.
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin facilisis pharetra neque, at semper nulla mattis auctor. Proin semper mollis enim eget interdum. Mauris eleifend eget diam vitae bibendum. Praesent ut aliquet odio, sodales imperdiet nisi. Nam interdum imperdiet tortor sed fringilla. Maecenas efficitur mi sodales nulla commodo rutrum. Ut ornare diam quam, sed commodo turpis aliquam et. In nec enim consequat, suscipit tortor sit amet, luctus ante. Integer dictum augue diam, non pulvinar massa euismod in. Morbi viverra condimentum auctor. Nullam et metus mauris. Cras risus ex, porta sit amet nibh et, dapibus auctor leo. :cite:`2010ascl.soft10043C`
 
 .. code-block:: python
    :caption: hello.py

documenteer-2.3.0/demo/rst-technote/local.bib

@@ -0,0 +1,10 @@
+@software{2010ascl.soft10043C,
+       author = {{Conroy}, Charlie and {Gunn}, James E.},
+        title = "{FSPS: Flexible Stellar Population Synthesis}",
+ howpublished = {Astrophysics Source Code Library, record ascl:1010.043},
+         year = 2010,
+        month = oct,
+          eid = {ascl:1010.043},
+       adsurl = {https://ui.adsabs.harvard.edu/abs/2010ascl.soft10043C},
+      adsnote = {Provided by the SAO/NASA Astrophysics Data System}
+}

{documenteer-2.2.0 → documenteer-2.3.0}/docs/changelog.md

@@ -2,6 +2,28 @@
 
 <!-- scriv-insert-here -->
 
+<a id='changelog-2.3.0'></a>
+## 2.3.0 (2025-09-03)
+
+### New features
+
+- Improved configuration defaults for `documenteer.conf.guide` and `documenteer.conf.technote`:
+
+  - Add `sentry_sdk` to default non-intersphinx packages
+  - Ignore `TypeAliasType` due to sphinx bug
+  - Ignore `asyncio.Event`, it has the same problem as `asyncio.Lock`
+
+- [ASCL](https://ascl.net) identifiers in bibliography entries are now hyperlinked.
+
+### Bug fixes
+
+- Vendored `parse_line_num_spec` from Sphinx to accommodate differences between Sphinx 7 and 8.
+- Fix `nitpick_ignore_regex` regexes, they weren't being applied due to a missing `.`
+
+### Other changes
+
+- Added documentation on creating bibliographies in technotes.
+
 <a id='changelog-2.2.0'></a>
 ## 2.2.0 (2025-08-06)
 

{documenteer-2.2.0 → documenteer-2.3.0}/docs/guides/configuration.rst

@@ -18,11 +18,14 @@ How you do this depends on your project's packaging structure:
       .. code-block:: toml
          :caption: pyproject.toml
 
-         [project.optional-dependencies]
-         dev = [
+         [dependency-groups]
+         docs = [
              "documenteer[guide]"
          ]
 
+      Dependency groups are a way organize development dependencies and are supported by `uv <https://docs.astral.sh/uv/concepts/projects/dependencies/#development-dependencies>`__.
+      Dependency groups are preferred over earlier methods of specifying optional dependencies because they are not published as installable dependencies from PyPI.
+
    .. tab-item:: requirements.txt
 
       .. code-block:: text

{documenteer-2.2.0 → documenteer-2.3.0}/docs/index.rst

@@ -56,15 +56,15 @@ Installation
 
       .. code-block:: sh
 
-         conda install documenteer
+         conda install lsst-documenteer
 
-      To use Documenteer's configurations for specific Rubin documentation use cases, you'll need to install Documenteer with specific "extras" to bring in the necessary dependencies.
-
-      To install Documenteer for technote projects:
+      For user guide projects:
 
       .. code-block:: sh
 
-         conda-install lsst-documenteer-technote
+         conda-install lsst-documenteer-guide
+
+      *Conda distributions aren't available for technote projects at this time.*
 
 Project guides
 ==============

{documenteer-2.2.0 → documenteer-2.3.0}/docs/technotes/_templates/README.md

@@ -16,7 +16,7 @@ A short description of this document.
 
 ## Build this technical note
 
-You can clone this repository and build the technote locally if your system has Python 3.11 or later:
+You can clone this repository and build the technote locally if your system has Python 3.12 or later:
 
 ```bash
 git clone https://github.com/lsst/example-000

{documenteer-2.2.0 → documenteer-2.3.0}/docs/technotes/_templates/README.rst

@@ -22,7 +22,7 @@ A short description of this document.
 Build this technical note
 =========================
 
-You can clone this repository and build the technote locally if your system has Python 3.11 or later:
+You can clone this repository and build the technote locally if your system has Python 3.12 or later:
 
 .. code-block:: bash
 

{documenteer-2.2.0 → documenteer-2.3.0}/docs/technotes/edit-locally.rst

@@ -34,7 +34,7 @@ Because of that, you don't need to rely on a specific Rubin Conda environment to
 .. important::
 
    Tox and pre-commit generally use the Python that they were installed with.
-   Documenteer requires Python 3.11 or later.
+   Documenteer requires Python 3.12 or later.
    To check what version of Python you have, run:
 
    .. prompt:: bash

{documenteer-2.2.0 → documenteer-2.3.0}/docs/technotes/index.rst

@@ -28,6 +28,7 @@ Documenteer provides centralized configuration and tooling for technotes.
    :maxdepth: 2
    :caption: Content & design
 
+   references
    wide-content
 
 .. toctree::

{documenteer-2.2.0 → documenteer-2.3.0}/docs/technotes/migrate.rst

@@ -235,6 +235,7 @@ Add the title to the top of the content:
 .. tab-set::
 
    .. tab-item:: rst
+      :sync: rst
 
       .. code-block:: rst
          :caption: index.rst
@@ -246,6 +247,7 @@ Add the title to the top of the content:
          [... content below ...]
 
    .. tab-item:: md
+      :sync: md
 
       .. code-block:: md
          :caption: index.md
@@ -268,6 +270,7 @@ The new technote format uses an ``abstract`` directive to mark up the abstract/s
 .. tab-set::
 
    .. tab-item:: rst
+      :sync: rst
 
       .. code-block:: rst
          :caption: index.rst
@@ -287,6 +290,7 @@ The new technote format uses an ``abstract`` directive to mark up the abstract/s
          [... content below ...]
 
    .. tab-item:: md
+      :sync: md
 
       .. code-block:: md
          :caption: index.md
@@ -311,6 +315,7 @@ In the new technote format, this section is simplified:
 .. tab-set::
 
    .. tab-item:: rst
+      :sync: rst
 
       .. code-block:: rst
          :caption: index.rst
@@ -323,6 +328,7 @@ In the new technote format, this section is simplified:
          .. bibliography::
 
    .. tab-item:: md
+      :sync: md
 
       .. code-block:: md
          :caption: index.md
@@ -476,12 +482,14 @@ Here is a suggested README template for technotes in the new format:
 .. tab-set::
 
    .. tab-item:: rst
+      :sync: rst
 
       .. literalinclude:: _templates/README.rst
          :language: rst
          :caption: README.rst
 
    .. tab-item:: md
+      :sync: md
 
       .. literalinclude:: _templates/README.md
          :language: md

documenteer-2.3.0/docs/technotes/references.rst

@@ -0,0 +1,135 @@
+#############################
+Citing references with BibTeX
+#############################
+
+Technotes include built-in support for citing references with BibTeX. Any bibitem from `lsst-texmf's bibliography files <https://github.com/lsst/lsst-texmf/tree/main/texmf/bibtex/bib>`__ is available for citation.
+You can also define your own BibTeX entries in a local bib files.
+
+Set up references section
+=========================
+
+To use BibTeX references in your technote, add a "References" section at the end of the main content with a ``bibliography`` directive:
+
+.. tab-set::
+   :sync-group: markup
+
+   .. tab-item:: RST
+      :sync: rst
+
+      .. code-block:: rst
+
+         References
+         ==========
+
+         .. bibliography::
+
+   .. tab-item:: Markdown
+      :sync: md
+
+      .. code-block:: md
+
+         ## References
+
+         ```{bibliography}
+         ```
+
+No arguments are needed for the ``bibliography`` directive because it is automatically configured.
+
+By default, all BibTeX files from lsst-texmf are available in your technote.
+
+Adding local BibTeX entries
+===========================
+
+You can define your own BibTeX entries in a local bib file, such as :file:`local.bib`, when lsst-texmf is missing references.
+Any ``*.bib`` file in the root of the technote repository is automatically included in the build.
+
+Creating citations in text
+==========================
+
+You can add citations in your text using ``cite`` and related roles.
+The ``cite`` roles takes the bibkey as the argument.
+
+Author-year citations with cite
+-------------------------------
+
+The ``cite`` role adds a parenthetical inline citation like ``[Author et al., Year]``:
+
+.. tab-set::
+   :sync-group: markup
+
+   .. tab-item:: RST
+      :sync: rst
+
+      .. code-block:: rst
+
+         :cite:`RTN-095`
+
+   .. tab-item:: Markdown
+      :sync: md
+
+      .. code-block:: md
+
+         {cite}`RTN-095`
+
+Multiple bibkeys can be included, separated by commas:
+
+.. tab-set::
+   :sync-group: markup
+
+   .. tab-item:: RST
+      :sync: rst
+
+      .. code-block:: rst
+
+         :cite:`bibkey1,bibkey2`
+
+   .. tab-item:: Markdown
+      :sync: md
+
+      .. code-block:: md
+
+         {cite}`bibkey1,bibkey2`
+
+Textual citations with cite:t
+-----------------------------
+
+The ``cite:t`` role adds a textual citation like ``Author et al. (Year)``:
+
+.. tab-set::
+   :sync-group: markup
+
+   .. tab-item:: RST
+      :sync: rst
+
+      .. code-block:: rst
+
+         :cite:t:`RTN-095`
+
+   .. tab-item:: Markdown
+      :sync: md
+
+      .. code-block:: md
+
+         {cite:t}`RTN-095`
+
+Specialized citation roles
+--------------------------
+
+The sphinxcontrib-bibtex extension also provides specialized citation roles for specific situations, such as listing authors or years, or including pre- or post-text inside a parenthetical citation.
+See the `sphinxcontrib-bibtex documentation <https://sphinxcontrib-bibtex.readthedocs.io/en/latest/usage.html#roles-and-directives>`__ for details.
+
+Refresh bib files from lsst-texmf
+=================================
+
+The lsst-texmf bib files are automatically downloaded and cached in the :file:`.technote` directory when your technote is built. You can refresh the cached files by deleting the :file:`.technote` directory and rebuilding your technote.
+
+.. prompt::
+
+   rm -rf .technote
+   make html
+
+You can also delete both the cache and the existing built HTML with:
+
+.. prompt::
+
+   make clean

{documenteer-2.2.0 → documenteer-2.3.0}/src/documenteer/conf/_utils.py

@@ -171,10 +171,11 @@ def get_common_nitpick_ignore() -> list[tuple[str, str]]:
             "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.
+        # asyncio.Lock and asyncio.Event are documented 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", "asyncio.locks.Event"),
         ("py:class", "pathlib._local.Path"),
     ]
 
@@ -199,15 +200,18 @@ def get_common_nitpick_ignore_regex() -> list[tuple[str, str]]:
         "kubernetes_asyncio",
         "pydantic",
         "pydantic_settings",
+        "sentry_sdk",
         "starlette",
     ]
-    patterns = [("py:*", rf"{package}(?:\..*)?") for package in packages]
+    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"),
+            ("py:.*", r".*\.all fields"),
+            # Sphinx bug handling the type keyword
+            ("py:.*", r".*\.TypeAliasType"),
         ]
     )
 

{documenteer-2.2.0 → documenteer-2.3.0}/src/documenteer/ext/bibtex.py

@@ -18,6 +18,7 @@ from pybtex.style.template import (
     optional_field,
     sentence,
     tag,
+    words,
 )
 from sphinx.application import Sphinx
 from sphinx.util.typing import ExtensionMetadata
@@ -100,6 +101,28 @@ class LsstBibtexStyle(pybtex.style.formatting.plain.Style):
         self._rewrite_field(e, "journal")
         return super().get_article_template(e)
 
+    def format_ascl(self, e: Entry) -> Node:
+        # based on urlbst format.doi
+        url = join["https://ascl.net/", field("eid", raw=True)]
+        return href(url)[join["ascl:", field("eid", raw=True)]]
+
+    def get_software_template(self, e: Entry) -> Node:
+        if "eid" in e.fields and "ascl:" in e.fields["eid"]:
+            date = words[optional_field("month"), field("year")]
+            e.fields["eid"] = e.fields["eid"].removeprefix("ascl:")
+            return toplevel[
+                optional[sentence[self.format_names("author")]],
+                optional[self.format_title(e, "title")],
+                sentence[
+                    optional[field("howpublished")],
+                    optional[date],
+                ],
+                sentence[optional_field("note")],
+                self.format_ascl(e),
+            ]
+        # If not an ASCL entry, use the default software template.
+        return super().get_software_template(e)
+
     def get_inproceedings_template(self, e: Entry) -> Node:
         # Potentially modify the series string before formatting it.
         self._rewrite_field(e, "series")

{documenteer-2.2.0 → documenteer-2.3.0}/src/documenteer/ext/remotecodeblock.py

@@ -12,7 +12,7 @@ from docutils import nodes
 from docutils.parsers.rst import directives
 from sphinx.application import Sphinx
 from sphinx.directives.code import LiteralIncludeReader, container_wrapper
-from sphinx.util import logging, parselinenos  # type: ignore[attr-defined]
+from sphinx.util import logging
 from sphinx.util.docutils import SphinxDirective
 from sphinx.util.nodes import set_source_info
 from sphinx.util.typing import ExtensionMetadata
@@ -25,6 +25,39 @@ __all__ = ["setup"]
 logger = logging.getLogger(__name__)
 
 
+# Vendored from sphinx to accomodate differences between Sphinx 7 and 8
+# Copyright the Sphinx team.
+# See licenses/sphinx.txt
+def parse_line_num_spec(spec: str, total: int) -> list[int]:
+    """Parse a line number spec (such as "1,2,4-6") and return a list of
+    wanted line numbers.
+    """
+    items = []
+    parts = spec.split(",")
+    for part in parts:
+        try:
+            begend = part.strip().split("-")
+            if begend == ["", ""]:
+                raise ValueError
+            if len(begend) == 1:
+                items.append(int(begend[0]) - 1)
+            elif len(begend) == 2:
+                start = int(begend[0] or 1)  # left half open (cf. -10)
+                end = int(
+                    begend[1] or max(start, total)
+                )  # right half open (cf. 10-)
+                if start > end:  # invalid range (cf. 10-1)
+                    raise ValueError
+                items.extend(range(start - 1, end))
+            else:
+                raise ValueError
+        except ValueError as exc:
+            msg = f"invalid line number spec: {spec!r}"
+            raise ValueError(msg) from exc
+
+    return items
+
+
 class RemoteCodeBlock(SphinxDirective):
     """Directive that works like ``literalinclude`` to show a code block, but
     supports getting content over https.
@@ -94,7 +127,9 @@ class RemoteCodeBlock(SphinxDirective):
             retnode["classes"] += self.options.get("class", [])
             extra_args = retnode["highlight_args"] = {}
             if "emphasize-lines" in self.options:
-                hl_lines = parselinenos(self.options["emphasize-lines"], lines)
+                hl_lines = parse_line_num_spec(
+                    self.options["emphasize-lines"], lines
+                )
                 if any(i >= lines for i in hl_lines):
                     logger.warning(
                         "line number spec is out of range(1-%d): %r",

{documenteer-2.2.0 → documenteer-2.3.0}/src/documenteer/storage/localtemplates/technote/README.rst

@@ -22,7 +22,7 @@
 Build this technical note
 =========================
 
-You can clone this repository and build the technote locally if your system has Python 3.11 or later:
+You can clone this repository and build the technote locally if your system has Python 3.12 or later:
 
 .. code-block:: bash
 

{documenteer-2.2.0 → documenteer-2.3.0}/src/documenteer.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: documenteer
-Version: 2.2.0
+Version: 2.3.0
 Summary: Rubin Observatory / LSST Sphinx documentation tools, extensions, and configurations.
 License-Expression: MIT
 Project-URL: Homepage, https://documenteer.lsst.io

{documenteer-2.2.0 → documenteer-2.3.0}/src/documenteer.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@
 .prettierignore
 .prettierrc.yaml
 CHANGELOG.md
+CLAUDE.md
 LICENSE
 MANIFEST.in
 Makefile
@@ -17,6 +18,8 @@ pyproject.toml
 ruff-shared.toml
 tox.ini
 webpack.config.js
+.claude/.gitignore
+.claude/tasks/.gitkeep
 .github/CODE_OF_CONDUCT.md
 .github/CONTRIBUTING.md
 .github/SUPPORT.md
@@ -45,6 +48,7 @@ demo/rst-technote/Makefile
 demo/rst-technote/conf.py
 demo/rst-technote/diagram.py
 demo/rst-technote/index.rst
+demo/rst-technote/local.bib
 demo/rst-technote/technote.toml
 docs/.gitignore
 docs/Makefile
@@ -95,6 +99,7 @@ docs/technotes/extensions.rst
 docs/technotes/how-your-technote-gets-published.rst
 docs/technotes/index.rst
 docs/technotes/migrate.rst
+docs/technotes/references.rst
 docs/technotes/start-a-technote.rst
 docs/technotes/wide-content.rst
 docs/technotes/_templates/README.md