Georg Brandl committed 9487748

A bit of domain documentation.

Comments (0)

Files changed (5)

+   domains
+.. _domains:
+Sphinx Domains
+.. todo:: Write this section.
       the :term:`source directory`, but can be set differently with the **-c**
       command-line option.
+   directive
+      A reStructuredText markup element that allows marking a block of content
+      with special meaning.  Directives are supplied not only by docutils, but
+      Sphinx and custom extensions can add their own.  The basic directive
+      syntax looks like this::
+         .. directivename:: argument ...
+            :option: value
+            Content of the directive.
+      See :ref:`directives` for more information.
+   domain
+      A domain is a collection of markup (reStructuredText :term:`directive`\ s
+      and :term:`role`\ s) to describe and link to :term:`object`\ s belonging
+      together, e.g. elements of a programming language.  Directive and role
+      names in a domain have names like ``domain:name``, e.g. ``py:function``.
+      Having domains means that there are no naming problems when one set of
+      documentation wants to refer to e.g. C++ and Python classes.  It also
+      means that extensions that support the documentation of whole new
+      languages are much easier to write.  For more information about domains,
+      see the chapter :ref:`domains`.
       A structure where information about all documents under the root is saved,
       and used for cross-referencing.  The environment is pickled after the
       directive" (e.g. :dir:`function` or :dir:`object`) creates such a block;
       and most objects can be cross-referenced to.
+   role
+      A reStructuredText markup element that allows marking a piece of text.
+      Like directives, roles are extensible.  The basic syntax looks like this:
+      ``:rolename:`content```.  See :ref:`inlinemarkup` for details.
    source directory
       The directory which, including its subdirectories, contains all source
       files for one Sphinx project.


 .. versionadded:: 0.4
-.. XXX this is only for Python
+.. XXX this is only correct for Python
 Inside object description directives, reST field lists with these fields are
 recognized and formatted nicely:
 to the same level of indentation.
+.. _inlinemarkup:
 Inline markup
 when you write it.)
+.. _directives: