search

sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.61k stars 2.13k forks source link

Set conditional tags for use during inclusion #13024

Open nedbat opened 1 month ago

nedbat commented 1 month ago

I would like to have a common file that will be included in multiple places in my docs. I want to be able to use .. only:: directives in that common file, and have tags set differently by different .. include: directives so that the content is customize for each place it is included.

For example (with invented :tags: syntax):

.. common.rst

This is for everyone

.. only:: red

    Hello red team!

.. only:: blue

    Hello blue team!
Red team
========

This is for red team.

.. include:: common.rst
   :tags: red
AA-Turner commented 1 month ago

I think this is reasonable, but it would mean that include directives have unique rules w.r.t. tags.

Thoughts @chrisjsewell @picnixz?

A

timhoffm commented 1 month ago

The request sounds reasonable.

it would mean that include directives have unique rules w.r.t. tags.

Yes, include must influence the tags one way or the other.

Thoughts on the implementation: Tags are currently a constant global setting. Obviously, that has to be changed. There are fundamentally two ways:

  1. make tags non-constant: i.e. temporarly override the global value (think: context manager) while processing the include.

  2. make tags document-local: Tags are currently stored in the app / builder. We could attach the tags to the document instead.