Update dependency documenteer to v1

[renovate]

This PR contains the following updates:

Package	Change	Age	Adoption	Passing	Confidence
documenteer	>=0.5.0,<0.6.0 -> >=1.2.2,<1.3.0

---

Release Notes

lsst-sqre/documenteer (documenteer)

v1.2.2

Compare Source

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.

v1.2.1

Compare Source

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.

v1.2.0

Compare Source

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.

v1.1.1

Compare Source

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.

v1.1.0

Compare Source

New features

• Update to Technote 0.7.0.
• Add sphinx_design as a default extension for technotes.

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.

v1.0.1

Compare Source

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.

v1.0.0

Compare Source

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.

v0.8.4

Compare Source

Fixes:

• Pin Sphinx < 7 for the guide extra (same as the pinning already being done for the pipelines and technote extras).

v0.8.3

Compare Source

Fixes:

• Pin Pydantic < 2.0.0. This is a temporary measure while we add and test compatibility with Pydantic 1 and 2.

v0.8.2

Compare Source

Fixes:

• Fixed a bug in the help subcommand for the package-docs and stack-docs commands.

v0.8.1

Compare Source

Fixes:

• Fixed a bug in the in the help subcommand for the package-docs and stack-docs commands.

v0.8.0

Compare Source

New features:

• Added a -W / --warning-is-error flag to the package-docs build and stack-docs build commands for Science Pipelines documentation builds. This flag causes Sphinx to treat warnings as errors, which is useful for CI builds.
• Also added a -n / --nitpicky flag that enables Sphinx's nitpicky mode to flag warnings when links cannot resolve.

Fixes:

• Pinned sphinx-autodoc-typehints<1.23.0 to avoid a Sphinx version conflict with sphinx-design. The former required Sphinx >= 7.

v0.7.5

Compare Source

Fixes:

• Use sphinxcontrib-jquery to ensure jQuery is available for user guide and Pipelines documentation builds. Sphinx 6 dropped jQuery from its default theme, and the new pydata-sphinx-theme v0.12 does not include it either.

v0.7.4

Compare Source

Fixes:

• Pinned Sphinx < 7 for the pipelines and technote extras since their themes are not currently compatible with Sphinx 7 and later.

v0.7.3

Compare Source

Fixes:

• Add requirements.txt and .venv/venv to the default exclude_patterns for User Guides.

v0.7.2

Compare Source

Fixes:

• Temporarily pin pydata-sphinx-theme to <0.13. The new version changed how it treats light/dark logos.

v0.7.1

Compare Source

Fixes:

• Temporarily pinning Mermaid to 9.4.0 in the User Guide configuration to workaround a change in the Mermaid CDN.

v0.7.0

Compare Source

• Documenteer provides a new Sphinx configuration profile for general Rubin user guide projects, documenteer.conf.guide.
  This configuration profile features the new pydata-sphinx-theme, with customizations based on design tokens from the Rubin Style Dictionary.
  Most metadata and Sphinx configurations can also be set through a documenteer.toml file, located alongside the standard Sphinx conf.py file.
  Install documenteer[guide] with pip to get the dependencies needed for this Sphinx configuration.

• Packaging updates:

  • Documenteer now uses pyproject.toml for its packaging.
  • The GitHub Actions workflows now use SQuaRE composite workflows for many steps.
  • The README and change log are now written in Markdown.
  • Sphinx version 5 is now included in the test matrix.

v0.6.14

Compare Source

What's Changed

• DM-35900: Update flake8 linter by @​jonathansick in https://github.com/lsst-sqre/documenteer/pull/124
• DM-35917: Back port CmdLineTask deprecation support for 0.6 release by @​jonathansick in https://github.com/lsst-sqre/documenteer/pull/128

Full Changelog: lsst-sqre/documenteer@0.6.13...0.6.14

v0.6.13

Compare Source

• Fixed the "Edit on GitHub" URL string construction in documenteer.conf.technote.

v0.6.12

Compare Source

• Add a tstn role for linking to Telescope and Site technical notes.

v0.6.11

