documenteer 2.1.1__tar.gz → 2.3.0__tar.gz

documenteer-2.3.0/.claude/.gitignore

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

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

@@ -2,6 +2,44 @@
 
 <!-- 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)
+
+### New features
+
+- Updated the `documenteer technote migrate` command to use Documenteer 2.0 for new technotes.
+- Technote migration documentation now uses uv/uvx for running migration tools.
+- Improved the formatting for reference section in technotes with the Rubin BibTeX style:
+
+  - If an entry has more than 7 authors, the first three authors are listed, followed by "and others."
+  - LaTeX macros for journals are now converted to their expected names in the bibliography.
+
+### Other changes
+
+- Cleanup the API documentation for cleaner documentation builds.
+
 <a id='changelog-2.1.1'></a>
 ## 2.1.1 (2025-07-17)
 

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.1.1 → documenteer-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: documenteer
-Version: 2.1.1
+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.1.1 → 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.1.1 → documenteer-2.3.0}/docs/Makefile

@@ -1,7 +1,7 @@
 # Makefile for Sphinx documentation
 
 # You can set these variables from the command line.
-SPHINXOPTS    = -n
+SPHINXOPTS    = -n -W
 SPHINXBUILD   = sphinx-build
 BUILDDIR      = _build
 

{documenteer-2.1.1 → documenteer-2.3.0}/docs/_rst_epilog.rst

@@ -62,6 +62,7 @@
 .. _`authordb.yaml`: https://github.com/lsst/lsst-texmf/blob/main/etc/authordb.yaml
 .. _pipx: https://pipx.pypa.io
 .. _`LSSTC Slack Workspace`: https://lsstc.slack.com
+.. _`uv`: https://docs.astral.sh/uv/
 
 .. |dmw-squarebot| replace:: `direct message with @squarebot <https://slack.com/app_redirect?app=A07PWG9UG9M&team=T02SVMGU4>`__
 

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

@@ -2,6 +2,44 @@
 
 <!-- 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)
+
+### New features
+
+- Updated the `documenteer technote migrate` command to use Documenteer 2.0 for new technotes.
+- Technote migration documentation now uses uv/uvx for running migration tools.
+- Improved the formatting for reference section in technotes with the Rubin BibTeX style:
+
+  - If an entry has more than 7 authors, the first three authors are listed, followed by "and others."
+  - LaTeX macros for journals are now converted to their expected names in the bibliography.
+
+### Other changes
+
+- Cleanup the API documentation for cleaner documentation builds.
+
 <a id='changelog-2.1.1'></a>
 ## 2.1.1 (2025-07-17)
 

{documenteer-2.1.1 → documenteer-2.3.0}/docs/dev/api/documenteer.ext.rst

@@ -2,12 +2,12 @@
 documenteer.ext
 ###############
 
-.. automodapi:: documenteer.ext.openapi
-
 .. automodapi:: documenteer.ext.bibtex
    :no-inherited-members:
    :no-inheritance-diagram:
 
+.. automodapi:: documenteer.ext.githubbibcache
+
 .. automodapi:: documenteer.ext.jira
    :no-inheritance-diagram:
 
@@ -16,3 +16,9 @@ documenteer.ext
 
 .. automodapi:: documenteer.ext.mockcoderefs
    :no-inheritance-diagram:
+
+.. automodapi:: documenteer.ext.openapi
+
+.. automodapi:: documenteer.ext.remotecodeblock
+
+.. automodapi:: documenteer.ext.robots

{documenteer-2.1.1 → documenteer-2.3.0}/docs/documenteer.toml

@@ -44,7 +44,8 @@ technote = "https://technote.lsst.io/"
 
 [sphinx.linkcheck]
 ignore = [
-    "https://mermaid-js.github.io"
+    "https://mermaid-js.github.io",
+    "https://rubin-obs.slack.com"
 ]
 
 [sphinx.redirects]

