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

1.2.0

New features

• Rubin user guides (documenteer.conf.guide) and technotes (documenteer.conf.technote) now include MyST-NB to support Jupyter Notebooks in Sphinx documentation. The MyST-NB extension also supersedes MyST-Parser for Markdown syntax support. For guides, Jupyter Notebook files can be intermixed with Markdown (.md) and reStructuredText (.rst) files. An ipynb file is considered as a page in the documentation. For technotes, the Jupyter Notebook must be named index.ipynb. By default, these configurations use MyST-NB's "auto" mode for notebook execution: only if a notebook is missing outputs will it be executed.

What's Changed

• [neophile] Update dependencies by @neophile-square in #219
• DM-43485: Integrate MyST-NB for technotes and user guides by @jonathansick in #220

Full Changelog: 1.1.1...1.2.0

1.1.1

Bug fixes

• setuptools is now included in the core package dependencies. The documenteer.ext.bibtex extension uses pybtex, which is turn uses pkg_resources from setuptools. In Python 3.12, setuptools is not available in Python environments by default. This direct dependency can be removed once pybtex is updated to use importlib.metadata.

Other changes

• Update to the Python project configuration guide for documenteer.toml to use an example project other than "Documenteer" in the examples. Also emphasize the requirement that the project must be installed to use the [project.python] configuration in documenteer.toml.

What's Changed

• Improve guide for project.python table configuration by @jonathansick in #216
• [neophile] Update dependencies by @neophile-square in #217
• DM-42967: Add setuptools as a dependency by @jonathansick in #218

Full Changelog: 1.1.0...1.1.1