DM-41296: Migrate out of documenteer.sphinxext namespace #193
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
jonathansick
force-pushed
the
tickets/DM-41296
branch
3 times, most recently
from
09b5f78
to
0e3c99a
Compare
- Migrate the bibtex, jira, lsstdocushare, mockcoderefs, packagetoctree and lssttasks Sphinx extensions for documenteer.sphinxext to documenteer.ext, where all new extensions are being added. - Drop the original documenteer.sphinxconfig package; all Pipelines configurations are now done through the documenteer.conf.pipelines configuration module.
This ensures that all guides automatically include the sphinx-jinja dependency. They will need to configure their context in their own conf.py files, though.
Now documenteer.conf.pipelines imports its base configuration from documenteer.conf.guide. This allows us to retire the original theme, lsst-sphinx-bootstrap-theme. It'll also help us unify the pipelines documentation with the overall engineering and support we have for Rubin guides in general. The pipelines configuration add additional extensions. It still makes sense to ship this as a configuration through documenteer because individual packages will use documenteer.conf.pipelinespkg to do single package documentation previews. Since the guides configuration uses documenteer.toml, it might make sense to migrate manifest.yaml into documenteer.toml as a separate table.
This CLI was developed for the original technotes to vendor bibtex files from lsst/lsst-texmf. Documenteer's technotes now download and cache bib files automatically.
This CLI was the predecessor for stack-docs. It should be fully deprecated at this point.
This makes it convenient to create redirect pages when documentation is moved or renamed. https://sphinxext-rediraffe.readthedocs.io/en/latest/
This is the initial move with rediraffe redirects. More work is needed to make the content reflect the new relationship between guides and the specific pipelines docs use case.
jonathansick
force-pushed
the
tickets/DM-41296
branch
from
0e3c99a
to
cde778d
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Backwards-incompatible changes
Delete the
refresh-lsst-bibCLI command. Technotes now automatically vendor lsst-texmf's bib files and cache them usingdocumenteer.ext.githubbibcache.Delete the
build-stack-docsCLI command, which was replaced by thestack-docsandpackage-docsCLIs in Documenteer 0.3.0.The
documenteer.conf.pipelinesanddocumenteer.conf.pipelinespkgconfiguration modules now derive fromdocumenteer.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, thelsst-sphinx-bootstrap-themeis no longer used by Documenteer.The
documenteer.sphinxextmodule has been removed and the existing Sphinx extensions within it are now available fromdocumenteer.ext. It's no longer possible to usedocumenteer.sphinxextto automatically load all Documenteer Sphinx extensions. Extensions need to now be added individually to theextensionsconfiguration variable inconf.py. The migrated extension modules are:documenteer.ext.bibtexdocumenteer.ext.jiradocumenteer.ext.lsstdocusharedocumenteer.ext.lssttasksdocumenteer.ext.mockcoderefsdocumenteer.ext.packagetoctreeNew features
sphinx-jinjato the Rubin guides configuration by default.sphinx-rediraffeto the Rubin guides configuration by default.