-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 On 28/05/12 07:47, Viktor Haag wrote: > Sphinx's build obviously uses a multi-pass process in order to do its > work. I'm pretty convinced that what happens is Sphinx first > parses/assembles the /entire/ document that it can reach using only the > exclusions and rules about what files to look at, and the 'toctree' > contents directives it can find to assemble a massive tree of content > nodes.
It is far more subtle than that. For example all files (completely ignoring excludes) are read and you'll get errors for any files that have toctree even if they have been explicitly excluded. > Annoyingly, the processing for certain /kinds/ of things using this > massive tree doesn't all happen at once. For example, I /believe/ that > Sphinx uses the tree to process/assemble an index, large table of > contents structure, and so on, /separately/ from processing the nodes > to produce output text (in HTML, TeX, whatever). The PDF (via rst2pdf) TOC doesn't include the contents of all toctrees, but HTML does. > What this means is that you might have hiccups if you try to use > 'ifconfig', 'only' or similar types of conditional inclusion structures > /around/ structural markup that would appear in tables of contents, > indices, tables of references and so on, because those bits are parsed > separately, and the conditional inclusion directives really only affect > the /text output pass/. The references are particularly painful. References aren't structural in any way, just a reference to somewhere else. Not being able to use references in ifconfig sections is really painful. Even not being able to do headers was getting annoying since I wanted to use different wording in them depending on the context. > Given that Sphinx' operation works the way it does, I think that > properly implementing "conditional inclusion" that operates as you > would /hope/ it to is actually a very, very difficult problem (or > potentially very difficult). If Sphinx did only/ifconfig as the very first pass then things would work perfectly. The problem is it appears to do it in the middle which is what leads to all the problems. > You /might/ get more mileage out of using some /other/ preprocessor on > your RST sources /before/ you actually use Sphinx to do processing on > them, if you really have situations where you need to absolutely chop > out certain blocks of text before you let Sphinx even do anything with > them. All I'm doing in the preprocessor that I am writing is doing ifconfig as a first pass operation. Roger -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.11 (GNU/Linux) iEYEARECAAYFAk/D38sACgkQmOOfHg372QQFqACfZf1r6/lGIkVWoBuuk+Bz+uj7 Ya8AoIf2fHoRnMm3v11YbO1j1tM/5/fB =9Zyf -----END PGP SIGNATURE----- -- You received this message because you are subscribed to the Google Groups "sphinx-dev" group. To post to this group, send email to sphinx-dev@googlegroups.com. To unsubscribe from this group, send email to sphinx-dev+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en.