{documenteer-2.1.1 → 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.1.1 → 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.1.1 → 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.1.1 → 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.1.1 → 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.1.1 → 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.1.1 → documenteer-2.3.0}/docs/technotes/migrate.rst

@@ -5,7 +5,7 @@ Migrate legacy reStructuredText/Sphinx technical notes
 ######################################################
 
 Introduced in December 2023, Rubin Observatory has a new technical note format for Markdown and reStructuredText documents.
-This update provides many `new features <https://community.lsst.org/t/the-next-generation-of-rubin-observatory-technotes-with-documenteer-1-0/8166>`__ included a responsive and branded page design, Markdown support, improved build configuration, automated bibliography management, and citation-ready metadata.
+This update provides many `new features <https://community.lsst.org/t/the-next-generation-of-rubin-observatory-technotes-with-documenteer-1-0/8166>`__ including a responsive and branded page design, Markdown support, improved build configuration, automated bibliography management, and citation-ready metadata.
 
 This page shows how to migrate your existing technotes with a command-line tool that largely automates the process.
 This page also provides file-by-file notes in case you need to revise the migration.
@@ -16,39 +16,17 @@ This page also provides file-by-file notes in case you need to revise the migrat
 
    LaTeX-format technotes are unaffected by this migration.
 
-Step 1. Install pipx
-====================
+Use the migration tool
+======================
 
-The migration tool needs **Python 3.11 or later**.
-You can verify this by running ``python --version`` from your shell.
+Documenteer provides a command-line tool, :command:`documenteer technote migrate`, to migrate legacy technotes to the new format.
+The migration tool requires:
 
-This official migration procedure uses the pipx_ tool to install and run the migration tool in an isolated Python environment.
-You can verify that pipx_ is installed by running ``pipx --version`` from your shell and checking for a version number.
+- Python 3.12 or later
+- The :command:`uvx` command from the `uv`_ package
 
-If you don't have the :command:`pipx` command-line tool already, you can install ``pipx`` several ways:
-
-.. tab-set::
-
-   .. tab-item:: pip
-
-      .. prompt:: bash
-
-         python -m pip install pipx
-
-   .. tab-item:: conda-forge
-
-      .. prompt:: bash
-
-         conda install -c conda-forge pipx
-
-   .. tab-item:: homebrew
-
-      .. prompt:: bash
-
-         brew install pipx
-
-Step 2. Clone your technote and create a branch
-===============================================
+Step 1. Clone your technote and create a branch
+-----------------------------------------------
 
 Since the migration is performed locally, you need to clone the repository:
 