Compare Source

Fixes:

• Fix type checking by adding stub packages.

Changes:

• Add new roles for linking to technical notes:

  • sitcomtn
  • rtn
  • pstn

• Link to technical notes, which are hosted on lsst.io, now linking directly to lsst.io rather than going through `ls.st``. This includes the sqr, dmtn, etc. roles and all the new roles mentioned above.

• Use importlib.metadata for getting the package version, rather than pkg_resources.

• Move to a src/ based package layout for consistency.

Issues:

• Temporarily disable testing the Doxygen-related Sphinx extensions.

v0.6.10

Compare Source

Fixes:

• Support sphinx-jinja 2.0.0 by using the sphinx_jinja extension name in documenteer.conf.pipelines and documenteer.conf.pipelinespkg.
  Installations that use sphinx-jinja < 2 will continue to use sphinxcontrib.jinja since the sphinx-jinja version is dynamically detected.

v0.6.9

Compare Source

Fixes:

• Add support for Sphinx 4.x by switching from sphinx.util.inspect.Signature to sphinx.util.inspect.signature for Sphinx versions 2.4 and later.
  A minimum Sphinx version 2.4 is now required.
• Updated testing matrix to test against the latest patch versions of Sphinx 2.x, 3.x, and 4.x.

v0.6.8

Compare Source

Fixes:

• Document conda-forge based installations.

• Stack documentation builds no longer include meta or build-related files in the HTML site output, such as:

  • conf.py
  • .doctrees
  • doxygen.conf
  • manifest.yaml
  • Build products from sconsUtils-based Doxygen builds, including html and xml.

v0.6.7

Compare Source

Fixes:

• The html_extras_path is no longer accidentally reset to [""] in documenteer.conf.pipelines.

• sphinx-automodapi introduces an autodoc enhancement that replace's autodoc's attr getter for type with a custom function.
  However, we're finding that this enhancement is incompatible with Pybind11 static properties that are part of the LSST Science Pipelines API.
  This release includes a new extension, documenteer.ext.autodocreset, that resets the attr getter for type to the one built into autodoc.
  This extension is used by default in documenteer.config.pipelines and documenteer.config.pipelinespkg.

v0.6.6

Compare Source

Fixes:

• Updated the documenteer.conf.pipelines (and documenteer.conf.pipelinespkg) configuration modules so that they no longer configure doxylink if the Doxygen tag file is not present.
  This change is useful for single-package documentation builds of pure-Python packages.

v0.6.5

Compare Source

Fixes:

• Updated intersphinx links for Numpy and Astropy in the Pipelines configuration (documenteer.conf.pipelines and documenteer.conf.pipelinespkg).

v0.6.4

Compare Source

Fixes:

• Fixed a syntax issue with the package's long description, and added a linting rule to prevent this issue in the future.

v0.6.2

Compare Source

Fixes:

• The build-stack-docs CLI (replaced by stack-docs build) now defaults to not generating a Doxygen configuration, or running Doxygen.
  This is consistent with the original behavior of build-stack-docs, which did not perform a Doxygen build.

• The autocppapi directive now works even if the corresponding Doxylink symbol map is unavailable.
  This feature is useful for any circumstance when a Doxygen subsite that is normally present is unavailable, such as for a single-package documentation build.

• The Doxygen subsite is only added to html_extras_path if the _doxygen/html directory is present.

• Remove the matplotlib plot extension from the legacy documenteer.sphinxconf configuration because the extension appears to be incompatible with Sphinx 3.x.

v0.6.1

Compare Source

• Fixed the "Edit on GitHub" URL string construction in documenteer.conf.technote.

v0.6.0

Compare Source

• Documenteer now works with Sphinx 2.0+.

• Documenteer's dependencies now cleanly map to each use case:

  • pip install documenteer installs only the dependencies required to use Documenteer's own Sphinx extensions.
    The dependencies are not strictly pinned (aside from Sphinx >= 2.0).

  • pip install documenteer[technote] installs the core dependencies required by Documenteer, as well as the pinned Sphinx theme and extensions used by all technote projects.

  • pip install documenteer[pipelines] installs the core dependencies required by Documenteer, as well as the Sphinx theme and extensions used by pipelines.lsst.io.
    These extensions no longer have pinned versions.

  Development and test dependencies are no longer pinned.

• Python 3.6 is no longer officially supported.
  Documenteer is tested with Python 3.7 and 3.8.

• New Sphinx configuration facilities should prevent recursion issues by more cleanly populating the Python attributes in the configuration module:

  • Technote projects now import documenteer.conf.technote in their conf.py files.
  • Stack projects now import documenteer.conf.pipelines in their conf.py files.
  • Individual Stack packages now import documenteer.conf.pipelinespkg in their conf.py files.

  The previous configuration sub-package, documenteer.sphinxconf is deprecated.
  [DM-20866]

  Overall, the configurations are compatible with these exceptions:

  • ReStructuredText source files are no longer copied into the built site for Pipelines projects (html_copy_source is False).
    This change reduces the upload site of the pipelines.lsst.io site.
  • Updated the MathJax CDN URL to point to cdnjs.

• The stack documentation build (stack-docs build) can now run a Doxygen build to generate an HTML site and tag file of the C++ API.
  The HTML site is copied into the cpp-api directory of the Sphinx site, during the Sphinx build.
  This Doxygen build replaces, and is independent of, the Doxygen build tooling in sconsUtils, lsstDoxygen, and the base package.

  ReStructuredText content can now link into the embedded Doxygen-generate site using the sphinxcontrib-doxylink extension with the new lsstcc role.
  Authors can use a new command, stack-docs listcc to find available APIs for linking.

  There is a new directive, autocppapi, part of the documenteer.ext.autocppapi extension, that helps you list and link to C++ APIs in a namespace.
  It's intended to be used equivalently to the automodapi extension.

  The built-in Doxygen build considers all Stack packages with a doc/doxygen.conf.in file.
  Documenteer creates a Doxygen configuration from the contents of each package's doxygen.conf.in file, along with built-in defaults appropriate for pipelines.lsst.io.
  For example, individual packages can add to the EXCLUDE tag.
  By default, each package's include directory is included in the Doxygen build.

  [DM-22698, DM-23094, DM-22461]

• Improved Sphinx runner (documenteer.sphinxrunner).
  [DM-26768]

• Added static type checking using mypy.
  [DM-22717, DM-26288]

• Improved packaging, testing, and development environment:

  • PEP 518-ify the build process by adding a pyproject.toml file.
  • Removed the deprecated pytest-runner plugin.
  • Moved most of the packaging configuration to setup.cfg.
  • Adopted black and isort for code formatting.
  • Migrated to tox for running tests.
  • Migrated to pre-commit for running linters and code formatters.
  • Migrated to GitHub Actions from Travis CI.

  [DM-22957 <https://jira.lsstcorp.org/browse/DM-22957>, DM-26288 <https://jira.lsstcorp.org/browse/DM-26288>]

• Documentation improvements:

  • Added a new Developer guide and Release procedure guide.
  • Added an installation page.
  • Moved the Python API reference to its own page.
  • Improved the README to list features.

• Added GitHub community health features: contributing, support, and code of conduct files.

---

Configuration

📅 Schedule: Branch creation - "before 6am on Monday" (UTC), Automerge - At any time (no schedule defined).

🚦 Automerge: Disabled by config. Please merge this manually once you are satisfied.

♻ Rebasing: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.

🔕 Ignore: Close this PR and you won't be reminded about this update again.

---

• If you want to rebase/retry this PR, check this box

---

This PR has been generated by Mend Renovate. View repository job log here.

[rra]

We're not updating the documentation build here.

[renovate]

Renovate Ignore Notification

Because you closed this PR without merging, Renovate will ignore this update. You will not get PRs for any future 1.x releases. But if you manually upgrade to 1.x then Renovate will re-enable minor and patch updates automatically.

If you accidentally closed this PR, or if you changed your mind: rename this PR to get a fresh replacement PR.