On Monday, 28 May 2012 02:18:38 UTC-4, Roger Binns wrote: > > On 25/05/12 23:34, Roger Binns wrote: > > Does anyone have any guidance on how to get Sphinx to play nicely with > > ifconfig and toctree? > > I'm encountering yet more issues. This generates a warning about > undefined label abc when debug is False. > > normal > > .. ifconfig:: debug > > This doesn't show up. :ref:`abc` > > The warning is nonsensical - the section is not included and I have > verified the text is not present in the output. >
So, here's what I /think/ is going on with ifconfig, and only, and other conditional text inclusions. And once I made this assumption/realization, the reason it "doesn't work" makes a lot of sense to me. 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. /Then/ as it process that tree of nodes, it will leave out things that should get left out of a particular build by logic contained within the nodes themselves. (Such as 'ifconfig' and 'only' and etc.) 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). 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/. Once I made this assumption, I said "damn! these conditional inclusion directives are not nearly as useful as I thought", but it also let me suddenly figure out that to do certain kinds of conditional builds I had to rely on other techniques to do it. 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). 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. I hope this explanation is helpful to you -- I'm sorry if it's a bit long and/or rambly. (Also, it's possible it could be not entirely correct. 8( ) -- Viktor -- You received this message because you are subscribed to the Google Groups "sphinx-dev" group. To view this discussion on the web visit https://groups.google.com/d/msg/sphinx-dev/-/k0cYm5GpUdIJ. 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.
