Common directive options:

Add "name" and "class" options to admonition directives.

Directive content may start on the first line also when the directive
type accepts options.

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk@7072 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

16 files changed, 84 insertions, 70 deletions

diff --git a/docutils/HISTORY.txt b/docutils/HISTORY.txt
index f5dc80f5b..915fed9a9 100644
--- a/docutils/HISTORY.txt
+++ b/docutils/HISTORY.txt
@@ -37,8 +37,11 @@ Changes Since 0.7
 
 * reStructuredText:
 
-  - most directives now support a "name" option that attaches a
+  - Most directives now support a "name" option that attaches a
     reference name.
+    
+  - Directive content may start on the first line also when the directive
+    type accepts options.
 
 * docs/dev/policies.txt:
 
diff --git a/docutils/docutils/parsers/rst/directives/admonitions.py b/docutils/docutils/parsers/rst/directives/admonitions.py
index 870b6659e..b5b60811e 100644
--- a/docutils/docutils/parsers/rst/directives/admonitions.py
+++ b/docutils/docutils/parsers/rst/directives/admonitions.py
@@ -11,35 +11,35 @@ __docformat__ = 'reStructuredText'
 
 from docutils.parsers.rst import Directive
 from docutils.parsers.rst import states, directives
+from docutils.parsers.rst.roles import set_classes
 from docutils import nodes
 
 
 class BaseAdmonition(Directive):
 
-    required_arguments = 0
-    optional_arguments = 0
     final_argument_whitespace = True
-    option_spec = {}
+    option_spec = {'class': directives.class_option,
+                   'name': directives.unchanged}
     has_content = True
 
     node_class = None
     """Subclasses must set this to the appropriate admonition node class."""
 
     def run(self):
+        set_classes(self.options)
         self.assert_has_content()
         text = '\n'.join(self.content)
-        admonition_node = self.node_class(text)
-        if self.arguments:
+        admonition_node = self.node_class(text, **self.options)
+        self.add_name(admonition_node)
+        if self.node_class is nodes.admonition:
             title_text = self.arguments[0]
             textnodes, messages = self.state.inline_text(title_text,
                                                          self.lineno)
             admonition_node += nodes.title(title_text, '', *textnodes)
             admonition_node += messages
-            if 'class' in self.options:
-                classes = self.options['class']
-            else:
-                classes = ['admonition-' + nodes.make_id(title_text)]
-            admonition_node['classes'] += classes
+            if not 'classes' in self.options:
+                admonition_node['classes'] += ['admonition-' +
+                                               nodes.make_id(title_text)]
         self.state.nested_parse(self.content, self.content_offset,
                                 admonition_node)
         return [admonition_node]
@@ -48,7 +48,6 @@ class BaseAdmonition(Directive):
 class Admonition(BaseAdmonition):
 
     required_arguments = 1
-    option_spec = {'class': directives.class_option}
     node_class = nodes.admonition
 
 
diff --git a/docutils/docutils/parsers/rst/directives/body.py b/docutils/docutils/parsers/rst/directives/body.py
index dd9b7be9c..90b7ce1ca 100644
--- a/docutils/docutils/parsers/rst/directives/body.py
+++ b/docutils/docutils/parsers/rst/directives/body.py
@@ -117,9 +117,6 @@ class ParsedLiteral(Directive):
 
 class MathBlock(Directive):
 
-    required_arguments = 0
-    optional_arguments = 1
-    final_argument_whitespace = True
     option_spec = {'class': directives.class_option,
                    'name': directives.unchanged}
                    ## TODO: Add Sphinx' ``mathbase.py`` option 'nowrap'?
@@ -128,12 +125,11 @@ class MathBlock(Directive):
 
     def run(self):
         set_classes(self.options)
-        if not self.arguments:
-            self.assert_has_content()
+        self.assert_has_content()
         # join lines, separate blocks
         content = '\n'.join(self.content).split('\n\n')
         _nodes = []
-        for block in self.arguments + content:
+        for block in content:
             if not block:
                 continue
             node = nodes.math_block(self.block_text, block, **self.options)
