2.0.0a3

Other changes

• Constrain Sphinx < 8.2 to avoid an issue with sphinxcontrib-bibtex and Sphinx 8.2.

1.4.3

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.

What's Changed

• DM-47710: backport #dm-docs-support, #square-docs-support by @fajpunk in #237
• DM-49037: Pin Sphinx < 8.2 for compatibility with sphinxcontrib-bibtex by @jonathansick in #240

Full Changelog: 1.4.2...1.4.3

1.4.2

What's Changed

• Backport revert sphinx pin by @fajpunk in #234

Full Changelog: 1.4.1...1.4.2

1.4.1

What's Changed

• DM-46777: sphinx < 8.1.0 by @fajpunk in #231
• DM-46777: release 1.4.1 by @fajpunk in #232

Full Changelog: 1.4.0...1.4.1

2.0.0a2

Backwards-incompatible changes

• All Science Pipelines-related tooling and Sphinx extensions have been removed from Documenteer, and can now be found in a new Science Pipelines package called sphinxutils (https://github.com/lsst-dm/sphinxutils). Specific removals 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

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. 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 that are common when including references to projects that don't use Sphinx/Intersphinx for this documentation, including Pydantic and FastAPI.

• The entire documenteer code base is now type annotated.

Other changes

• The code base is now linted and formatted with ruff.
• Start testing against Sphinx 8.

Full Changelog: 1.4.0...2.0.0a2

2.0.0a1

Backwards-incompatible changes

• All Science Pipelines-related tooling and Sphinx extensions have been removed from Documenteer, and can now be found in a new Science Pipelines package called sphinxutils (https://github.com/lsst-dm/sphinxutils). Specific removals 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

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. 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 that are common when including references to projects that don't use Sphinx/Intersphinx for this documentation, including Pydantic and FastAPI.

• The entire documenteer code base is now type annotated.

Other changes

• The code base is now linted and formatted with ruff.
• Start testing against Sphinx 8.

Full Changelog: 1.4.0...2.0.0a1

1.4.0

New features

• Update to technote 0.9.0. This new version of the technote theme features a two column layout that allows wide content, such as tables, code blocks, and figures, to span the full width of the page (bleeding beyond the text column).

What's Changed

• DM-44542: Adopt technote 0.9 and wide content utility class by @jonathansick in #228

Full Changelog: 1.3.0...1.4.0

1.3.0

New features

• Added a [sphinx.redirects] table to documenteer.toml. This provides support for configuring page redirects from the TOML configuration. Redirects are useful if pages move because of a content re-organization. This feature is based on sphinx-rediraffe.

• Added the sphinxcontrib-youtube 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 it's 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.

What's Changed

• DM-44137: Add extend_excludes_for_non_index_source by @jonathansick in #224
• DM-43638: Update to technote 0.8 to fix baseline alignment for monospace text in technotes by @jonathansick in #225
• DM-44193: Add [sphinx.redirects] table to documenteer.toml by @jonathansick in #226

Full Changelog: 1.2.2...1.3.0

1.2.2

Bug fixes

• Update jira_uri_template configuration default to https://rubinobs.atlassian.net/browse/{issue}. This will make all :jira:, :jirab:, and :jirap: roles point to the new Jira instance for Rubin Observatory.
• Drop jira.lsstcorp.org from the linkcheck ignore list defaults for documenteer.config.guide since that instance is no longer being used.
• Replace jira.lsstcorp.org URLs in documentation to rubinobs.atlassian.net.

What's Changed

• DM-43749: Update jira_uri_template default to point to rubinobs.atlassian.net by @jonathansick in #223

Full Changelog: 1.2.1...1.2.2

1.2.1

Bug fixes

• Fix the "Source parser for markdown not registered" error for Markdown-based technotes. With the MyST-NB extension the Markdown parser is automatically registered, so the documenteer.conf.technote configuration now resets the source_suffix configuration originally created by the Technote package.

Other changes

• Being running the "demo" technotes in GitHub Actions CI.
• Add a Markdown-based demo technote for testing.

What's Changed

• DM-43617: Fix Source parser for markdown not registered error for technotes by @jonathansick in #221

Full Changelog: 1.2.0...1.2.1