'only' directive exhibits strange behavior with headers

[shimizukawa]

When a heading inside an only block is of the same level of any heading present outside of the only block, that heading won't be displayed and neither will any content after that heading inside the only block.

Please see this reST for an example

The bug was reproduced on a clean VM with Xubuntu 12.10, Sphinx 1.1.3, Python 2.7.3 and no extensions enabled. Furthermore, the bug was reproduced by user 'nesv' on the #pocoo IRC channel.

Use case: I am documenting software which is tailored to user preferences. And for example, if the user wants the software without PostgeSQL support (as MongoDB is standard for our product) it is unnecessary to clutter, for example, the configuration documentation with many sections about PostgreSQL. So we would like to make these sections conditional depending on if the user chooses this.

---

• Bitbucket: https://bitbucket.org/birkenfeld/sphinx/issue/1115
• Originally reported by: Ernst Haagsman
• Originally created at: 2013-02-21T12:36:06.434

[shimizukawa]

From Takayuki Shimizukawa on 2013-02-21 14:53:10+00:00

I think that is sphinx (and docutils') limitation.
Your reST translated into node tree like below:

#!xml

<document source="/tmp/foo/index.rst">
    <comment xml:space="preserve">
        Quest for Sphinx Behavior documentation master file, created by
        sphinx-quickstart on Thu Feb 21 02:23:30 2013.
        You can adapt this file completely to your liking, but it should at least
        contain the root `toctree` directive.
    <section ids="welcome-to-quest-for-sphinx-behavior-s-documentation" names="welcome\ to\ quest\ for\ sphinx\ behavior's\ documentation!">
        <title>
            Welcome to Quest for Sphinx Behavior's documentation!
        <paragraph>
            Contents:
        <compound classes="toctree-wrapper">
            <toctree entries="" glob="False" hidden="False" includefiles="" maxdepth="2" numbered="0" parent="index" titlesonly="False">
        <only expr="platform">
            <paragraph>
                This gets displayed
            <section ids="a-title-at-another-level" names="a\ title\ at\ another\ level">
                <title>
                    A title at another level
                <paragraph>
                    This also gets displayed

There is no Similar title to headings in the rest of the document section that is higher level section than only directive depended.

As one way of the solutions to share the headlines throughout the file that means only directive did not include any headings.

Another way to separate the directory for every platform and specify which directory you want to build in the conf.py by using tags and exclude_patterns. (There is referred information but that written by Japanese http://sphinx-users.jp/cookbook/multidoc/index.html)

[shimizukawa]

From Jon Waltman on 2013-02-24 15:15:24+00:00

This behavior of the "only" directive has been changed since Sphinx 1.1.3 was released (see issue #886).

It now works as expected in most cases and you can use higher level headings than those of the surrounding section.

It appears that your example is one of the cases where it doesn't work as expected though. The section with the higher level heading "=" is treated as a subection of the first section "-".

This is how your example would be processed:

1. Document level heading
=========================

.. only:: tag or not tag

   1.1. Section
   ------------

   1.1.1. Expected to be Document level heading but output as subsection
   =====================================================================

   1.2 Section
   -----------

Which generates the following pseodoxml:

<document source="...">
    <section ids="document-level-heading" names="1.\ document\ level\ heading">
        <title>
            1. Document level heading
        <section ids="section" names="1.1.\ section">
            <title>
                1.1. Section
            <section ids="document-level-heading-but-output-as-subsection" names="1.1.1.\ document\ leve
                <title>
                    1.1.1. Document level heading but output as subsection
        <section ids="id1" names="1.2\ section">
            <title>
                1.2 Section

You can work around this so long as the first section in the "only" directive is not lower than any other sections within the "only" directive. Eg:

1. Document level heading
=========================

.. only:: tag or not tag

   1.1. Section
   ------------

.. only:: tag or not tag   

   2. Document level heading
   =========================

   2.1 Section
   -----------

The resulting pseodoxml is

<document source="...">
    <section ids="document-level-heading" names="1.\ document\ level\ heading">
        <title>
            1. Document level heading
        <section ids="section" names="1.1.\ section">
            <title>
                1.1. Section
    <section ids="id1" names="2.\ document\ level\ heading">
        <title>
            2. Document level heading
        <section ids="id2" names="2.1\ section">
            <title>
                2.1 Section

[shimizukawa]

From Ernst Haagsman on 2013-02-25 10:06:05+00:00

Confirmed, when I use the current development version it works as expected. Thanks for helping.

[shimizukawa]

From Takayuki Shimizukawa on 2013-02-26 06:11:04+00:00

fixed at #886 (after 1.1.3)