Sections inside only:: tags do not show up in the html

[shimizukawa]

Please try to compile the attached example using: make html

---

• Bitbucket: https://bitbucket.org/birkenfeld/sphinx/issue/886
• Originally reported by: mateobur
• Originally created at: 2012-02-24T19:12:10.524

[shimizukawa]

From Georg Brandl on 2012-03-10 20:06:08+00:00

Duplicate of #795.

[shimizukawa]

From mateobur on 2012-08-10 12:48:32+00:00

The exact same issue seems to have reappeared.

Ubuntu 12.04
Sphinx 1.1.3

[shimizukawa]

From Jon Waltman on 2012-08-12 08:09:00+00:00

It wasn't ever really fixed; it just documented this as a known limitation of the only directive.

Due to docutils’ specifics of parsing of directive content, you cannot put a section with the same level as the main document heading inside an only directive. Such sections will appear to be ignored in the parsed document.

http://sphinx.pocoo.org/markup/misc.html?highlight=only%20dir#directive-only

[shimizukawa]

From mateobur on 2012-08-12 10:49:30+00:00

Thanks for the reply Jon,

But if you see the attached document, for example example2.rst

{{{
#!python

hello

---

example

bla bla

.. only:: randomtag

lacabr
======

blah blah

}}}

To me, it seems like 'hello' is the main document heading and the sections with "==" are secondary, but still, the second section isn't appearing in the document.

Sorry if this is me misunderstanding something.

[shimizukawa]

From Jon Waltman on 2012-08-12 11:15:47+00:00

Instead of the main document heading, I think it is actually the current heading.

That is, only sub-headings are handled correctly.

So this will work:

{{{
hello

---

example

bla bla

.. only:: randomtag

lacabr
------

blah blah

}}}

because the "--" heading is lower than "==".

[shimizukawa]

From mateobur on 2012-08-12 11:23:44+00:00

Thanks again for you attention,

But then, this is not completely useful because 'lacabr' will have to be a subsection of 'example' and will appear as such in the document index, what I really want is to have a same-level section only when I apply the tag. Maybe that's just not possible, but seems odd.

[shimizukawa]

From Jon Waltman on 2012-08-12 11:42:45+00:00

Yea, but it does avoid some ambiguous situations like the following:

{{{
top

---

Section A

bla bla

.. only:: randomtag

Section B
=========

blah blah

Subsection A.1 or B.1

blah blah
}}}

[shimizukawa]

From mateobur on 2012-08-12 11:49:11+00:00

If it has the same indentation level as B, it will be B.1, in your example A.1 :). It can't be a subsection of B in your example because B may not be there in the final document. Odd thing is, I have some documents where the same-level headers inside only:: tag work for some of the tags and not for others.

PD: I'm hanging around the #pocoo IRC channel if you want to chat directly.

[shimizukawa]

From Jon Waltman on 2012-08-12 17:41:59+00:00

I hacked together a new only directive that should work with nested and same-level headers. You try it out by adding the following to your conf.py

{{{
#!python

from docutils.parsers.rst import Directive
class ReallyOnly(Directive):
"""
Directive to only include text if the given tag(s) are enabled.
"""
has_content = True
required_arguments = 1
optional_arguments = 0
final_argument_whitespace = True
option_spec = {}

def run(self):
    from docutils import nodes
    from sphinx import addnodes
    from sphinx.util.nodes import set_source_info

    node = addnodes.only()
    node.document = self.state.document
    set_source_info(self, node)
    node['expr'] = self.arguments[0]

    # hack around title style bookkeeping
    surrounding_title_styles = self.state.memo.title_styles
    surrounding_section_level = self.state.memo.section_level
    self.state.memo.title_styles = []
    self.state.memo.section_level = 0
    try:
        result = self.state.nested_parse(self.content, 0, node,
                                         match_titles=1)
        depth = len(surrounding_title_styles)
        if self.state.memo.title_styles:
            style = self.state.memo.title_styles[0]
            if style in surrounding_title_styles:
                depth = surrounding_title_styles.index(style)
        parent = self.state.parent
        for i in xrange(len(surrounding_title_styles) - depth):
            if parent.parent:
                parent = parent.parent
        parent.append(node)
    finally:
        self.state.memo.title_styles = surrounding_title_styles
        self.state.memo.section_level = surrounding_section_level
    return []

def setup(app):
# from sphinx.directives import Only
app.add_directive('only', ReallyOnly)

# # pretty print doctree
# def dump_doctree(app, doctree, docname):
#     print '\n# %s\n%s\n' % (docname, doctree.pformat())
# app.connect('doctree-resolved', dump_doctree)

}}}

[shimizukawa]

From Georg Brandl on 2012-09-13 07:59:12+00:00

Closes #886: Fix handling of section headings in "only" directives.

→ <<cset 6654687>>

[shimizukawa]

From Georg Brandl on 2014-10-18 07:32:54+00:00

Removing version: 1.1.1 (automated comment)