conditional exclusion of rst files

[Alastair Dent]

I need to be able to exclude specific rst files, depending on a built parameter.

 

Is there an extension that will enable this?

[Koen]

I was having the same type of question:

I have a documentation project for division x and I would like
to have the same documentation for division Y but only some files are
different.

So question is, what is the best approach to setup a correct structure
for this?
(both should have a different build html)

What I would think as a structure:

top_dir
|
|---- MakeFile
|---- build
|---------divisionx
|---------doctrees
|---------html_div_x
|---------divisiony
|---------doctrees
|---------html_div_x
|---- sources
|------ conf.py
|------ index_division_x.rst
|------ index_division_y.rst
|------ general sources
|------ all general rst files
|------ divisionXspecific
|------- Specific rst files for x
|------ divisionYspecific
|------- specific rst files for y

So goal would be to reuse the general files and add
the specific files for every division.

At the moment I dont directly see how I could do this.
An exclude based on a build parameter would be nice.

Problem now is that the conf.py is linked to one index masterfile.

Only possibility I see now is to create two different sphinx projects
for each division and symlink the general rst files but this does
not feels as the proper way to do it?

If somebody has some pointers on this would be nice
to hear your opinion on this.

[Alastair Dent]

Hi,
I found I could do this using ifconfig extension and the exclusion list in config.py.

The ifconfig extension allows you to conditionally include text. The exclusion takes a list of rst files and excludes them from the build.

The syntax of exclude_patterns is:

exclude_patterns = ['anrstfile.rst', 'directorypath/']

There is one niggle with this exclude; if there is a relative link to any excluded file, then exclude_patterns is ignored and the file is included.

--
You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
To post to this group, send email to sphin...@googlegroups.com.
To unsubscribe from this group, send email to sphinx-dev+...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en.

[Kevin Horn]

The "only" directive might be useful too, depending on your use case.

Kevin Horn

[Viktor Haag]

On Wednesday, 20 July 2011 06:39:43 UTC-4, Alastair Dent wrote:

I need to be able to exclude specific rst files, depending on a built parameter.

 

Is there an extension that will enable this?

Here's what I've done:

1. In my doc set do something like this:

    .. only::

       .. toctree::

          :hidden:

 

          internal/foo

      Some text that refers to :doc:`foo <internal/foo>`.

2. On my sphinx command line do something like this:

    sphinx-build -t internal input-dir output-dir

3. In my conf.py do something like this:

    if tags.has("internal"):

       exclude_patterns = [ '.build' ]

    else:

       exclude_patterns = [ '.build', '.internal' ]

This seems to work. However, whenever I do a build that doesn't include -t internal, I get warnings from the sphinx processor that it can't find the files internal/foo.

I /assume/ that this is because even though I'm blocking with .. only::, the processor still does a first pass through where it builds all the "content" stuff (i.e. tries to find all files/nodes), and /then/ decides about what text to drop out.

So, really, all I'm doing here is relying on a system error to not include the file in the toc tree (because it's in an excluded dir), and the ..only:: to block out any text that /refers/ to the file with a user-visible link.

This doesn't strike me as optimal -- it would be a very useful feature to support conditional inclusion/exclusion of stuff at the "node" level (i.e. have conditional toc-trees, conditional file includes, and conditional blocks that could wrap around (for example) section headings...

This might, however, depending on how sphinx goes about doing its processing, be a non-trivial thing to do.

The right answer might very well be much more simply done with N different conf files, N different "contents" files, and a cunningly structured source tree to minimize duplication of source outside the conf and contents files... 8(

--

Viktor Haag

[Guenter Milde]

On 2011-11-23, Viktor Haag wrote:
> On Wednesday, 20 July 2011 06:39:43 UTC-4, Alastair Dent wrote:

>> I need to be able to exclude specific rst files, depending on a built
>> parameter.

You might try with a "condotional include" directive like

.. only:: ...
.. include:: foo.txt

> The right answer might very well be much more simply done with N different
> conf files, N different "contents" files, and a cunningly structured source
> tree to minimize duplication of source outside the conf and contents
> files... 8(

Maybe a version control system with good support for branches (git, ...)?

Günter

[Viktor Haag]

On Wednesday, 23 November 2011 16:19:22 UTC-5, Guenter Milde wrote:

You might try with a "condotional include" directive like

.. only:: ...
   .. include:: foo.txt

I tried that, and it didn't seem to work as I expected it to. I wondered whether the fact that include-ed file had contents structural elements in it (i.e .sections and such) was causing issues. I will investigate that more.

 

> The right answer might very well be much more simply done with N different
> conf files, N different "contents" files, and a cunningly structured source
> tree to minimize duplication of source outside the conf and contents
> files... 8(

Maybe a version control system with good support for branches (git, ...)?

Depending on how one likes to work, yes, that would be one way to go. In my case, I'd prefer to have a single source file that can support multiple build outputs so that I can account for the relatively small build variants I need to all while editing a single set of source, and then use a build script to mux it into all the built output I need. 

But if you have widely variant branches of content, or have to support many different kinds skewed by kind, content, or time (i.e. you have to support a 1.0 version of content at the same time as the 4.0 content), then I agree, a solidly branching version control system is probably a good thing to look into.

--
Viktor Haag