-
Notifications
You must be signed in to change notification settings - Fork 650
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[ENH] Add tag options to _config.yml for conditional content #1630
base: master
Are you sure you want to change the base?
Conversation
Thanks for this PR and all of the explanation - I will try and figure out what's going on here :-) maybe @chrisjsewell also has a moment to look since he's more familiar with the guts of Sphinx's machinery than I am. One thing that would be helpful is a user-level explanation of this feature in the docs. What are tags and why would somebody want to use them? What's the minimal use-case that this functionality is designed for? Where can a person go to learn more if they really want to dive into this feature? I think motivating the PR with a clear example would be a helpful way to understand the value that this functionality is bringing. |
Thanks for the feedback. I'll look through the docs to see where this would fit. Quick answer here: a typical use is to mark content that is rendered only for certain builders or audiences. For example, a textbook might have additional content in the teacher edition. The _conf_teacher.yaml uses
Command
|
Latest commit adds explanation. Similar to toggling and cell tags, so I added it to hiding.md even though it's nested under web and internet features. Any advice on relocating? I considered placing into |
It looks like this PR has been left to languish. @choldgraf @chrisjsewell Any chance we can get something like this, or at least get |
I'd really value having optional content support. I'm trying to write some generic materials with optional elements , and the ability to have conditional content in generic files would be hugely beneficial, rather than having to create custom files that share 95% of the content, and custom toc files for different set-ups. [@agoose77 @choldgraf ] |
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