diff options
Diffstat (limited to 'doc/source/dev/howto-docs.rst')
| -rw-r--r-- | doc/source/dev/howto-docs.rst | 219 |
1 files changed, 216 insertions, 3 deletions
diff --git a/doc/source/dev/howto-docs.rst b/doc/source/dev/howto-docs.rst index 3156d3452..93fec509c 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 separately in `_add_newdocs.py <https://github.com/numpy/numpy/blob/main/numpy/core/_add_newdocs.py>`__ ********************** @@ -72,7 +72,7 @@ Your frustrations using our documents are our best guide to what needs fixing. If you write a missing doc you join the front line of open source, but it's a meaningful contribution just to let us know what's missing. If you want to compose a doc, run your thoughts by the `mailing list -<https://mail.python.org/mailman/listinfo/numpy-discussion>`__ for futher +<https://mail.python.org/mailman/listinfo/numpy-discussion>`__ for further ideas and feedback. If you want to alert us to a gap, `open an issue <https://github.com/numpy/numpy/issues>`__. See `this issue <https://github.com/numpy/numpy/issues/15760>`__ for an example. @@ -215,6 +215,219 @@ Note that for documentation within NumPy, it is not necessary to do Please use the ``numpydoc`` :ref:`formatting standard <numpydoc:format>` as shown in their :ref:`example <numpydoc:example>`. +.. _doc_c_code: + +Documenting C/C++ Code +====================== + +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**: + +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:: + Please see `"Documenting the code" <https://www.doxygen.nl/manual/docblocks.html>`__. + +**This is what Javadoc style looks like**: + +.. literalinclude:: examples/doxy_func.h + +**And here is how it is rendered**: + +.. doxygenfunction:: doxy_javadoc_example + +**For line comment, you can use a triple forward slash. For example**: + +.. literalinclude:: examples/doxy_class.hpp + +**And here is how it is rendered**: + +.. doxygenclass:: DoxyLimbo + +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 <https://www.doxygen.nl/manual/config.html#cfg_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 <parameter-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. + +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 +------------------ + +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 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 <https://www.doxygen.nl/manual/config.html>`__, +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 \ + @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 +converting the documents generated by Doxygen_ into reST files. + +.. note:: + For more information, please check out "`Directives & Config Variables <https://breathe.readthedocs.io/en/latest/directives.html>`__" + +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:: <function name> + :outline: + :no-link: + +Checkout the `example <https://breathe.readthedocs.io/en/latest/function.html#function-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:: <class name> + :members: [...] + :protected-members: + :private-members: + :undoc-members: + :membergroups: ... + :members-only: + :outline: + :no-link: + +Checkout the `doxygenclass documentation <https://breathe.readthedocs.io/en/latest/class.html#class-example>_` +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:: <namespace> + :content-only: + :outline: + :members: + :protected-members: + :private-members: + :undoc-members: + :no-link: + +Checkout the `doxygennamespace documentation <https://breathe.readthedocs.io/en/latest/namespace.html#namespace-example>`__ +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 <https://www.doxygen.nl/manual/grouping.html>`__. + +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:: <group name> + :content-only: + :outline: + :members: + :protected-members: + :private-members: + :undoc-members: + :no-link: + :inner: + +Checkout the `doxygengroup documentation <https://breathe.readthedocs.io/en/latest/group.html#group-example>`__ +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 |