diff --git a/doc/usage/domains/c.rst b/doc/usage/domains/c.rst index a4661658d..833cb5c57 100644 --- a/doc/usage/domains/c.rst +++ b/doc/usage/domains/c.rst @@ -1,7 +1,8 @@ .. highlight:: rst +============ The C Domain ------------- +============ The C domain (name **c**) is suited for documentation of C API. @@ -126,7 +127,7 @@ The C domain (name **c**) is suited for documentation of C API. .. _c-roles: Cross-referencing C constructs -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------ The following roles create cross-references to C-language constructs if they are defined in the documentation: @@ -151,7 +152,7 @@ are defined in the documentation: Anonymous Entities -~~~~~~~~~~~~~~~~~~ +------------------ C supports anonymous structs, enums, and unions. For the sake of documentation they must be given some name that starts with @@ -197,7 +198,7 @@ Explicit ref: :c:var:`Data.@data.a`. Short-hand ref: :c:var:`Data.a`. Aliasing Declarations -~~~~~~~~~~~~~~~~~~~~~ +--------------------- .. c:namespace-push:: @alias @@ -251,7 +252,7 @@ The following directive can be used for this purpose. Inline Expressions and Types -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +---------------------------- .. rst:role:: c:expr c:texpr @@ -287,7 +288,7 @@ Inline Expressions and Types Namespacing -~~~~~~~~~~~ +----------- .. versionadded:: 3.1 @@ -352,6 +353,6 @@ The ``c:namespace-pop`` directive undoes the most recent .. c:namespace-push:: A.B Configuration Variables -~~~~~~~~~~~~~~~~~~~~~~~ +----------------------- See :ref:`c-config`. diff --git a/doc/usage/domains/cpp.rst b/doc/usage/domains/cpp.rst index 5cf2d0cd5..50afd7c34 100644 --- a/doc/usage/domains/cpp.rst +++ b/doc/usage/domains/cpp.rst @@ -1,12 +1,13 @@ .. highlight:: rst +============== The C++ Domain --------------- +============== The C++ domain (name **cpp**) supports documenting C++ projects. Directives for Declaring Entities -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------------------------- The following directives are available. All declarations can start with a visibility statement (``public``, ``private`` or ``protected``). @@ -247,7 +248,7 @@ visibility statement (``public``, ``private`` or ``protected``). Options -^^^^^^^ +~~~~~~~ Some directives support options: @@ -258,7 +259,7 @@ Some directives support options: .. versionadded:: 1.6 Anonymous Entities -~~~~~~~~~~~~~~~~~~ +------------------ C++ supports anonymous namespaces, classes, enums, and unions. For the sake of documentation they must be given some name that starts with @@ -304,7 +305,7 @@ Explicit ref: :cpp:var:`Data::@data::a`. Short-hand ref: :cpp:var:`Data::a`. Aliasing Declarations -~~~~~~~~~~~~~~~~~~~~~ +--------------------- Sometimes it may be helpful list declarations elsewhere than their main documentation, e.g., when creating a synopsis of a class interface. @@ -359,7 +360,7 @@ The following directive can be used for this purpose. Constrained Templates -~~~~~~~~~~~~~~~~~~~~~ +--------------------- .. warning:: The support for concepts is experimental. It is based on the current draft standard and the Concepts Technical Specification. @@ -368,7 +369,7 @@ Constrained Templates .. note:: Sphinx does not currently support ``requires`` clauses. Placeholders -^^^^^^^^^^^^ +~~~~~~~~~~~~ Declarations may use the name of a concept to introduce constrained template parameters, or the keyword ``auto`` to introduce unconstrained template @@ -384,7 +385,7 @@ parameters:: Iterator concept. Template Introductions -^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~ Simple constrained function or class templates can be declared with a `template introduction` instead of a template parameter list:: @@ -419,7 +420,7 @@ compatibility. E.g., ``Iterator{A, B, C}`` will be accepted as an introduction even though it would not be valid C++. Inline Expressions and Types -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +---------------------------- .. rst:role:: cpp:expr cpp:texpr @@ -458,7 +459,7 @@ Inline Expressions and Types The :rst:role:`cpp:texpr` role. Namespacing -~~~~~~~~~~~ +----------- Declarations in the C++ domain are as default placed in global scope. The current scope can be changed using three namespace directives. They manage a @@ -544,7 +545,7 @@ The ``cpp:namespace-pop`` directive undoes the most recent .. versionadded:: 1.4 Info field lists -~~~~~~~~~~~~~~~~~ +---------------- All the C++ directives for declaring entities support the following info fields (see also :ref:`info-field-lists`): @@ -566,7 +567,7 @@ following fields: .. _cpp-roles: Cross-referencing -~~~~~~~~~~~~~~~~~ +----------------- These roles link to the given declaration types: @@ -602,14 +603,14 @@ These roles link to the given declaration types: angle brackets do not need escaping. Declarations without template parameters and template arguments -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ For linking to non-templated declarations the name must be a nested name, e.g., ``f`` or ``MyClass::f``. Overloaded (member) functions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When a (member) function is referenced using just its name, the reference will point to an arbitrary matching overload. @@ -643,7 +644,7 @@ does not influence specific overload references. Templated declarations -^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~ Assume the following declarations. @@ -680,7 +681,7 @@ This means the following references work as well: (:cpp:class:`template\ Wrapper::Outer::Inner`) (Full) Template Specialisations -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Assume the following declarations. @@ -709,7 +710,7 @@ shorthand the empty template parameter list can be omitted, e.g., (:cpp:class:`Outer\::Inner\`). Partial Template Specialisations -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Assume the following declaration. @@ -722,6 +723,6 @@ parameter lists, e.g., ``template\ Outer\`` succeed if the template parameter identifiers are equal strings. Configuration Variables -~~~~~~~~~~~~~~~~~~~~~~~ +----------------------- See :ref:`cpp-config`. diff --git a/doc/usage/domains/javascript.rst b/doc/usage/domains/javascript.rst index d3c1e7ca6..7e186ae6c 100644 --- a/doc/usage/domains/javascript.rst +++ b/doc/usage/domains/javascript.rst @@ -1,7 +1,8 @@ .. highlight:: rst +===================== The JavaScript Domain ---------------------- +===================== The JavaScript domain (name **js**) provides the following directives: diff --git a/doc/usage/domains/mathematics.rst b/doc/usage/domains/mathematics.rst index bf0e9e69a..6d70ae6cc 100644 --- a/doc/usage/domains/mathematics.rst +++ b/doc/usage/domains/mathematics.rst @@ -1,7 +1,8 @@ .. highlight:: rst +====================== The Mathematics Domain ----------------------- +====================== The math domain (name **math**) provides the following roles: diff --git a/doc/usage/domains/python.rst b/doc/usage/domains/python.rst index ee8a90039..209677800 100644 --- a/doc/usage/domains/python.rst +++ b/doc/usage/domains/python.rst @@ -1,7 +1,8 @@ .. highlight:: rst +================= The Python Domain ------------------ +================= The Python domain (name **py**) provides the following directives for module declarations: @@ -468,7 +469,7 @@ The following directives are provided for module and class contents: .. _signatures: Python Signatures -~~~~~~~~~~~~~~~~~ +----------------- Signatures of functions, methods and class constructors can be given like they would be written in Python. @@ -512,7 +513,7 @@ See :pep:`695` and :pep:`696` for details and the full specification. .. _info-field-lists: Info field lists -~~~~~~~~~~~~~~~~ +---------------- .. versionadded:: 0.4 .. versionchanged:: 3.0 @@ -603,7 +604,7 @@ word "or":: .. _python-roles: Cross-referencing Python objects -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +-------------------------------- The following roles refer to objects in modules and are possibly hyperlinked if a matching identifier is found: diff --git a/doc/usage/domains/restructuredtext.rst b/doc/usage/domains/restructuredtext.rst index f2465e018..0c3281fab 100644 --- a/doc/usage/domains/restructuredtext.rst +++ b/doc/usage/domains/restructuredtext.rst @@ -1,7 +1,8 @@ .. highlight:: rst +=========================== The reStructuredText Domain ---------------------------- +=========================== The reStructuredText domain (name **rst**) provides the following directives: diff --git a/doc/usage/domains/standard.rst b/doc/usage/domains/standard.rst index 216ba6262..1923a6dc2 100644 --- a/doc/usage/domains/standard.rst +++ b/doc/usage/domains/standard.rst @@ -1,7 +1,8 @@ .. highlight:: rst +=================== The Standard Domain -------------------- +=================== The so-called "standard" domain collects all markup that doesn't warrant a domain of its own. Its directives and roles are not prefixed with a domain