Re: [Docutils-users] Class Directive

[Guenter M. <mi...@us...>]

On 2015-08-14, Paul VonZimmerman wrote:

> [-- Type: text/plain, Encoding:  --]

> Hi everyone, having a lot of trouble figuring out how to define what
> content get's a particular class.

>  .. class:: drop-down

>     This is a header
>     ++++++++++++++++

>     I'm a bit of content

>     An H2
>     =====


Here, this example aborts with an 

 /tmp/class-arg.rst:4: (SEVERE/4) Unexpected section title.

error. This is in accordance with the documentation: section titles cannot
be nested in any directive. OTOH, the class directive 

  sets the "classes" attribute value on its content or on the first
  immediately following [4] non-comment element

  -- http://docutils.sourceforge.net/docs/ref/rst/directives.html#class

i.e. with the form::

  Leading text

  .. class:: drop-down
  
  This is a header
  ++++++++++++++++
  
  I'm a bit of content
  
  An H2
  =====

  Text in section 1.1 is a part of section 1.

the "drop-down" class argument is applied to section 1 "This is a header".

The document tree looks like 

  <document source="/tmp/class-arg.rst">
      <paragraph>
          Leading text
      <section classes="drop-down" ids="this-is-a-header" names="this\ is\ a\ header">
          <title>
              This is a header
          <paragraph>
              I’m a bit of content
          <section ids="an-h2" names="an\ h2">
              <title>
                  An H2
              <paragraph>
                  Text in section 1.1 is a part of section 1.

(output of rst2pseudoxml.py)



> So, what I want to do is make the H2 element not have the class "drop-down"
> applied to it. I've tried different indentations, etc. The only thing that
> seems to work is placing H1 before the h2, this seems to be the only thing
> that ends the class. Any help would be appreciated! Thank you!

There are some limitatins of the simple text input format rST:

You cannot give a class to the "title" element, only to the "section" element.

In Docutils, sections are nested. You cannot end a subsection and continue
the parent section. 

Depending on what you want to achieve, you may choose between several
workarounds:

* same level headings::

    .. class:: drop-down
    
    This is a header
    ++++++++++++++++
    
    I'm a bit of content
    
    next section of same level
    ++++++++++++++++++++++++++
    
* "overwrite" with more specific class arg::

  .. class:: drop-down
  
  This is a header
  ++++++++++++++++
  
  I'm a bit of content
  
  .. class:: not-drop-down
  
  An H2
  =====

* custom role for class with very limited scope
  http://docutils.sourceforge.net/docs/ref/rst/directives.html#custom-interpreted-text-roles
  ::

  .. role:: drop-down
  
  :drop-down:`This is a header`
  +++++++++++++++++++++++++++++
  
  I'm a bit of content
  
  An H2
  =====



* live with it and write more specific CSS rules.


If you explain what you want to achieve, we may find a way...

Günter