Adding custom tag in Sphinx

Question

I am using Sphinx tool for documentation and ran into a situation where I want to expose a piece of information in only one file format.
I came across this link which addresses a similar issue with help of only directive.

The issue I am facing is I want to use the only directive with a custom tag

.. only:: xyz

  ..directive ::
    :maxdepth: 1

    good_stuff

I am using a setup.py file for building, and running BuildDoc.run(self) to generate the html files. I want somehow pass this custom tag in the setup.py file. I tried doing this, but seems like we cant access tags object from within setup.py file.

 def run(self):
    self.builder = 'html'
    *self.tags.add(xyz)*
    BuildDoc.run(self)
    self.zip("html.zip")

If I add tags.add('xyz') in the conf.py file, it will always expose the additional information, what I want to do is conditionally add this tag in my setup.py file.
I assume the make command does something similar by passing the tag info to the conf.py file but I am not sure how it works.

Leahy

Answer 1

The sphinx-build command accepts a -t option, which allows you to specify a tag you can then use in an only condition.

From sphinx-build --help:

    -t TAG            define tag: include "only" blocks with TAG

So using something like:

sphinx-build -t xyz

Will allow you to use the .. only:: xyz conditional inline.

---

It seems to me that if you want to conditionally apply tags in your setup.py file, you'd have to write the logic yourself to determine if you should include self.tags.add('xyz') or not.

Cabdriver

I added tags.add('my-tag') in conf.py. And the line highlights in conf.py and says tags is not defined. Can you please tell the right steps how to use this? What is the right usage of command . I am using: sphinx-build -t my-tag . build/html, I get: WARNING: exception while evaluating only directive expression: chunk after expression – Hyperextension

Answer 2

For using tags define function setup in your conf.py.

Example: get environment variable IS_INTERNAL and when is True add tag internal:

from os import environ
from typing import Final


def setup(app):
    "Add tag 'internal'"

    IS_INTERNAL: Final[bool] = bool(environ.get("IS_INTERNAL", False))

    if IS_INTERNAL:
        app.tags.add('internal')

Bestrew