0

(Note: this is similar to Conditional output in Sphinx Documentation, but it's not clear if the solution there is usable.)

I have some documentation of two functions that are very similar. What I want to write is a file that would be included by the doc for both that looks like:

.. if:: doc_for_foo
  This documentation only applies to ``foo``.

.. if:: doc_for_bar
  This documentation only applies to ``bar``.

This documentation applies to both.

So, the common content would appear in two separate pages of the same generated documentation. Is there a way to do this? (I know about .. only, but it isn't clear how I would enable the relevant bits for each documentation page.)

Note: I don't want to just split the common stuff into separate files, because the content is significantly interleaved. That is, I would end up with:

Text about ``foo``.

.. include:: common-part-1

More text.

.. include:: common-part-2

.. for 'foo', no intervening text here

.. include:: common-part-3

More text.

.. include:: common-part-4

...and so on, where each part is perhaps a single paragraph. IOW, the former would be much easier to maintain.

To clarify, I want something like:

.. foo.rst

.. enable-tag:: doc_for_foo
.. include:: foo_and_bar_doc

.. bar.rst

.. enable-tag:: doc_for_bar
.. include:: foo_and_bar_doc

...where both foo.rst and bar.rst are generated by the same run of Sphinx. Passing -t at build time won't work; both foo.rst and bar.rst would (AFAIU) see the same set of tags set. Same with anything I did in conf.py.

Matthew
  • 2,593
  • 22
  • 25
  • Did you actually try using the directive [`only`](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#including-content-based-on-tags)? It does exactly what you want. – Steve Piercy Sep 28 '22 at 09:35
  • @StevePiercy, did you *read* the question? "I know about `.. only`, but it isn't clear how I would enable the relevant bits for each documentation page." If you know how to use `.. only` for this purpose, please post an answer. To wit, how do I enable a "tag" *for a specific page*? – Matthew Sep 28 '22 at 14:29
  • Did you *read* the documentation for `only` about how to use it? If that documentation is not clear about its usage, then what about it is not clear? – Steve Piercy Sep 29 '22 at 11:26
  • @StevePiercy, what part of "how do I enable a "tag" for a specific page?" was unclear? I can see how to affect `.. only` for *an entire build*. I *do not* see how to affect it on a per-page basis. Since you obviously are seeing something I am not, please elucidate. – Matthew Sep 29 '22 at 15:39
  • What part of the documentation that states "Undefined tags are false, defined tags (via the -t command-line option or within conf.py, see [here](https://www.sphinx-doc.org/en/master/usage/configuration.html#conf-tags)) are true. Boolean expressions, also using parentheses (like html and (latex or draft)) are supported." was not clear? – Steve Piercy Sep 30 '22 at 07:27
  • @StevePiercy, what part of "via the -t command-line option or within conf.py" explains how to set those *per page*? How am I not communicating clearly? – Matthew Sep 30 '22 at 14:15
  • 1
    I cannot help you when you do not read the whole sentence and follow the linked reference: "...see [here](https://www.sphinx-doc.org/en/master/usage/configuration.html#conf-tags)) are true." Perhaps your snark got in the way? – Steve Piercy Oct 01 '22 at 04:22

0 Answers0