Add docs on sphinx tags

[agjohnson]

Another Sphinx feature that would be helpful would be addition of Sphinx tags: http://www.sphinx-doc.org/en/stable/markup/misc.html#including-content-based-on-tags

It allows for having content like:

.. only:: footag

    Only in the Foo docs!

.. only:: bartag

    Only in the Bar docs!

The tags config option is already exposed in conf.py

[stsewd]

Seems very useful, I wonder how many people are aware of this functionality, maybe Sphinx heavy users, or maybe I was the only one that didn't know about this :grin:

[humitos]

Does it worth to implement this as a YAML option, add validation, modify the command, etc instead of just using the conf.py for this?

I mean, we need to do some extra work and I don't think we are adding any value by using the YAML file here. Instead, by using the conf.py we get the same benefits and the user just need to add:

# conf.py
tags.add('footag')

[stsewd]

There is only one downside of only using the conf.py file

Only tags set via the -t command-line option or via tags.add('tag') can be queried using tags.has('tag').

But not sure if that worth it

[stsewd]

Also, some useful tags are already provided

The format and the name of the current builder (html, latex or text) are always set as a tag [1]. To make the distinction between format and name explicit, they are also added with the prefix format_ and builder_, e.g. the epub builder defines the tags html, epub, format_html and builder_epub.

[humitos]

I'm not following you about the downside that you are mentioning here. Can you expand?

[stsewd]

@humitos I think this would be a downside if we pass tags per builder, so they are exposed on the config.py file or people only want some tags on rtd.

[humitos]

would be a downside if we pass tags per builder, so they are exposed on the config.py file

I don't understand this :confused:

or people only want some tags on rtd.

This is still possible and simpler:

# conf.py
if READTHEDOCS == 'True':
    tags.add('footag')
else:
    tags.add('bartag')

[stsewd]

Nevermind, I don't think that case is worth it p: But we could expose "something" to the rst files with a tag like -tag readthedocs and used it as

.. only:: readthedocs

[humitos]

That could be. It's another feature/issue, though. And it doesn't require to implement anything from our side. Just change the command on the builders to add that option.

Although, I don't think it's really useful.

[agjohnson]

I didn't realize sphinx exposed a tag element in the conf.py, that is a better ux. We should document this usage

[stsewd]

@agjohnson but you can't see the builder tags in the conf.py file

Only tags set via the -t command-line option or via tags.add('tag') can be queried using tags.has('tag').

[stsewd]

Just linking to the new docs http://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#including-content-based-on-tags

Also:

These standard tags are set after the configuration file is read, so they are not available there.

Not sure what we want to document here.

[agjohnson]

@stsewd what is the need to be able to see the tags? I don't think we need read access to them, just need to guide users to add them and use them.

I think what we want to document is "How to have conditional content in your documentation", which describes:

• Adding tags.add('foo') to your config
• Using only directive to make conditional content

I just tested this out, and it does work as I'd expect.

Thinking about this more however, I thought of an additional use case. Asking users to add a if READTHEDOCS block to their config is a) a bit hacky, or at least isn't a product-y feature and b) isn't version-dependent, it's only boolean whether or not we're on RTD. I could see some use cases for config dependent tags, like a tag for is_lts or something.

Another feature we could add is dropping our own tags into conf.py automatically. Assume we added tags like:

• is_stable
• is_latest
• is_on_readthedocs

Authors could use these to make version-dependent docs:

.. only:: is_stable

    This version is the most stable version

Mostly just brainstorming here, perhaps there are more tags we could add automatically? Also, these are mostly features to make docs more version specific. Perhaps it would be better served by an extension that inspects version from conf.py instead (something we could populate with a branch name? I'm not necessarily convinced we need version-specific tags, but perhaps it's a good idea?

[stsewd]

How to have conditional content in your documentation

Got it, that should be in our guides section https://docs.readthedocs.io/en/latest/guides/index.html.

I'm not sure if there is a need to add tags from the rtd side, users already have access to the version from the conf.py file, maybe we can add that to the guide?

Not sure about is_on_rtd tag, I can't think of a use case for that, people mostly want to see the same docs locally as in rtd p: And this tag can be added to the conf.py by the user using the env variable that we already expose.

[agjohnson]

Yup +1 on a guide for this.

They have access to the version, but most folks don't automate this or keep it up to date. I feel like we could be updating the version in conf.py for them. Hard to determine what is default and what is an intended value for version though, so we might not be able to automate this.

[stsewd]

Just pointing that we already set up a readthedocs tag, because we have a custom builder, see https://github.com/rtfd/readthedocs.org/issues/4765#issuecomment-431927720

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[agarwalrounak]

I will work on it.

I am new to Sphinx, so I might need a little guidance along the way:sweat_smile:

[ghost]

Is anyone still working on this? If I understand correctly, we need documentation on how to add tags in RTD using Sphinx? I can take this issue :)

[stsewd]

@potterwrit yes, you can submit a PR!

[akien-mga]

I'm confused by this issue. The RTD config exposes Tags in the admin section:

But they don't seem to be passed to Sphinx with the -t switch, so what's their use case? I just realized after a year that my i18n instances did not use the .. only:: i18n content I set for them due to this.

How can we pass tags via RTD without changing conf.py manually? (In my use case I have the original English docs and the localized instances all use the same conf.py, so the tag should be passed by RTD.)

[stsewd]

@akien-mga sorry for the confusion, these tags, are to clasify the version, they are not sphinx tags.

Also, we are removing those tags in the next release https://github.com/readthedocs/readthedocs.org/pull/5864

Maybe you could use env variables to have this? https://docs.readthedocs.io/en/stable/guides/environment-variables.html

[akien-mga]

@stsewd Thanks, environment variables + some logic to parse them and append the Sphinx tags object should do the trick indeed for my use case.

[Lokesh2703]

By just adding sphinx-tabs==1.1.13, I was able to get sphinx-tabs in my docs, Can I add this in doc that the user had to add sphinx-tabs==1.1.13 to the requirements.txt file in their repository to use sphinx-tabs in their RTD

[stsewd]

@Lokesh2703 this issue is about sphinx tags, not tabs https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#including-content-based-on-tags.

[astrojuanlu]

Should we try to contribute this upstream instead?

[stsewd]

Should we try to contribute this upstream instead?

If there are any improvements to the existing docs yeah, but we still need to document or put an example of how to use/expose tags specific to rtd, like https://github.com/readthedocs/readthedocs.org/issues/4603#issuecomment-438894865 and adding tags for if we are building the latest version like https://github.com/readthedocs/readthedocs.org/issues/4603#issuecomment-422108848

[Sachin-Suresh]

I am trying to add something like the below in conf.py, but I get syntax highlighted as - "tags is not defined".

exclude_patterns = ['**/*admin*']
if tags.has('adminmode'):
    exclude_patterns = []

Where do we declare or configure tags in conf?

[felixvd]

That's a Sphinx issue. tags is injected into the namespace in eval_config_file. This also affects conf files that import other conf files - the undefined tags object will raise NameError: name 'tags' is not defined.

This should be raised as an issue on Sphinx, but I'm commenting here because it comes up on Google. This workaround will silence the syntax highlights and allow imports from other conf files (e.g. when you want to build sub-trees of your doc as a PDF):

# Workaround to allow importing this file from other confs and remove 
if 'tags' not in locals():
    class Tags(dict):
        def has(self, tag):
            return tag in self
    tags = Tags()