@@ -207,7 +203,6 @@ class Compound(Directive):
 
 class Container(Directive):
 
-    required_arguments = 0
     optional_arguments = 1
     final_argument_whitespace = True
     option_spec = {'name': directives.unchanged}
diff --git a/docutils/docutils/parsers/rst/directives/misc.py b/docutils/docutils/parsers/rst/directives/misc.py
index 43f299bab..b68446bb4 100644
--- a/docutils/docutils/parsers/rst/directives/misc.py
+++ b/docutils/docutils/parsers/rst/directives/misc.py
@@ -381,7 +381,6 @@ class DefaultRole(Directive):
 
     """Set the default interpreted text role."""
 
-    required_arguments = 0
     optional_arguments = 1
     final_argument_whitespace = False
 
@@ -434,7 +433,6 @@ class TestDirective(Directive):
 
     """This directive is useful only for testing purposes."""
 
-    required_arguments = 0
     optional_arguments = 1
     final_argument_whitespace = True
     option_spec = {'option': directives.unchanged_required}
diff --git a/docutils/docutils/parsers/rst/directives/parts.py b/docutils/docutils/parsers/rst/directives/parts.py
index b394544e4..55a4dd5ed 100644
--- a/docutils/docutils/parsers/rst/directives/parts.py
+++ b/docutils/docutils/parsers/rst/directives/parts.py
@@ -35,7 +35,6 @@ class Contents(Directive):
         else:
             return value
 
