diff options
| author | Stephen Finucane <stephen@that.guru> | 2018-03-21 13:45:01 +0000 |
|---|---|---|
| committer | Stephen Finucane <stephen@that.guru> | 2018-03-27 15:37:28 +0100 |
| commit | fdf91e502c37b298ca852867f3457eb4ea7da6e0 (patch) | |
| tree | 203d9938c22768673b8a7d11c7ee96694f541d12 | |
| parent | 0167c009c26773bca12188a1f9c365982f33c2d2 (diff) | |
| download | sphinx-git-fdf91e502c37b298ca852867f3457eb4ea7da6e0.tar.gz | |
doc: Add "directives" doc to restructuredtext section
There's simply no need to artificially divide up the documentation on
directives into multiple, hard-to-navigate documents. Gather all
documentation for directives into one easy-to-reference guide, starting
with the former 'toctree' document. There are no changes to the content.
Signed-off-by: Stephen Finucane <stephen@that.guru>
| -rw-r--r-- | doc/glossary.rst | 2 | ||||
| -rw-r--r-- | doc/markup/index.rst | 3 | ||||
| -rw-r--r-- | doc/usage/restructuredtext/basics.rst | 4 | ||||
| -rw-r--r-- | doc/usage/restructuredtext/directives.rst (renamed from doc/markup/toctree.rst) | 17 | ||||
| -rw-r--r-- | doc/usage/restructuredtext/index.rst | 1 |
5 files changed, 21 insertions, 6 deletions
diff --git a/doc/glossary.rst b/doc/glossary.rst index 216277f41..ef8742d00 100644 --- a/doc/glossary.rst +++ b/doc/glossary.rst @@ -32,7 +32,7 @@ Glossary Content of the directive. - See :ref:`directives` for more information. + See :ref:`rst-directives` for more information. document name Since reST source files can have different extensions (some people like diff --git a/doc/markup/index.rst b/doc/markup/index.rst index 33e876556..792114878 100644 --- a/doc/markup/index.rst +++ b/doc/markup/index.rst @@ -1,5 +1,3 @@ -.. _sphinxmarkup: - Sphinx Markup Constructs ======================== @@ -9,7 +7,6 @@ facilities. .. toctree:: - toctree para code misc diff --git a/doc/usage/restructuredtext/basics.rst b/doc/usage/restructuredtext/basics.rst index 0bfb311c1..76cbe8ae4 100644 --- a/doc/usage/restructuredtext/basics.rst +++ b/doc/usage/restructuredtext/basics.rst @@ -303,7 +303,7 @@ normal paragraphs. This may all sound a bit complicated, but it is intuitive enough when you write it.) -.. _directives: +.. _rst-directives: Directives ---------- @@ -371,7 +371,7 @@ Docutils supports the following directives: Do *not* use the directives :dudir:`sectnum`, :dudir:`header` and :dudir:`footer`. -Directives added by Sphinx are described in :ref:`sphinxmarkup`. +Directives added by Sphinx are described in :doc:`directives`. Basically, a directive consists of a name, arguments, options and content. (Keep this terminology in mind, it is used in the next chapter describing diff --git a/doc/markup/toctree.rst b/doc/usage/restructuredtext/directives.rst index 51401ba50..4f9b3cc9e 100644 --- a/doc/markup/toctree.rst +++ b/doc/usage/restructuredtext/directives.rst @@ -1,4 +1,20 @@ .. highlight:: rst + +========== +Directives +========== + +:ref:`As previously discussed <rst-directives>`, a directive is a generic block +of explicit markup. While Docutils provides a number of directives, Sphinx +provides many more and uses directives as one of the primary extension +mechanisms. + +.. seealso:: + + Refer to the :ref:`reStructuredText Primer <rst-directives>` for an overview + of the directives provided by Docutils. + + .. _toctree-directive: Table of contents @@ -237,6 +253,7 @@ The special document names (and pages generated for them) are: * Do not use the plus ``+`` for the ePub format. Some resources may not be found. + .. rubric:: Footnotes .. [#] The LaTeX writer only refers the ``maxdepth`` option of first toctree diff --git a/doc/usage/restructuredtext/index.rst b/doc/usage/restructuredtext/index.rst index 5ff872f0d..75aedf4dd 100644 --- a/doc/usage/restructuredtext/index.rst +++ b/doc/usage/restructuredtext/index.rst @@ -17,4 +17,5 @@ __ http://docutils.sourceforge.net/rst.html basics roles + directives field-lists |