From a7d3a77121f0127b9402a78b1138d00dd4f973fc Mon Sep 17 00:00:00 2001 From: Sayed Adel Date: Tue, 13 Jul 2021 23:37:25 +0200 Subject: DOC: Add support for documenting C/C++ via Doxygen & Breathe --- doc/source/dev/howto-docs.rst | 219 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 217 insertions(+), 2 deletions(-) (limited to 'doc/source/dev/howto-docs.rst') diff --git a/doc/source/dev/howto-docs.rst b/doc/source/dev/howto-docs.rst index 3156d3452..501de9e1c 100644 --- a/doc/source/dev/howto-docs.rst +++ b/doc/source/dev/howto-docs.rst @@ -59,8 +59,8 @@ Obvious **wording** mistakes (like leaving out a "not") fall into the typo category, but other rewordings -- even for grammar -- require a judgment call, which raises the bar. Test the waters by first presenting the fix as an issue. -Some functions/objects like numpy.ndarray.transpose, numpy.array etc. defined in -C-extension modules have their docstrings defined seperately in `_add_newdocs.py +Some functions/objects like numpy.ndarray.transpose, numpy.array etc. defined in +C-extension modules have their docstrings defined seperately in `_add_newdocs.py `__ ********************** @@ -215,6 +215,221 @@ Note that for documentation within NumPy, it is not necessary to do Please use the ``numpydoc`` :ref:`formatting standard ` as shown in their :ref:`example `. +.. _doc_c_cpp: + +Documenting C/C++ Code +====================== + +Recently, NumPy headed out to use Doxygen_ along with Sphinx due to the urgent need +to generate C/C++ API reference documentation from comment blocks, especially with +the most recent expansion in the use of SIMD, and also due to the future reliance on C++. +Thanks to Breathe_, we were able to bind both worlds together at the lowest cost. + +**It takes three steps to complete the documentation process**: + +1. Writing the comment blocks +----------------------------- + +Although there is still no commenting style set to follow, the Javadoc +is more preferable than the others due to the similarities with the current +existing non-indexed comment blocks. + +.. note:: + If you have never used Doxygen_ before, then maybe you need to take a quick + look at `"Documenting the code" `__. + +This is how Javadoc style looks like:: + + /** + * Your brief is here. + */ + void function(void); + +For line comment, insert a triple forward slash:: + + /// Your brief is here. + void function(void); + +And for structured data members, just insert triple forward slash and less-than sign:: + + /// Data type brief. + typedef struct { + int member_1; ///< Member 1 description. + int member_2; ///< Member 2 description. + } data_type; + + +Common Doxygen Tags: +++++++++++++++++++++ + +.. note:: + For more tags/commands, please take a look at https://www.doxygen.nl/manual/commands.html + +``@brief`` + +Starts a paragraph that serves as a brief description. By default the first sentence +of the documentation block is automatically treated as a brief description, since +option `JAVADOC_AUTOBRIEF `__ +is enabled within doxygen configurations. + +``@details`` + +Just like ``@brief`` starts a brief description, ``@details`` starts the detailed description. +You can also start a new paragraph (blank line) then the ``@details`` command is not needed. + +``@param`` + +Starts a parameter description for a function parameter with name , +followed by a description of the parameter. The existence of the parameter is checked +and a warning is given if the documentation of this (or any other) parameter is missing +or not present in the function declaration or definition. + +``@return`` + +Starts a return value description for a function. +Multiple adjacent ``@return`` commands will be joined into a single paragraph. +The ``@return`` description ends when a blank line or some other sectioning command is encountered. + +``@code/@endcode`` + +Starts/Ends a block of code. A code block is treated differently from ordinary text. +It is interpreted as source code. + +``@rst/@endrst`` + +Starts/Ends a block of reST markup. Take a look at the following example: + +.. literalinclude:: examples/doxy_rst.h + +.. doxygenfunction:: doxy_reST_example + +2. Feeding Doxygen +------------------ + +Not all headers files are collected automatically. You have to add the desired +C/C++ header paths within the sub-config files of Doxygen. + +Sub-config files have the unique name ``.doxyfile``, which you can usually find near +directories that contain documented headers. You need to create a new config file if +there's no one located in a path close(2-depth) to the headers you want to add. + +Sub-config files can accept any of Doxygen_ `configuration options `__, +but you should be aware of not overriding or re-initializing any configuration option, +you must only count on the concatenation operator "+=". For example:: + + # to specfiy certain headers + INPUT += @CUR_DIR/header1.h \ + @CUR_DIR/header2.h + # to add all headers in certain path + INPUT += @CUR_DIR/to/headers + # to define certain macros + PREDEFINED += C_MACRO(X)=X + # to enable certain branches + PREDEFINED += NPY_HAVE_FEATURE \ + NPY_HAVE_FEATURE2 + +.. note:: + @CUR_DIR is a template constant returns the current + dir path of the sub-config file. + +3. Inclusion directives +----------------------- + +Breathe_ provides a wide range of custom directives to allow +including the generated documents by Doxygen_ into reST files. + +.. note:: + For more information, please check out "`Directives & Config Variables `__" + +Common directives: +++++++++++++++++++ + +``doxygenfunction`` + +This directive generates the appropriate output for a single function. +The function name is required to be unique in the project. + +.. code:: + + .. doxygenfunction:: + :outline: + :no-link: + +Checkout the `example `__ +to see it in action. + + +``doxygenclass`` + +This directive generates the appropriate output for a single class. +It takes the standard project, path, outline and no-link options and +additionally the members, protected-members, private-members, undoc-members, +membergroups and members-only options: + +.. code:: + + .. doxygenclass:: + :members: [...] + :protected-members: + :private-members: + :undoc-members: + :membergroups: ... + :members-only: + :outline: + :no-link: + +Checkout the `doxygenclass documentation _` +for more details and to see it in action. + +``doxygennamespace`` + +This directive generates the appropriate output for the contents of a namespace. +It takes the standard project, path, outline and no-link options and additionally the content-only, +members, protected-members, private-members and undoc-members options. +To reference a nested namespace, the full namespaced path must be provided, +e.g. foo::bar for the bar namespace inside the foo namespace. + +.. code:: + + .. doxygennamespace:: + :content-only: + :outline: + :members: + :protected-members: + :private-members: + :undoc-members: + :no-link: + +Checkout the `doxygennamespace documentation `__ +for more details and to see it in action. + +``doxygengroup`` + +This directive generates the appropriate output for the contents of a doxygen group. +A doxygen group can be declared with specific doxygen markup in the source comments +as covered in the doxygen `grouping documentation `__. + +It takes the standard project, path, outline and no-link options and additionally the +content-only, members, protected-members, private-members and undoc-members options. + +.. code:: + + .. doxygengroup:: + :content-only: + :outline: + :members: + :protected-members: + :private-members: + :undoc-members: + :no-link: + :inner: + +Checkout the `doxygengroup documentation `__ +for more details and to see it in action. + +.. _`Doxygen`: https://www.doxygen.nl/index.html +.. _`Breathe`: https://breathe.readthedocs.io/en/latest/ + ********************* Documentation reading -- cgit v1.2.1 From 21c69689bafc4ed2d3ef4038bda81d32c05dc6d7 Mon Sep 17 00:00:00 2001 From: Sayed Adel Date: Mon, 30 Aug 2021 21:08:45 +0200 Subject: DOC: Apply suggestions from Matti review Co-authored-by: Matti Picus --- doc/source/dev/howto-docs.rst | 31 +++++++++++++++++-------------- 1 file changed, 17 insertions(+), 14 deletions(-) (limited to 'doc/source/dev/howto-docs.rst') diff --git a/doc/source/dev/howto-docs.rst b/doc/source/dev/howto-docs.rst index 501de9e1c..f8513aced 100644 --- a/doc/source/dev/howto-docs.rst +++ b/doc/source/dev/howto-docs.rst @@ -215,15 +215,13 @@ Note that for documentation within NumPy, it is not necessary to do Please use the ``numpydoc`` :ref:`formatting standard ` as shown in their :ref:`example `. -.. _doc_c_cpp: +.. _doc_c_code: Documenting C/C++ Code ====================== -Recently, NumPy headed out to use Doxygen_ along with Sphinx due to the urgent need -to generate C/C++ API reference documentation from comment blocks, especially with -the most recent expansion in the use of SIMD, and also due to the future reliance on C++. -Thanks to Breathe_, we were able to bind both worlds together at the lowest cost. +NumPy uses Doxygen_ to parse specially-formatted C/C++ comment blocks. This generates +XML files, which are converted by Breathe_ into RST, which is used by Sphinx. **It takes three steps to complete the documentation process**: @@ -235,10 +233,9 @@ is more preferable than the others due to the similarities with the current existing non-indexed comment blocks. .. note:: - If you have never used Doxygen_ before, then maybe you need to take a quick - look at `"Documenting the code" `__. + Please see `"Documenting the code" `__. -This is how Javadoc style looks like:: +This is what Javadoc style looks like:: /** * Your brief is here. @@ -252,7 +249,7 @@ For line comment, insert a triple forward slash:: And for structured data members, just insert triple forward slash and less-than sign:: - /// Data type brief. + /// Data type brief description typedef struct { int member_1; ///< Member 1 description. int member_2; ///< Member 2 description. @@ -297,10 +294,16 @@ It is interpreted as source code. ``@rst/@endrst`` -Starts/Ends a block of reST markup. Take a look at the following example: +Starts/Ends a block of reST markup. + +Example +~~~~~~~ +Take a look at the following example: .. literalinclude:: examples/doxy_rst.h +And here is how it is rendered: + .. doxygenfunction:: doxy_reST_example 2. Feeding Doxygen @@ -311,11 +314,11 @@ C/C++ header paths within the sub-config files of Doxygen. Sub-config files have the unique name ``.doxyfile``, which you can usually find near directories that contain documented headers. You need to create a new config file if -there's no one located in a path close(2-depth) to the headers you want to add. +there's not one located in a path close(2-depth) to the headers you want to add. Sub-config files can accept any of Doxygen_ `configuration options `__, -but you should be aware of not overriding or re-initializing any configuration option, -you must only count on the concatenation operator "+=". For example:: +but do not override or re-initialize any configuration option, +rather only use the concatenation operator "+=". For example:: # to specfiy certain headers INPUT += @CUR_DIR/header1.h \ @@ -336,7 +339,7 @@ you must only count on the concatenation operator "+=". For example:: ----------------------- Breathe_ provides a wide range of custom directives to allow -including the generated documents by Doxygen_ into reST files. +converting the documents generated by Doxygen_ into reST files. .. note:: For more information, please check out "`Directives & Config Variables `__" -- cgit v1.2.1 From 241527a3cb287c1033b3a71a7cc14c40f22ec607 Mon Sep 17 00:00:00 2001 From: Sayed Adel Date: Tue, 31 Aug 2021 20:16:05 +0200 Subject: DOC: Improve Doxygen Javadoc style examples --- doc/source/dev/howto-docs.rst | 27 +++++++++++---------------- 1 file changed, 11 insertions(+), 16 deletions(-) (limited to 'doc/source/dev/howto-docs.rst') diff --git a/doc/source/dev/howto-docs.rst b/doc/source/dev/howto-docs.rst index f8513aced..cc17a1feb 100644 --- a/doc/source/dev/howto-docs.rst +++ b/doc/source/dev/howto-docs.rst @@ -235,26 +235,21 @@ existing non-indexed comment blocks. .. note:: Please see `"Documenting the code" `__. -This is what Javadoc style looks like:: +**This is what Javadoc style looks like**: - /** - * Your brief is here. - */ - void function(void); +.. literalinclude:: examples/doxy_func.h -For line comment, insert a triple forward slash:: +**And here is how it is rendered**: - /// Your brief is here. - void function(void); +.. doxygenfunction:: doxy_javadoc_example -And for structured data members, just insert triple forward slash and less-than sign:: +**For line comment, you can use a triple forward slash. For example**: - /// Data type brief description - typedef struct { - int member_1; ///< Member 1 description. - int member_2; ///< Member 2 description. - } data_type; +.. literalinclude:: examples/doxy_class.hpp +**And here is how it is rendered**: + +.. doxygenclass:: DoxyLimbo Common Doxygen Tags: ++++++++++++++++++++ @@ -298,11 +293,11 @@ Starts/Ends a block of reST markup. Example ~~~~~~~ -Take a look at the following example: +**Take a look at the following example**: .. literalinclude:: examples/doxy_rst.h -And here is how it is rendered: +**And here is how it is rendered**: .. doxygenfunction:: doxy_reST_example -- cgit v1.2.1