diff options
author | Takeshi KOMIYA <i.tkomiya@gmail.com> | 2021-11-21 20:34:07 +0300 |
---|---|---|
committer | GitHub <noreply@github.com> | 2021-11-21 20:34:07 +0300 |
commit | a63fb559075d59df78281b11b10af01fadd1ecb3 (patch) | |
tree | 6025ec71eb22fae9cbbb6673427596b1ebc2684e /doc | |
parent | 647314133d7a9a524087eddd9c21203010cb4aa7 (diff) | |
parent | 79f6d404135389b0e7a74675daf480dc890ae6a2 (diff) |
Merge pull request #9850 from astrojuanlu/new-tutorial-describing-code-other
Add brief section on documenting other languages to tutorial
Diffstat (limited to 'doc')
-rw-r--r-- | doc/tutorial/describing-code.rst | 50 |
1 files changed, 47 insertions, 3 deletions
diff --git a/doc/tutorial/describing-code.rst b/doc/tutorial/describing-code.rst index bfeca0455..0b88f5bd9 100644 --- a/doc/tutorial/describing-code.rst +++ b/doc/tutorial/describing-code.rst @@ -14,8 +14,11 @@ section apply for the other domains as well. .. _tutorial-describing-objects: +Python +------ + Documenting Python objects --------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~ Sphinx offers several roles and directives to document Python objects, all grouped together in :ref:`the Python domain <python-domain>`. For example, @@ -68,7 +71,7 @@ Notice several things: ``.. function::`` directly. Cross-referencing Python objects --------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ By default, most of these directives generate entities that can be cross-referenced from any part of the documentation by using @@ -123,7 +126,7 @@ And finally, this is how the result would look: Beautiful, isn't it? Including doctests in your documentation ----------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Since you are now describing code from a Python library, it will become useful to keep both the documentation and the code as synchronized as possible. @@ -229,3 +232,44 @@ And finally, ``make test`` reports success! For big projects though, this manual approach can become a bit tedious. In the next section, you will see :doc:`how to automate the process </tutorial/automatic-doc-generation>`. + +Other languages (C, C++, others) +-------------------------------- + +Documenting and cross-referencing objects +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sphinx also supports documenting and cross-referencing objects written in +other programming languages. There are four additional built-in domains: +C, C++, JavaScript, and reStructuredText. Third-party extensions may +define domains for more languages, such as + +- `Fortran <https://sphinx-fortran.readthedocs.io>`_, +- `Julia <http://bastikr.github.io/sphinx-julia>`_, or +- `PHP <https://github.com/markstory/sphinxcontrib-phpdomain>`_. + +For example, to document a C++ type definition, you would use the built-in +:rst:dir:`cpp:type` directive, as follows: + +.. code-block:: rst + + .. cpp:type:: std::vector<int> CustomList + + A typedef-like declaration of a type. + +Which would give the following result: + +.. cpp:type:: std::vector<int> CustomList + + A typedef-like declaration of a type. + +All such directives then generate references that can be +cross-referenced by using the corresponding role. For example, to reference +the previous type definition, you can use the :rst:role:`cpp:type` role +as follows: + +.. code-block:: rst + + Cross reference to :cpp:type:`CustomList`. + +Which would produce a hyperlink to the previous definition: :cpp:type:`CustomList`. |