-    required_arguments = 0
     optional_arguments = 1
     final_argument_whitespace = True
     option_spec = {'depth': directives.nonnegative_int,
diff --git a/docutils/docutils/parsers/rst/directives/tables.py b/docutils/docutils/parsers/rst/directives/tables.py
index f8bb52add..fcf3c2b83 100644
--- a/docutils/docutils/parsers/rst/directives/tables.py
+++ b/docutils/docutils/parsers/rst/directives/tables.py
@@ -26,7 +26,6 @@ class Table(Directive):
     Generic table base class.
     """
 
-    required_arguments = 0
     optional_arguments = 1
     final_argument_whitespace = True
     option_spec = {'class': directives.class_option,
diff --git a/docutils/docutils/parsers/rst/states.py b/docutils/docutils/parsers/rst/states.py
index b76cd48c3..38ca80665 100644
--- a/docutils/docutils/parsers/rst/states.py
+++ b/docutils/docutils/parsers/rst/states.py
@@ -2111,8 +2111,8 @@ class Body(RSTState):
         if indented and (directive.required_arguments
                          or directive.optional_arguments
                          or option_spec):
-            for i in range(len(indented)):
-                if not indented[i].strip():
+            for i, line in enumerate(indented):
+                if not line.strip():
                     break
             else:
                 i += 1
@@ -2123,18 +2123,19 @@ class Body(RSTState):
             content = indented
             content_offset = line_offset
             arg_block = []
-        while content and not content[0].strip():
-            content.trim_start()
-            content_offset += 1
         if option_spec:
             options, arg_block = self.parse_directive_options(
                 option_presets, option_spec, arg_block)
-            if arg_block and not (directive.required_arguments
-                                  or directive.optional_arguments):
-                raise MarkupError('no arguments permitted; blank line '
-                                  'required before content block')
         else:
             options = {}
+        if arg_block and not (directive.required_arguments
+                              or directive.optional_arguments):
+            content = arg_block + indented[i:]
+            content_offset = line_offset
+            arg_block = []
+        while content and not content[0].strip():
+            content.trim_start()
+            content_offset += 1
         if directive.required_arguments or directive.optional_arguments:
             arguments = self.parse_directive_arguments(
                 directive, arg_block)
diff --git a/docutils/test/functional/expected/math_output_html.html b/docutils/test/functional/expected/math_output_html.html
index aac8b3ba4..7c9c72b4e 100644
--- a/docutils/test/functional/expected/math_output_html.html
+++ b/docutils/test/functional/expected/math_output_html.html
@@ -22,12 +22,14 @@ role specificator, <span class="formula">
 <div class="formula">
 <i>f</i>(<i>ϵ</i>) = <span class="fraction"><span class="ignored">(</span><span class="numerator">1</span><span class="ignored">)/(</span><span class="denominator">1 + exp<span class="array"><span class="arrayrow"><span class="bracket align-left">⎛</span></span><span class="arrayrow"><span class="bracket align-left">⎝</span></span></span><span class="fraction"><span class="ignored">(</span><span class="numerator"><i>ε</i></span><span class="ignored">)/(</span><span class="denominator"><i>k</i><sub><span class="text">B</span></sub><i>T</i></span><span class="ignored">)</span></span><span class="array"><span class="arrayrow"><span class="bracket align-right">⎞</span></span><span class="arrayrow"><span class="bracket align-right">⎠</span></span></span></span><span class="ignored">)</span></span>
 </div>
-<p>A display formula can also be given as directive argument, e.g.</p>
+<p>Content may start on the first line of the directive, e.g.</p>
 <div class="formula">
 <i>N</i> = <span class="fraction"><span class="ignored">(</span><span class="numerator"><span class="text">number of apples</span></span><span class="ignored">)/(</span><span class="denominator">7</span><span class="ignored">)</span></span>
 </div>
+<p>Equations can be labeled with a reference name using the <tt class="docutils literal">:name:</tt> option.
+See <a class="reference internal" href="#eq-m">eq:M</a> and <a class="reference internal" href="#eq-schrodinger">eq:schrödinger</a> below.</p>
 <p>The determinant of the matrix</p>
-<div class="formula">
+<div class="formula" id="eq-m">
 <b>M</b> = <span class="array"><span class="arrayrow"><span class="bracket align-left">⎛</span></span><span class="arrayrow"><span class="bracket align-left">⎜</span></span><span class="arrayrow"><span class="bracket align-left">⎝</span></span></span><span class="array"><span class="arrayrow">
 <span class="arraycell align-c">
 <i>a</i>
@@ -71,7 +73,7 @@ For example, the following sum and integral with limits:</p>
 <p>LaTeX-supported Unicode math symbols can be used in math roles and
 directives:</p>
 <p>The Schrödinger equation</p>
-<div class="formula">
+<div class="formula" id="eq-schrodinger">
 <i>i</i>ℏ<span class="fraction"><span class="ignored">(</span><span class="numerator">∂</span><span class="ignored">)/(</span><span class="denominator">∂<i>t</i></span><span class="ignored">)</span></span>Ψ = <i>Ĥ</i>Ψ, 
 </div>
 <p>with the <em>wave function</em> <span class="formula">
diff --git a/docutils/test/functional/expected/math_output_latex.html b/docutils/test/functional/expected/math_output_latex.html
index d9aa8ba45..54050f347 100644
--- a/docutils/test/functional/expected/math_output_latex.html
+++ b/docutils/test/functional/expected/math_output_latex.html
@@ -22,12 +22,14 @@ A_\text{c} =
 <pre class="math">
 f(\epsilon) = \frac{1}{1 + \exp\left(\frac{\varepsilon}{k_\text{B}T}\right)}
 </pre>
-<p>A display formula can also be given as directive argument, e.g.</p>
+<p>Content may start on the first line of the directive, e.g.</p>
 <pre class="math">
 N = \frac{\text{number of apples}}{7}
 </pre>
+<p>Equations can be labeled with a reference name using the <tt class="docutils literal">:name:</tt> option.
+See <a class="reference internal" href="#eq-m">eq:M</a> and <a class="reference internal" href="#eq-schrodinger">eq:schrödinger</a> below.</p>
 <p>The determinant of the matrix</p>
-<pre class="math">
+<pre class="math" id="eq-m">
 \mathbf{M} = \left(\begin{matrix}a&amp;b\\c&amp;d\end{matrix}\right)
 </pre>
 <p>is <tt class="math">
@@ -44,7 +46,7 @@ For example, the following sum and integral with limits:</p>
 <p>LaTeX-supported Unicode math symbols can be used in math roles and
 directives:</p>
 <p>The Schrödinger equation</p>
-<pre class="math">
+<pre class="math" id="eq-schrodinger">
 i\hbar \frac{\partial }{\partial t}\Psi  = \hat{H}\Psi ,
 </pre>
 <p>with the <em>wave function</em> <tt class="math">
diff --git a/docutils/test/functional/expected/math_output_mathjax.html b/docutils/test/functional/expected/math_output_mathjax.html
index 011697c73..b4e6b114b 100644
--- a/docutils/test/functional/expected/math_output_mathjax.html
+++ b/docutils/test/functional/expected/math_output_mathjax.html
@@ -25,14 +25,16 @@ role specificator, <span class="math">
 f(\epsilon) = \frac{1}{1 + \exp\left(\frac{\varepsilon}{k_\text{B}T}\right)}
 \end{equation*}
 </div>
-<p>A display formula can also be given as directive argument, e.g.</p>
+<p>Content may start on the first line of the directive, e.g.</p>
 <div class="math">
 \begin{equation*}
 N = \frac{\text{number of apples}}{7}
 \end{equation*}
 </div>
+<p>Equations can be labeled with a reference name using the <tt class="docutils literal">:name:</tt> option.
+See <a class="reference internal" href="#eq-m">eq:M</a> and <a class="reference internal" href="#eq-schrodinger">eq:schrödinger</a> below.</p>
 <p>The determinant of the matrix</p>
-<div class="math">
+<div class="math" id="eq-m">
 \begin{equation*}
 \mathbf{M} = \left(\begin{matrix}a&amp;b\\c&amp;d\end{matrix}\right)
 \end{equation*}
@@ -55,7 +57,7 @@ For example, the following sum and integral with limits:</p>
 <p>LaTeX-supported Unicode math symbols can be used in math roles and
 directives:</p>
 <p>The Schrödinger equation</p>
-<div class="math">
+<div class="math" id="eq-schrodinger">
 \begin{equation*}
 i\hbar \frac{\partial }{\partial t}\Psi  = \hat{H}\Psi ,
 \end{equation*}
diff --git a/docutils/test/functional/expected/math_output_mathml.xhtml b/docutils/test/functional/expected/math_output_mathml.xhtml
index 1e949a0a5..1298d349d 100644
--- a/docutils/test/functional/expected/math_output_mathml.xhtml
+++ b/docutils/test/functional/expected/math_output_mathml.xhtml
@@ -29,7 +29,7 @@ role specificator, <math xmlns="http://www.w3.org/1998/Math/MathML">
 <mrow><mi>ε</mi></mrow>
 <mrow><msub><mi>k</mi><mtext>B</mtext></msub><mi>T</mi></mrow></mfrac></mrow></mfenced></mrow></mfrac></mtd></mtr></mtable></math>
 </div>
-<p>A display formula can also be given as directive argument, e.g.</p>
+<p>Content may start on the first line of the directive, e.g.</p>
 <div>
 <math xmlns="http://www.w3.org/1998/Math/MathML" mode="display">
 <mtable>
@@ -38,8 +38,10 @@ role specificator, <math xmlns="http://www.w3.org/1998/Math/MathML">
 <mrow><mtext>number of apples</mtext></mrow>
 <mrow><mn>7</mn></mrow></mfrac></mtd></mtr></mtable></math>
 </div>
+<p>Equations can be labeled with a reference name using the <tt class="docutils literal">:name:</tt> option.
+See <a class="reference internal" href="#eq-m">eq:M</a> and <a class="reference internal" href="#eq-schrodinger">eq:schrödinger</a> below.</p>
 <p>The determinant of the matrix</p>
-<div>
+<div id="eq-m">
 <math xmlns="http://www.w3.org/1998/Math/MathML" mode="display">
 <mtable>
 <mtr>
@@ -79,7 +81,7 @@ For example, the following sum and integral with limits:</p>
 <p>LaTeX-supported Unicode math symbols can be used in math roles and
 directives:</p>
 <p>The Schrödinger equation</p>
-<div>
+<div id="eq-schrodinger">
 <math xmlns="http://www.w3.org/1998/Math/MathML" mode="display">
 <mtable>
 <mtr>
@@ -203,7 +205,7 @@ physical system changes in time.</p>
 <p>Cases with the <a class="reference external" href="ftp://ftp.ams.org/ams/doc/amsmath/short-math-guide.pdf">AMSmath</a> <tt class="docutils literal">cases</tt> environment (not (yet) supported by
 HTML writers with <tt class="docutils literal"><span class="pre">--math-output=MathML</span></tt>):</p>
 <div class="system-message">
-<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">functional/input/data/math.txt</tt>, line 102)</p>
+<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">functional/input/data/math.txt</tt>, line 108)</p>
 <p>
 Environment not supported! Supported environment: "matrix".</p>
 <pre class="literal-block">
diff --git a/docutils/test/functional/expected/standalone_rst_latex.tex b/docutils/test/functional/expected/standalone_rst_latex.tex
index b5ff60f1f..2db3ff0cb 100644
--- a/docutils/test/functional/expected/standalone_rst_latex.tex
+++ b/docutils/test/functional/expected/standalone_rst_latex.tex
@@ -1646,15 +1646,20 @@ role specificator, $n! + \sin(x_n^2)$ and $A_\text{c} =
 \begin{equation*}
 f(\epsilon) = \frac{1}{1 + \exp\left(\frac{\varepsilon}{k_\text{B}T}\right)}
 \end{equation*}
-A display formula can also be given as directive argument, e.g.
+Content may start on the first line of the directive, e.g.
 %
 \begin{equation*}
 N = \frac{\text{number of apples}}{7}
 \end{equation*}
+Equations can be labeled with a reference name using the \texttt{:name:} option.
+See \hyperref[eq-m]{eq:M} and \hyperref[eq-schrodinger]{eq:schrödinger} below.
+
 The determinant of the matrix
 %
 \begin{equation*}
 \mathbf{M} = \left(\begin{matrix}a&b\\c&d\end{matrix}\right)
+\phantomsection
+\label{eq-m}
 \end{equation*}
 is $|\mathbf{M}| = ad - bc$.
 
@@ -1674,6 +1679,8 @@ The Schrödinger equation
 %
 \begin{equation*}
 i\hbar \frac{\partial }{\partial t}\Psi  = \hat{H}\Psi ,
+\phantomsection
+\label{eq-schrodinger}
 \end{equation*}
 with the \emph{wave function} $\Psi $, describes how the quantum state of a
 physical system changes in time.
diff --git a/docutils/test/functional/input/data/math.txt b/docutils/test/functional/input/data/math.txt
index bd2190aad..15acdcdd0 100644
--- a/docutils/test/functional/input/data/math.txt
+++ b/docutils/test/functional/input/data/math.txt
@@ -10,13 +10,16 @@ role specificator, :math:`n! + \sin(x_n^2)` and `A_\text{c} =
 
    f(\epsilon) = \frac{1}{1 + \exp\left(\frac{\varepsilon}{k_\text{B}T}\right)}
 
-A display formula can also be given as directive argument, e.g.
+Content may start on the first line of the directive, e.g.
 
 .. math:: N = \frac{\text{number of apples}}{7}
 
+Equations can be labeled with a reference name using the ``:name:`` option.
+See `eq:M`_ and `eq:schrödinger`_ below.
+
 The determinant of the matrix
 
-.. math::
+.. math:: :name: eq:M
 
    \mathbf{M} = \left(\begin{matrix}a&b\\c&d\end{matrix}\right)
 
@@ -36,7 +39,10 @@ directives:
 
 The Schrödinger equation
 
-.. math:: i\hbar \frac{∂}{∂t}Ψ = \hat{H}Ψ,
+.. math:: :name: eq:schrödinger
+
+   i\hbar \frac{∂}{∂t}Ψ = \hat{H}Ψ,
+   
 
 with the *wave function* :math:`Ψ`, describes how the quantum state of a
 physical system changes in time.
diff --git a/docutils/test/test_parsers/test_rst/test_directives/test_admonitions.py b/docutils/test/test_parsers/test_rst/test_directives/test_admonitions.py
index 30870f3d5..c4a01800d 100755
--- a/docutils/test/test_parsers/test_rst/test_directives/test_admonitions.py
+++ b/docutils/test/test_parsers/test_rst/test_directives/test_admonitions.py
@@ -21,7 +21,10 @@ totest['admonitions'] = [
 ["""\
 .. Attention:: Directives at large.
 
-.. Note:: This is a note.
+.. Note:: :name: mynote
+   :class: testnote
+
+   Admonitions support the generic "name" and "class" options.
 
 .. Tip:: 15% if the
    service is good.
@@ -49,9 +52,9 @@ totest['admonitions'] = [
     <attention>
         <paragraph>
             Directives at large.
-    <note>
+    <note classes="testnote" ids="mynote" names="mynote">
         <paragraph>
-            This is a note.
+            Admonitions support the generic "name" and "class" options.
     <tip>
         <paragraph>
             15% if the
@@ -147,12 +150,13 @@ totest['admonitions'] = [
 ["""\
 .. admonition:: Admonition
    :class: emergency
+   :name: reference name
 
    Test the "class" override.
 """,
 """\
 <document source="test data">
-    <admonition classes="emergency">
+    <admonition classes="emergency" ids="reference-name" names="reference\ name">
         <title>
             Admonition
         <paragraph>
diff --git a/docutils/test/test_parsers/test_rst/test_directives/test_compound.py b/docutils/test/test_parsers/test_rst/test_directives/test_compound.py
index 0b7ba6eee..c27030fb0 100755
--- a/docutils/test/test_parsers/test_rst/test_directives/test_compound.py
+++ b/docutils/test/test_parsers/test_rst/test_directives/test_compound.py
@@ -55,6 +55,8 @@ totest['compound'] = [
 """],
 ["""\
 .. compound::
+   :name: interesting
+   :class: log
 
    This is an extremely interesting compound paragraph containing a
    simple paragraph, a literal block with some useless log messages::
@@ -68,7 +70,7 @@ totest['compound'] = [
 """,
 """\
 <document source="test data">
-    <compound>
+    <compound classes="log" ids="interesting" names="interesting">
         <paragraph>
             This is an extremely interesting compound paragraph containing a
             simple paragraph, a literal block with some useless log messages:
@@ -81,20 +83,17 @@ totest['compound'] = [
             of the first simple paragraph, with the literal block in between.
 """],
 ["""\
-.. compound:: arg1 arg2
+.. compound:: content may start on same line
 
-   text
+   second paragraph
 """,
 """\
 <document source="test data">
-    <system_message level="3" line="1" source="test data" type="ERROR">
+    <compound>
         <paragraph>
-            Error in "compound" directive:
-            no arguments permitted; blank line required before content block.
-        <literal_block xml:space="preserve">
-            .. compound:: arg1 arg2
-            \n\
-               text
+            content may start on same line
+        <paragraph>
+            second paragraph
 """],
 ]
 
diff --git a/docutils/test/test_parsers/test_rst/test_directives/test_parsed_literals.py b/docutils/test/test_parsers/test_rst/test_directives/test_parsed_literals.py
index 61c12ad42..6cfefeaa7 100755
--- a/docutils/test/test_parsers/test_rst/test_directives/test_parsed_literals.py
+++ b/docutils/test/test_parsers/test_rst/test_directives/test_parsed_literals.py
@@ -47,16 +47,12 @@ totest['parsed_literals'] = [
          This is a parsed literal block with options.
 """],
 ["""\
-.. parsed-literal:: argument
+.. parsed-literal:: content may start on same line
 """,
 """\
 <document source="test data">
-    <system_message level="3" line="1" source="test data" type="ERROR">
-        <paragraph>
-            Error in "parsed-literal" directive:
-            no arguments permitted; blank line required before content block.
-        <literal_block xml:space="preserve">
-            .. parsed-literal:: argument
+    <literal_block xml:space="preserve">
+        content may start on same line
 """],
 ["""\
 .. parsed-literal::