From 34c165e497e80ea563ac0619c602ad6ab8bd4742 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Mon, 15 Nov 2021 12:46:03 +0100 Subject: [PATCH 1/4] Add clarification on other languages --- doc/tutorial/describing-code.rst | 49 ++++++++++++++++++++++++++++++-- 1 file changed, 46 insertions(+), 3 deletions(-) diff --git a/doc/tutorial/describing-code.rst b/doc/tutorial/describing-code.rst index bfeca0455bc..f080b095c71 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 `. 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,43 @@ 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 `. + +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 extra built-in domains: +C, C++, JavaScript, and reStructuredText, and third party extensions may +define domains for more languages, such as +`.NET `, +`Fortran `_, +or `Julia `_. + +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 CustomList + + A typedef-like declaration of a type. + +Which would give the following result: + +.. cpp:type:: std::vector CustomList + + A typedef-like declaration of a type. + +All such directives then generate 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`. From d7d82a88ad2cf84b76b8e3256c9dfd59369b6de0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Mon, 15 Nov 2021 14:29:17 +0100 Subject: [PATCH 2/4] Typo Co-authored-by: Manuel Kaufmann --- doc/tutorial/describing-code.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/tutorial/describing-code.rst b/doc/tutorial/describing-code.rst index f080b095c71..88e1f870214 100644 --- a/doc/tutorial/describing-code.rst +++ b/doc/tutorial/describing-code.rst @@ -262,7 +262,7 @@ Which would give the following result: A typedef-like declaration of a type. -All such directives then generate generate references that can be +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: From eceb6b8f4b26e20246662ce916dc4143376b664d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Mon, 15 Nov 2021 14:30:07 +0100 Subject: [PATCH 3/4] Remove reference to unmaintained extension --- doc/tutorial/describing-code.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/tutorial/describing-code.rst b/doc/tutorial/describing-code.rst index 88e1f870214..bf8ab1c1f64 100644 --- a/doc/tutorial/describing-code.rst +++ b/doc/tutorial/describing-code.rst @@ -243,8 +243,7 @@ Sphinx also supports documenting and cross-referencing objects written in other programming languages. There are four extra built-in domains: C, C++, JavaScript, and reStructuredText, and third party extensions may define domains for more languages, such as -`.NET `, -`Fortran `_, +`Fortran `_ or `Julia `_. For example, to document a C++ type definition, you would use the built-in From 79f6d404135389b0e7a74675daf480dc890ae6a2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Thu, 18 Nov 2021 23:04:30 +0100 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Jakob Lykke Andersen --- doc/tutorial/describing-code.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/doc/tutorial/describing-code.rst b/doc/tutorial/describing-code.rst index bf8ab1c1f64..0b88f5bd9df 100644 --- a/doc/tutorial/describing-code.rst +++ b/doc/tutorial/describing-code.rst @@ -240,11 +240,13 @@ Documenting and cross-referencing objects ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Sphinx also supports documenting and cross-referencing objects written in -other programming languages. There are four extra built-in domains: -C, C++, JavaScript, and reStructuredText, and third party extensions may +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 `_ -or `Julia `_. + +- `Fortran `_, +- `Julia `_, or +- `PHP `_. For example, to document a C++ type definition, you would use the built-in :rst:dir:`cpp:type` directive, as follows: