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

1.0.0a17

What's Changed

• DM-42023: Add documenteer technote add-author and sync-authors commands by @jonathansick in #205

Full Changelog: 1.0.0a16...1.0.0a17

1.0.0a16

What's Changed

• DM-41917: Improvements to the technote UI design by @jonathansick in #203

Full Changelog: 1.0.0a15...1.0.0a16

1.0.0a15

What's Changed

• DM-41905: Add defalut Sphinx extensions for technotes by @jonathansick in #202

Full Changelog: 1.0.0a14...1.0.0a15

1.0.0a14

What's Changed

• Update technote migration by @jonathansick in #198
• Clarify optional nature of status by @frossie in #199
• [neophile] Update dependencies by @neophile-square in #200
• DM-41781: Update to technote 0.5 by @jonathansick in #201

New Contributors

• @frossie made their first contribution in #199

Full Changelog: 1.0.0a13...1.0.0a14

1.0.0a13

What's Changed

• [neophile] Update dependencies by @neophile-square in #196
• DM-41502: Update to technote 0.4 by @jonathansick in #197

Full Changelog: 1.0.0a12...1.0.0a13