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

1.1.0

New features

• Update to Technote 0.7.0. This version fixes the CSS for code samples without captions. It also uses the build date as the open graph modification date (og:article:modified_time) if one isn't set explicitly in technote.toml.
• Add sphinx_design as a default extension for technotes. This makes buttons, icons, and grids available to technote authors. See https://sqr-084.lsst.io for examples of buttons.

Bug fixes

• If the version field in documenteer.toml isn't set, and the project isn't a Python package, then the default value is now "Latest." The former default, None, was invalid.

What's Changed

• Fix typo in migration doc by @jonathansick in #211
• [neophile] Update dependencies by @neophile-square in #212
• [neophile] Update dependencies by @neophile-square in #213
• Update to technote 0.7 by @jonathansick in #214

Full Changelog: 1.0.1...1.1.0

1.0.1a1

What's Changed

• Fix typo in migration doc by @jonathansick in #211
• [neophile] Update dependencies by @neophile-square in #212
• [neophile] Update dependencies by @neophile-square in #213

Full Changelog: 1.0.1...1.0.1a1

1.0.1

Bug fixes

• In documenteer technote migrate, change the icon for a file deletion event from ❌ to 🗑️.

Other changes

• Update the migration docs around the migration tool and convert the previous manual migration docs into a reference of the file-by-file changes.

What's Changed

• Update migrate.rst by @frossie in #208
• Change file deletion icon to trashcan by @frossie in #209
• [neophile] Update dependencies by @neophile-square in #204
• Update change log for 1.0.1 release by @jonathansick in #210

Full Changelog: 1.0.0...1.0.1

1.0.0

Backwards-incompatible changes

• Documenteer now requires Python 3.11 or later.

• Dependency changes:

  • Pydantic 2.0 or later.
  • Sphinx 7 and later (and docutils 0.20 and later)
  • pydata-sphinx-theme < 0.13 on account of a change in logo path checking (affects user guide projects).

• Dropped support for the original technote configuration for Documenteer < 1.0. The documenteer.conf.technote configuration now uses the modern platform build with Technote. See new features below for more details.

• Dropped CLI commands:

  • The refresh-lsst-bib CLI command is removed. Technotes now automatically vendor lsst-texmf's bib files and cache them using documenteer.ext.githubbibcache.
  • The build-stack-docs CLI command is removed and replaced by the stack-docs and package-docs CLIs in Documenteer 0.3.0.

• The documenteer.conf.pipelines and documenteer.conf.pipelinespkg configuration modules now derive from documenteer.conf.guide. In doing so, the Pipelines documentation configuration works the same as Rubin Guides, but with additional configuration for pipelines-specific Sphinx extensions and other configurations. With this change, the lsst-sphinx-bootstrap-theme is no longer used by Documenteer.

• The documenteer.sphinxext module has been removed and the existing Sphinx extensions within it are now available from documenteer.ext. It's no longer possible to use documenteer.sphinxext to automatically load all Documenteer Sphinx extensions. Extensions need to now be added individually to the extensions configuration variable in conf.py. The migrated extension modules are:

  • documenteer.ext.bibtex
  • documenteer.ext.jira
  • documenteer.ext.lsstdocushare
  • documenteer.ext.lssttasks
  • documenteer.ext.mockcoderefs
  • documenteer.ext.packagetoctree

New features

• All-new technote configuration for Rubin Observatory. Technotes are now built with a framework we created by the same name, Technote. The new technotes feature a responsive design, better on-page navigation, and overall cleaner design that matches Rubin Observatory's visual identity. For authors, technotes use a new configuration file, technote.toml, which replaces metadata.yaml. Technotes can also be written in Markdown (in addition to continuing reStructuredText support) thanks to MyST Parser. Other key features:

  • You can migrate your existing technote by running the documenteer technote migrate CLI command. The migration process is explained in detail at https://documenteer.lsst.io/technotes/migrate.html.

  • Rubin technotes automatically use the bib files from https://github.com/lsst/lsst-texmf. In your text, use the :cite: directive with a bibkey from those bib files to cite a reference. Documenteer automatically retrieves the bib files from GitHub so you no longer need to maintain a copy in your repository.

  • Rubin technotes include a richer metadata base than the original technote system. This will make it easier to cite technotes. Part of the richer metadata system is the authors table in technote.toml files. This author information is derived from, and synchronized with, the authordb.yaml file in lsst/lsst-texmf. The documenteer technote add-author and documenteer technote sync-authors CLI commands can help you manage author information in your technote.

  • The title for a technote is now derived from the top-level heading in the content itself.

  • There is a new abstract directive for marking up a technote's abstract or summary. This replaces the use of a note for the summary. This summary abstract is used by the documentation crawler to build https://www.lsst.io.

  • Technotes can now indicate their status with the technote.status field in technote.toml. For example, a technote can start out as a draft. You can also mark a technote as deprecated and link to superseding websites.

  • The new technote configuration comes pre-loaded with extensions for making diagrams as code, including sphinxcontrib-mermaid and sphinx-diagrams.

• Improvements for Rubin user guides (documenteer.conf.guide):

  • Add sphinx-jinja to the Rubin guides configuration by default.
  • Add sphinx-rediraffe to the Rubin guides configuration by default.
  • Use sphinxcontrib-jquery to ensure jQuery is available for user guide and Pipelines documentation builds.
  • New sphinx.exclude field to documenteer.toml to list files for exclusion from a documentation project. More files and directories like .venv and requirements.txt are now excluded, as well.
  • New support for embedding OpenAPI documentation in a Redoc-generated subsite. The documenteer.ext.openapi extension can call a user-specified function to generate and install the OpenAPI specification the Sphinx source. For user guide projects, the [project.openapi] table in documenteer.toml can be used to configure both the documenteer.ext.openapi and sphinxcontrib-redoc extensions. sphinxcontrib-redoc is installed and configured by default for all Rubin user guide projects (projects that use documenteer.conf.guide).

• A new extension, documenteer.ext.githubbibcache, can fetch and locally cache BibTeX files from one or more public GitHub repositories. These bibfiles are automatically added to sphinxcontrib-bibtex's bibtex_files configuration. This powers the technote's automatic use of bib files from the https://github.com/lsst/lsst-texmf repository.

Bug fixes

• Retry is now imported directly from urllib3 instead of the vendored version in requests.

Other changes

• Adopted Scriv for maintaining the change log.

What's Changed

• DM-36665: Drop version from homepage by @jonathansick in #142
• Documentation edits by @jonathansick in #143
• DM-37481: Fix emergent GitHub Actions issues by @jonathansick in #146
• DM-37007: Add beta technote theme for Rubin based on technote library by @jonathansick in #144
• Update pre-commit plugins by @jonathansick in #148
• Temporarily pin mermaid to 9.4.0 by @jonathansick in #149
• DM-38168: Pin pydata-sphinx-theme < 0.13 by @jonathansick in #151
• [neophile] Update dependencies by @sqrbot in #147
• DM-38388: Improve source exclusions for user guides by @jonathansick in #155
• [neophile] Update dependencies by @sqrbot in #157
• DM-37525: Add openapi generator extension by @jonathansick in #159
• DM-39580: Add sphinxcontrib-jquery by @jonathansick in #161
• DM-39580: Document import of get_openapi by @jonathansick in #162
• Fix typos on README by @jonathansick in #165
• [neophile] Update dependencies by @sqrbot in #163
• DM-25337: Add -W (warnings as errors) and -n nitpicky mode for stack-docs / package-docs build by @jonathansick in #167
• DM-39884: Pin pydantic < 2.0.0 by @jonathansick in #172
• DM-39837: Try DM-39837 version of pypi-publish action by @jonathansick in #173
• DM-39837: Check package version in GitHub Action release published event by @jonathansick in #174
• DM-39837: Do version check in tox.ini by @jonathansick in #175
• DM-39837: Enable release as a PyPI trusted publishers by @jonathansick in #176
• DM-39837: Adopt lsst-sqre/build-and-publish-to-pypi@v2 by @jonathansick in #177
• Adopt lsst-sqre/build-and-publish-to-pypi@v2 by @jonathansick in #178
• DM-40228: Pin sphinx < 7 (main) by @jonathansick in #180
• DM-40684: Adopt Python 3.11 and Pydantic 2 for 1.0 release milestone by @jonathansick in #181
• DM-40684: Add Neophile-based dependency update by @jonathansick in #182
• [neophile] Update dependencies by @neophile-square in #183
• DM-40815: Install technote from its main branch by @jonathansick in #184
• DM-40815: Update to technote 0.3.0a2 by @jonathansick in #185
• DM-40815: Update to technote 0.3.0a3 by @jonathansick in #186
• DM-40847: Update technote dependency to 0.3.0a4 by @jonathansick in #187
• DM-40967: Update to technote 0.3.0a6 by @jonathansick in #188
• [neophile] Update dependencies by @neophile-square in #189
• DM-41179: Update to technote 0.3.0a7 by @jonathansick in #190
• DM-41214: Add a GitHub-based bibtex file cache extension by @jonathansick...

1.0.0a18

What's Changed

• DM-42144: Include license.id in migration template by @jonathansick in #206

Full Changelog: 1.0.0a17...1.0.0a18