In past I wanted to compile two docs, a public and a private but I didn't want to split my source file (rst
).
First step I found the only
directive and I thought it was the solution. But when I wanted a entire full rst file in just public or private documentation I can't without indent the whole file.
So I write my own Sphinx plugin (scope) to manage all my case. To succeed I used the meta
directive that can be place on the top of the file.
Thus
a_doc_for_basic.rst
.. meta::
:scope: basic
Title
=====
My content
a_doc_for_code.rst
.. meta::
:scope: code
Title
=====
My content
And you can continue to use .. only::
directive on file
a_doc_for_all.rst
Title
=====
My content
.. only:: code
a piece of code
You can find plugin source here
As you can see the plugin is pretty simple and works thanks to regexp. That means (regexp) that there is limitation:
- The directive
.. meta:: :scope:
must be place at the top of the file (no line before) - The directive
.. meta:: :scope:
must match the regexp^\.\. meta::\s+:scope: ([a-zA-Z0-9_-]+)
- The directive
.. meta:: :scope:
can manage multiple tag but you can easily update the plugin for your needs - Plugin deviate the original use of
meta
directive docutils.sourceforge.net/docs/ref/rst/directives.html#meta
After that you can build your doc using the following command
sphinx-build ... -t <tag> ...
sphinx-build ... -t code ...
Other thing, you can use the same toctree
for all tag
because when compiling a doc per tag the toctree
will be edited by the plugin to generate a tree without reference to the no-matching documentation.
PS: my plugin is not perfect but I replied to my needs, you can inspired and update it.