Adding custom tag in Sphinx

问题

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.

回答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.

来源：https://stackoverflow.com/questions/42798152/adding-custom-tag-in-sphinx

标签

python

python-sphinx