@@ -60,12 +38,12 @@ Then create a branch for the migration (see the `Developer Guide <https://develo
 
 .. code-block:: bash
 
-   git switch -c {...}
+   git switch -c technote-migration
 
 Working from a branch allows you to create a pull request to verify the migration before merging it into the main branch.
 
-Step 3. Look up author IDs
-==========================
+Step 2. Look up author IDs
+--------------------------
 
 The migration tool needs the IDs of the technote's authors to fully configure the technote's metadata.
 
@@ -74,15 +52,39 @@ For example, ``sickj`` is the ID for Jonathan Sick.
 
 .. _technote-migration-tool:
 
-Step 4. Run the migration tool
-==============================
+Step 3. Run the migration tool
+------------------------------
 
 From the root of the cloned technote repository, run the migration tool, listing any identified authors that are relevant to your technote:
 
 .. code-block:: bash
    :caption: Set author IDs with the -a option
 
-   pipx run documenteer technote migrate -a sickj -a economouf
+   uvx documenteer technote migrate -a sickj -a economouf
+
+.. dropdown:: Details for installing uv/uvx...
+
+   The migration tool needs **Python 3.12 or later**.
+   You can verify this by running ``python --version`` from your shell.
+
+   This official migration procedure uses the :command:`uvx` command from uv_ to install and run the migration tool in an isolated Python environment.
+
+   If you don't have the :command:`uvx` command-line tool already, you can install ``uv`` several ways:
+
+   .. tab-set::
+
+      .. tab-item:: pip
+
+         .. prompt:: bash
+
+            python -m pip install uv
+
+      .. tab-item:: homebrew
+
+         .. prompt:: bash
+
+            brew install uv
+
 
 When the migration runs, it shows a summary of the files changed and deleted.
 Use ``git diff`` to review the changes in case you need to make tweaks before committing.
@@ -91,22 +93,21 @@ If you want to learn more about the changes made by the migration tool, you can
 
 .. _technote-migration-markdown:
 
-Step 5 (optional). Migrate to Markdown
-======================================
+Step 4 (optional). Migrate to Markdown
+--------------------------------------
 
 The new technote format supports Markdown as well as reStructuredText.
 If you wish to use Markdown, you can use MyST Parser's migration tool:
 
 .. prompt:: bash
 
-   pipx install "rst-to-myst[sphinx]"
-   rst2myst convert index.rst
+   uvx --from "rst-to-myst[sphinx]" rst2myst convert index.rst
 
 The Markdown flavor used by the new technote format is MyST Markdown, which is a superset of CommonMark Markdown with support for Sphinx roles and directives.
 See the `MyST Parser documentation <https://myst-parser.readthedocs.io/en/latest/syntax/roles-and-directives.html#roles-directives>`__ for more information.
 
-Step 6 (optional). Build the technote locally
-=============================================
+Step 5 (optional). Build the technote locally
+---------------------------------------------
 
 You can build the technote locally to verify that the migrated technote compiles successfully.
 
@@ -136,8 +137,8 @@ You might also want to run the linter to check links and find common issues:
 If you have any questions or issues about the build, you should still proceed with committing and creating a pull request (see next step).
 This way you can link to the repository when you reach out for help in `#square-docs-support`_ on Slack.
 
-Step 7. Commit the migration, pull request, and merge
-=====================================================
+Step 6. Commit the migration, pull request, and merge
+-----------------------------------------------------
 
 At this point, you should have a working technote in the new format.
 If you haven't already, commit your work, push your branch to the GitHub repository, and open a pull request.
@@ -225,26 +226,6 @@ The new technote format requires some changes to this file: the title is now par
 Additionally, the new technote format supports Markdown as well as reStructuredText.
 See :ref:`migrate to Markdown <technote-migration-markdown>` to learn how to switch to Markdown.
 
-.. tip::
-
-   Besides these changes, your technote can also be written in Markdown (:file:`index.md`).
-   If you wish to switch from ReStructuredText to Markdown, you can use MyST Parser's migration tool:
-
-   .. prompt:: bash
-
-      pipx install "rst-to-myst[sphinx]"
-      rst2myst convert index.rst
-
-   This procedure uses pipx_ to install the ``rst-to-myst`` tool in an isolated Python environment (you might have already installed pipx_ to run the :ref:`main migration tool <technote-migration-tool>`).
-
-   Finally, delete the original :file:`index.rst` file and edit :file:`index.md` to fix any formatting issues.
-
-   .. prompt:: bash
-
-      git rm index.rst
-      git add index.md
-      git commit -m "Switch to Markdown format"
-
 Title
 ~~~~~
 
@@ -254,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
@@ -265,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
@@ -287,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
@@ -306,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
@@ -330,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
@@ -342,6 +328,7 @@ In the new technote format, this section is simplified:
          .. bibliography::
 
    .. tab-item:: md
+      :sync: md
 
       .. code-block:: md
          :caption: index.md
@@ -402,7 +389,7 @@ To start, add a :file:`.pre-commit-config.yaml` file:
 
 .. tip::
 
-   You can add additional pre-commit hooks to this file to suite your needs.
+   You can add additional pre-commit hooks to this file to suit your needs.
    See Pre-commit's `directory of available hooks <https://pre-commit.com/hooks.html>`__ for ideas.
 
 requirements.txt file (updated)
@@ -495,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