Merge branch 'main' of https://github.com/sayantikabanik/numpy

6 files changed, 280 insertions, 7 deletions

diff --git a/doc/source/dev/examples/.doxyfile b/doc/source/dev/examples/.doxyfile
new file mode 100644
index 000000000..966c1b636
--- /dev/null
+++ b/doc/source/dev/examples/.doxyfile
@@ -0,0 +1,2 @@
+INPUT += @CUR_DIR
+INCLUDE_PATH += @CUR_DIR
diff --git a/doc/source/dev/examples/doxy_class.hpp b/doc/source/dev/examples/doxy_class.hpp
new file mode 100644
index 000000000..ceba63487
--- /dev/null
+++ b/doc/source/dev/examples/doxy_class.hpp
@@ -0,0 +1,21 @@
+/**
+ *  Template to represent limbo numbers.
+ *
+ *  Specializations for integer types that are part of nowhere.
+ *  It doesn't support with any real types.
+ *
+ *  @param Tp Type of the integer. Required to be an integer type.
+ *  @param N  Number of elements.
+*/
+template<typename Tp, std::size_t N>
+class DoxyLimbo {
+ public:
+    /// Default constructor. Initialize nothing.
+    DoxyLimbo();
+    /// Set Default behavior for copy the limbo.
+    DoxyLimbo(const DoxyLimbo<Tp, N> &l);
+    /// Returns the raw data for the limbo.
+    const Tp *data();
+ protected:
+    Tp p_data[N]; ///< Example for inline comment.
+};
diff --git a/doc/source/dev/examples/doxy_func.h b/doc/source/dev/examples/doxy_func.h
new file mode 100644
index 000000000..792a9d1b7
--- /dev/null
+++ b/doc/source/dev/examples/doxy_func.h
@@ -0,0 +1,11 @@
+/**
+ * This a simple brief.
+ *
+ * And the details goes here.
+ * Multi lines are welcome.
+ *
+ * @param  num  leave a comment for parameter num.
+ * @param  str  leave a comment for the second parameter.
+ * @return      leave a comment for the returned value.
+ */
+int doxy_javadoc_example(int num, const char *str);
diff --git a/doc/source/dev/examples/doxy_rst.h b/doc/source/dev/examples/doxy_rst.h
new file mode 100644
index 000000000..6ab4a0775
--- /dev/null
+++ b/doc/source/dev/examples/doxy_rst.h
@@ -0,0 +1,15 @@
+/**
+ * A comment block contains reST markup.
+ * @rst
+ * .. note::
+ *
+ *   Thanks to Breathe_, we were able to bring it to Doxygen_
+ *
+ * Some code example::
+ *
+ *   int example(int x) {
+ *       return x * 2;
+ *   }
+ * @endrst
+ */
+void doxy_reST_example(void);
diff --git a/doc/source/dev/howto-docs.rst b/doc/source/dev/howto-docs.rst
index 3156d3452..cc17a1feb 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
 <https://github.com/numpy/numpy/blob/main/numpy/core/_add_newdocs.py>`__
 
 **********************
@@ -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
diff --git a/doc/source/dev/howto_build_docs.rst b/doc/source/dev/howto_build_docs.rst
index 884cf7935..b175926da 100644
--- a/doc/source/dev/howto_build_docs.rst
+++ b/doc/source/dev/howto_build_docs.rst
@@ -58,18 +58,28 @@ new virtual environment is recommended.
 Dependencies
 ^^^^^^^^^^^^
 
-All of the necessary dependencies for building the NumPy docs can be installed
-with::
+All of the necessary dependencies for building the NumPy docs except for
+Doxygen_ can be installed with::
 
     pip install -r doc_requirements.txt
 
-We currently use Sphinx_ for generating the API and reference
-documentation for NumPy. In addition, building the documentation requires
-the Sphinx extension `plot_directive`, which is shipped with
+We currently use Sphinx_ along with Doxygen_ for generating the API and
+reference documentation for NumPy. In addition, building the documentation
+requires the Sphinx extension `plot_directive`, which is shipped with
 :doc:`Matplotlib <matplotlib:index>`. We also use numpydoc_ to render docstrings in
 the generated API documentation. :doc:`SciPy <scipy:index>`
 is installed since some parts of the documentation require SciPy functions.
 
+For installing Doxygen_, please check the official
+`download <https://www.doxygen.nl/download.html#srcbin>`_ and
+`installation <https://www.doxygen.nl/manual/install.html>`_ pages, or if you
+are using Linux then you can install it through your distribution package manager.
+
+.. note::
+
+   Try to install a newer version of Doxygen_ > 1.8.10 otherwise you may get some
+   warnings during the build.
+
 Submodules
 ^^^^^^^^^^
 
@@ -80,6 +90,7 @@ additional parts required for building the documentation::
 
 .. _Sphinx: http://www.sphinx-doc.org/
 .. _numpydoc: https://numpydoc.readthedocs.io/en/latest/index.html
+.. _Doxygen: https://www.doxygen.nl/index.html
 
 Instructions
 ------------