I use the include directive for a lot of this kind of case. The other thing you can do is construct the RST using some kind of program, from some sort of source files before passing them off to Sphinx.
It seems eminently possible to write an extension to Sphinx like the one you propose, and I don't want to discourage you from writing this kind of extension: it will be generally applicable, and feel like a native part of restructured text. Really what you're doing is extending rst/docutils *not* Sphinx, though you'd probably end up using a little Sphinx glue. At the same time, these kinds of extensions will run during the "read" phase of the Sphinx build, which is entirely single threaded at the moment, and because you're really extending rst, (some) of your text will become non-portable. So there are trade-offs, but then there always are. I'm interested in seeing what you come up with, please keep us posted! Cheers, sam On Tuesday, February 25 2014, 01:23:38, Ondřej Grover wrote: > Hello, > > I'd like to use Sphinx as a documentation tool for a big documentation > repository. > All the information is distributed in small ReST files in a directory > hierarchy. > These files have paragraphs with labels just before them, so they can be > referred to from anywhere using :ref: > > However, I'd like to use some directive like :includeref:`target`, which > instead of linking would include that paragraph. Does something like that > exist? > > The purpose is to have several master documents and in each one define > which paragraphs should be included, so for different tasks there would be > different outputs, but the documentation source would be the same for all > of them. > > As far as I understand Sphinx, I could achieve something similar with either > a) using an include directive, but that would mean each paragraphs would > have to be in a separate file > b) using the toctree directive with the :hidden: option. However, Sphinx > would complain if I stated only certain parts of the source repo and it > seems I would also have to split paragraphs into files. > c) instead of labels, define paragraphs as substitutions in those small > files and then include teh needed files and use the substitutions where > needed. > > Is there some simpler way? > > As for generating separate output (both html and latex/pdf) for each master > file, is there some simpler way than making a shell script that runs > sphinx-build for each master file and its conf.py? Scripting it would be > possible, but that would mean that the whole source repo is read each time. > > Kind regards, > Ondrej G. -- Sam Kleinman (tychoish): - [email protected] - tychoish <http://tychoish.com/> "don't get it right, get it written" -- james thurber -- You received this message because you are subscribed to the Google Groups "sphinx-users" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. Visit this group at http://groups.google.com/group/sphinx-users. For more options, visit https://groups.google.com/groups/opt_out.
