[ENH] Add tag options to _config.yml for conditional content #1630
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.
Add support to specify tags in
_config.yml
. Requires Jupyter Book processing of the Sphinx object (app
) insphinx_build
to manipulate tags, similar to howlatex_documents
are configured. No support for adding tags in the jupyter book command line.This addresses issue #1290 (mistakenly refers to "open" directive). Possibly also #1425.
(comment similar to the prior PR #1618 for command line tags)
The background context is that the tags are set, added, and removed during initialization of a Sphinx object. Sphinx achieves this by executing
conf.py
to call the Tags.add() and Tags.remove() methods. That's whyconf.py
contains lines liketags.add('cowboy')
and tag entries in theconfoverrides
dict passed tobuild_sphinx
result in warnings when building (e.g.,WARNING: unknown config value 'tags_add' in override, ignoring
).Users may add/remove tags in
_config.yml
likeChanges
config.yaml_to_sphinx()
parses the_config.yml
and the keystags_add
andtags_remove
are removed from thesphinx_config
dict and returned in a separate dict.config.get_final_config()
handles updating a default with this user-supplied config and also returns this new dict.cli.main.sphinx()
uses this new dict to append thetags.add()
andtags.remove()
lines when writingconf.py
, andsphinx.build_sphinx()
uses the new dict to adjustapp.tags.tags
:Note that passing the new
conf.py
and its locationconfdir
to Sphinx in sphinx.build_sphinx() (below) would handle adding and removing tags, but is prevented because ofpatch_docutils
. I don't know why that is there, so it's probably not wise to tinker with it. But I think that would be an alternate entry point.After initialization, the Spinx object is reconfigured with the new dict created through parsing
_config.yml