Merge pull request #18884 from seiko2plus/breathe_doxygen

DOC: Add support for documenting C/C++ via Doxygen & Breathe

15 files changed, 719 insertions, 13 deletions

diff --git a/.circleci/config.yml b/.circleci/config.yml
index fdb85be98..c343e9168 100644
--- a/.circleci/config.yml
+++ b/.circleci/config.yml
@@ -8,7 +8,11 @@ jobs:
     docker:
       # CircleCI maintains a library of pre-built images
       # documented at https://circleci.com/docs/2.0/circleci-images/
-      - image: cimg/python:3.8
+      # circleci/python3.8 images come with old versions of Doxygen(1.6.x),
+      # therefore a new base image chose instead to guarantee to
+      # have a newer version >= 1.8.10 to avoid warnings
+      # that related to the default behaviors or non-exist config options
+      - image: cimg/base:2021.05
 
     working_directory: ~/repo
 
@@ -23,7 +27,8 @@ jobs:
           name: create virtual environment, install dependencies
           command: |
             sudo apt-get update
-            sudo apt-get install -y graphviz texlive-fonts-recommended texlive-latex-recommended texlive-latex-extra latexmk texlive-xetex
+            sudo apt-get install -y python3.8 python3.8-dev python3-venv graphviz texlive-fonts-recommended texlive-latex-recommended \
+              texlive-latex-extra latexmk texlive-xetex doxygen
             python3.8 -m venv venv
             . venv/bin/activate
 
@@ -58,7 +63,7 @@ jobs:
             . venv/bin/activate
             cd doc
             # Don't use -q, show warning summary"
-            SPHINXOPTS="-n" make -e html || echo "ignoring errors for now, see gh-13114"
+            SPHINXOPTS="-j4 -n" make -e html || echo "ignoring errors for now, see gh-13114"
 
       - run:
           name: build devdocs
@@ -67,14 +72,14 @@ jobs:
             . venv/bin/activate
             cd doc
             make clean
-            SPHINXOPTS=-q make -e html
+            SPHINXOPTS="-j4 -q" make -e html
 
       - run:
           name: build neps
           command: |
             . venv/bin/activate
             cd doc/neps
-            SPHINXOPTS=-q make -e html
+            SPHINXOPTS="-j4 -q" make -e html
 
       - store_artifacts:
           path: doc/build/html/
diff --git a/doc/Makefile b/doc/Makefile
index 68d496389..16fc3229d 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -14,6 +14,7 @@ PYTHON = python$(PYVER)
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= LANG=C sphinx-build
 PAPER         ?=
+DOXYGEN       ?= doxygen
 # For merging a documentation archive into a git checkout of numpy/doc
 # Turn a tag like v1.18.0 into 1.18
 # Use sed -n -e 's/patttern/match/p' to return a blank value if no match
@@ -77,7 +78,7 @@ INSTALL_DIR = $(CURDIR)/build/inst-dist
 INSTALL_PPH = $(INSTALL_DIR)/lib/python$(PYVER)/site-packages:$(INSTALL_DIR)/local/lib/python$(PYVER)/site-packages:$(INSTALL_DIR)/lib/python$(PYVER)/dist-packages:$(INSTALL_DIR)/local/lib/python$(PYVER)/dist-packages
 UPLOAD_DIR=/srv/docs_scipy_org/doc/numpy-$(RELEASE)
 
-DIST_VARS=SPHINXBUILD="LANG=C PYTHONPATH=$(INSTALL_PPH) python$(PYVER) `which sphinx-build`" PYTHON="PYTHONPATH=$(INSTALL_PPH) python$(PYVER)" 
+DIST_VARS=SPHINXBUILD="LANG=C PYTHONPATH=$(INSTALL_PPH) python$(PYVER) `which sphinx-build`" PYTHON="PYTHONPATH=$(INSTALL_PPH) python$(PYVER)"
 
 NUMPYVER:=$(shell $(PYTHON) -c "import numpy; print(numpy.version.git_revision[:10])" 2>/dev/null)
 GITVER ?= $(shell cd ..; $(PYTHON) -c "import versioneer as v; print(v.get_versions()['full-revisionid'][:10])")
@@ -176,6 +177,12 @@ build/generate-stamp: $(wildcard source/reference/*.rst)
 html: version-check html-build
 html-build: generate
 	mkdir -p build/html build/doctrees
+	$(PYTHON) preprocess.py
+ifeq (, $(shell which $(DOXYGEN)))
+	@echo "Unable to find 'Doxygen:$(DOXYGEN)', skip generating C/C++ API from comment blocks."
+else
+	$(DOXYGEN) build/doxygen/Doxyfile
+endif
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html $(FILES)
 	$(PYTHON) postprocess.py html build/html/*.html
 	@echo
diff --git a/doc/preprocess.py b/doc/preprocess.py
new file mode 100755
index 000000000..e88d9608e
--- /dev/null
+++ b/doc/preprocess.py
@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+import subprocess
+import os
+import sys
+from string import Template
+
+def main():
+    doxy_gen(os.path.abspath(os.path.join('..')))
+
+def doxy_gen(root_path):
+    """
+    Generate Doxygen configration file.
+    """
+    confs = doxy_config(root_path)
+    build_path = os.path.join(root_path, "doc", "build", "doxygen")
+    gen_path = os.path.join(build_path, "Doxyfile")
+    if not os.path.exists(build_path):
+        os.makedirs(build_path)
+    with open(gen_path, 'w') as fd:
+        fd.write("#Please Don't Edit! This config file was autogenerated by ")
+        fd.write(f"doxy_gen({root_path}) in doc/preprocess.py.\n")
+        for c in confs:
+            fd.write(c)
+
+class DoxyTpl(Template):
+    delimiter = '@'
+
+def doxy_config(root_path):
+    """
+    Fetch all Doxygen sub-config files and gather it with the main config file.
+    """
+    confs = []
+    dsrc_path = os.path.join(root_path, "doc", "source")
+    sub = dict(ROOT_DIR=root_path)
+    with open(os.path.join(dsrc_path, "doxyfile"), "r") as fd:
+        conf = DoxyTpl(fd.read())
+        confs.append(conf.substitute(CUR_DIR=dsrc_path, **sub))
+
+    for dpath, _, files in os.walk(root_path):
+        if ".doxyfile" not in files:
+            continue
+        conf_path = os.path.join(dpath, ".doxyfile")
+        with open(conf_path, "r") as fd:
+            conf = DoxyTpl(fd.read())
+            confs.append(conf.substitute(CUR_DIR=dpath, **sub))
+    return confs
+
+
+if __name__ == "__main__":
+    main()
+
diff --git a/doc/release/upcoming_changes/18884.new_feature.rst b/doc/release/upcoming_changes/18884.new_feature.rst
new file mode 100644
index 000000000..41503b00e
--- /dev/null
+++ b/doc/release/upcoming_changes/18884.new_feature.rst
@@ -0,0 +1,7 @@
+Generate C/C++ API reference documentation from comments blocks is now possible
+-------------------------------------------------------------------------------
+This feature depends on Doxygen_ in the generation process and on Breathe_
+to integrate it with Sphinx.
+
+.. _`Doxygen`: https://www.doxygen.nl/index.html
+.. _`Breathe`: https://breathe.readthedocs.io/en/latest/
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 41b5cee25..d08f29e59 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -2,6 +2,7 @@
 import os
 import re
 import sys
+import importlib
 
 # Minimum version, enforced by sphinx
 needs_sphinx = '3.2.0'
@@ -86,6 +87,16 @@ extensions = [
     'sphinx.ext.mathjax',
 ]
 
+skippable_extensions = [
+    ('breathe', 'skip generating C/C++ API from comment blocks.'),
+]
+for ext, warn in skippable_extensions:
+    ext_exist = importlib.util.find_spec(ext) is not None
+    if ext_exist:
+        extensions.append(ext)
+    else:
+        print(f"Unable to find Sphinx extension '{ext}', {warn}.")
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -477,3 +488,11 @@ class NumPyLexer(CLexer):
             inherit,
         ],
     }
+
+
+# -----------------------------------------------------------------------------
+# Breathe & Doxygen
+# -----------------------------------------------------------------------------
+breathe_projects = dict(numpy=os.path.join("..", "build", "doxygen", "xml"))
+breathe_default_project = "numpy"
+breathe_default_members = ("members", "undoc-members", "protected-members")
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
 ------------
diff --git a/doc/source/doxyfile b/doc/source/doxyfile
new file mode 100644
index 000000000..ea45b9578
--- /dev/null
+++ b/doc/source/doxyfile
@@ -0,0 +1,340 @@
+# Doxyfile 1.8.18
+#---------------------------------------------------------------------------
+# Project related configuration options
+#---------------------------------------------------------------------------
+DOXYFILE_ENCODING      = UTF-8
+PROJECT_NAME           = NumPy
+PROJECT_NUMBER         =
+PROJECT_BRIEF          = "NumPy is the fundamental package for scientific computing in Python"
+PROJECT_LOGO           =
+OUTPUT_DIRECTORY       = @ROOT_DIR/doc/build/doxygen
+CREATE_SUBDIRS         = NO
+ALLOW_UNICODE_NAMES    = NO
+OUTPUT_LANGUAGE        = English
+OUTPUT_TEXT_DIRECTION  = None
+BRIEF_MEMBER_DESC      = YES
+REPEAT_BRIEF           = YES
+ABBREVIATE_BRIEF       = "The $name class" \
+                         "The $name widget" \
+                         "The $name file" \
+                         is \
+                         provides \
+                         specifies \
+                         contains \
+                         represents \
+                         a \
+                         an \
+                         the
+ALWAYS_DETAILED_SEC    = NO
+INLINE_INHERITED_MEMB  = NO
+FULL_PATH_NAMES        = YES
+STRIP_FROM_PATH        = @ROOT_DIR
+STRIP_FROM_INC_PATH    =
+SHORT_NAMES            = NO
+JAVADOC_AUTOBRIEF      = YES
+JAVADOC_BANNER         = NO
+QT_AUTOBRIEF           = NO
+MULTILINE_CPP_IS_BRIEF = NO
+INHERIT_DOCS           = YES
+SEPARATE_MEMBER_PAGES  = NO
+TAB_SIZE               = 4
+ALIASES                =
+ALIASES               += "rst=\verbatim embed:rst:leading-asterisk"
+ALIASES               += "endrst=\endverbatim"
+OPTIMIZE_OUTPUT_FOR_C  = NO
+OPTIMIZE_OUTPUT_JAVA   = NO
+OPTIMIZE_FOR_FORTRAN   = NO
+OPTIMIZE_OUTPUT_VHDL   = NO
+OPTIMIZE_OUTPUT_SLICE  = NO
+EXTENSION_MAPPING      =
+MARKDOWN_SUPPORT       = YES
+TOC_INCLUDE_HEADINGS   = 5
+AUTOLINK_SUPPORT       = YES
+BUILTIN_STL_SUPPORT    = NO
+CPP_CLI_SUPPORT        = NO
+SIP_SUPPORT            = NO
+IDL_PROPERTY_SUPPORT   = YES
+DISTRIBUTE_GROUP_DOC   = NO
+GROUP_NESTED_COMPOUNDS = NO
+SUBGROUPING            = YES
+INLINE_GROUPED_CLASSES = NO
+INLINE_SIMPLE_STRUCTS  = NO
+TYPEDEF_HIDES_STRUCT   = NO
+LOOKUP_CACHE_SIZE      = 0
+#---------------------------------------------------------------------------
+# Build related configuration options
+#---------------------------------------------------------------------------
+EXTRACT_ALL            = NO
+EXTRACT_PRIVATE        = NO
+EXTRACT_PRIV_VIRTUAL   = NO
+EXTRACT_PACKAGE        = NO
+EXTRACT_STATIC         = NO
+EXTRACT_LOCAL_CLASSES  = YES
+EXTRACT_LOCAL_METHODS  = NO
+EXTRACT_ANON_NSPACES   = NO
+HIDE_UNDOC_MEMBERS     = NO
+HIDE_UNDOC_CLASSES     = NO
+HIDE_FRIEND_COMPOUNDS  = NO
+HIDE_IN_BODY_DOCS      = NO
+INTERNAL_DOCS          = NO
+CASE_SENSE_NAMES       = YES
+HIDE_SCOPE_NAMES       = NO
+HIDE_COMPOUND_REFERENCE= NO
+SHOW_INCLUDE_FILES     = YES
+SHOW_GROUPED_MEMB_INC  = NO
+FORCE_LOCAL_INCLUDES   = NO
+INLINE_INFO            = YES
+SORT_MEMBER_DOCS       = YES
+SORT_BRIEF_DOCS        = NO
+SORT_MEMBERS_CTORS_1ST = NO
+SORT_GROUP_NAMES       = NO
+SORT_BY_SCOPE_NAME     = NO
+STRICT_PROTO_MATCHING  = NO
+GENERATE_TODOLIST      = YES
+GENERATE_TESTLIST      = YES
+GENERATE_BUGLIST       = YES
+GENERATE_DEPRECATEDLIST= YES
+ENABLED_SECTIONS       =
+MAX_INITIALIZER_LINES  = 30
+SHOW_USED_FILES        = YES
+SHOW_FILES             = YES
+SHOW_NAMESPACES        = YES
+FILE_VERSION_FILTER    =
+LAYOUT_FILE            =
+CITE_BIB_FILES         =
+#---------------------------------------------------------------------------
+# Configuration options related to warning and progress messages
+#---------------------------------------------------------------------------
+QUIET                  = no
+WARNINGS               = YES
+WARN_IF_UNDOCUMENTED   = YES
+WARN_IF_DOC_ERROR      = YES
+WARN_NO_PARAMDOC       = NO
+WARN_AS_ERROR          = NO
+WARN_FORMAT            = "$file:$line: $text"
+WARN_LOGFILE           =
+#---------------------------------------------------------------------------
+# Configuration options related to the input files
+#---------------------------------------------------------------------------
+INPUT                  =
+INPUT_ENCODING         = UTF-8
+FILE_PATTERNS          = *.h, *.hpp
+RECURSIVE              = YES
+EXCLUDE                =
+EXCLUDE_SYMLINKS       = NO
+EXCLUDE_PATTERNS       =
+EXCLUDE_SYMBOLS        =
+EXAMPLE_PATH           =
+EXAMPLE_PATTERNS       =
+EXAMPLE_RECURSIVE      = NO
+IMAGE_PATH             =
+INPUT_FILTER           =
+FILTER_PATTERNS        =
+FILTER_SOURCE_FILES    = NO
+FILTER_SOURCE_PATTERNS =
+USE_MDFILE_AS_MAINPAGE =
+#---------------------------------------------------------------------------
+# Configuration options related to source browsing
+#---------------------------------------------------------------------------
+SOURCE_BROWSER         = NO
+INLINE_SOURCES         = NO
+STRIP_CODE_COMMENTS    = YES
+REFERENCED_BY_RELATION = NO
+REFERENCES_RELATION    = NO
+REFERENCES_LINK_SOURCE = YES
+SOURCE_TOOLTIPS        = YES
+USE_HTAGS              = NO
+VERBATIM_HEADERS       = YES
+CLANG_ASSISTED_PARSING = NO
+CLANG_OPTIONS          =
+CLANG_DATABASE_PATH    =
+#---------------------------------------------------------------------------
+# Configuration options related to the alphabetical class index
+#---------------------------------------------------------------------------
+ALPHABETICAL_INDEX     = YES
+COLS_IN_ALPHA_INDEX    = 5
+IGNORE_PREFIX          =
+#---------------------------------------------------------------------------
+# Configuration options related to the HTML output
+#---------------------------------------------------------------------------
+GENERATE_HTML          = NO
+HTML_OUTPUT            = html
+HTML_FILE_EXTENSION    = .html
+HTML_HEADER            =
+HTML_FOOTER            =
+HTML_STYLESHEET        =
+HTML_EXTRA_STYLESHEET  =
+HTML_EXTRA_FILES       =
+HTML_COLORSTYLE_HUE    = 220
+HTML_COLORSTYLE_SAT    = 100
+HTML_COLORSTYLE_GAMMA  = 80
+HTML_TIMESTAMP         = NO
+HTML_DYNAMIC_MENUS     = YES
+HTML_DYNAMIC_SECTIONS  = NO
+HTML_INDEX_NUM_ENTRIES = 100
+GENERATE_DOCSET        = NO
+DOCSET_FEEDNAME        = "Doxygen generated docs"
+DOCSET_BUNDLE_ID       = org.doxygen.Project
+DOCSET_PUBLISHER_ID    = org.doxygen.Publisher
+DOCSET_PUBLISHER_NAME  = Publisher
+GENERATE_HTMLHELP      = NO
+CHM_FILE               =
+HHC_LOCATION           =
+GENERATE_CHI           = NO
+CHM_INDEX_ENCODING     =
+BINARY_TOC             = NO
+TOC_EXPAND             = NO
+GENERATE_QHP           = NO
+QCH_FILE               =
+QHP_NAMESPACE          = org.doxygen.Project
+QHP_VIRTUAL_FOLDER     = doc
+QHP_CUST_FILTER_NAME   =
+QHP_CUST_FILTER_ATTRS  =
+QHP_SECT_FILTER_ATTRS  =
+QHG_LOCATION           =
+GENERATE_ECLIPSEHELP   = NO
+ECLIPSE_DOC_ID         = org.doxygen.Project
+DISABLE_INDEX          = NO
+GENERATE_TREEVIEW      = NO
+ENUM_VALUES_PER_LINE   = 4
+TREEVIEW_WIDTH         = 250
+EXT_LINKS_IN_WINDOW    = NO
+HTML_FORMULA_FORMAT    = png
+FORMULA_FONTSIZE       = 10
+FORMULA_TRANSPARENT    = YES
+FORMULA_MACROFILE      =
+USE_MATHJAX            = NO
+MATHJAX_FORMAT         = HTML-CSS
+MATHJAX_RELPATH        = https://cdn.jsdelivr.net/npm/mathjax@@2
+MATHJAX_EXTENSIONS     =
+MATHJAX_CODEFILE       =
+SEARCHENGINE           = YES
+SERVER_BASED_SEARCH    = NO
+EXTERNAL_SEARCH        = NO
+SEARCHENGINE_URL       =
+SEARCHDATA_FILE        = searchdata.xml
+EXTERNAL_SEARCH_ID     =
+EXTRA_SEARCH_MAPPINGS  =
+#---------------------------------------------------------------------------
+# Configuration options related to the LaTeX output
+#---------------------------------------------------------------------------
+GENERATE_LATEX         = NO
+LATEX_OUTPUT           = latex
+LATEX_CMD_NAME         =
+MAKEINDEX_CMD_NAME     = makeindex
+LATEX_MAKEINDEX_CMD    = makeindex
+COMPACT_LATEX          = NO
+PAPER_TYPE             = a4
+EXTRA_PACKAGES         =
+LATEX_HEADER           =
+LATEX_FOOTER           =
+LATEX_EXTRA_STYLESHEET =
+LATEX_EXTRA_FILES      =
+PDF_HYPERLINKS         = YES
+USE_PDFLATEX           = YES
+LATEX_BATCHMODE        = NO
+LATEX_HIDE_INDICES     = NO
+LATEX_SOURCE_CODE      = NO
+LATEX_BIB_STYLE        = plain
+LATEX_TIMESTAMP        = NO
+LATEX_EMOJI_DIRECTORY  =
+#---------------------------------------------------------------------------
+# Configuration options related to the RTF output
+#---------------------------------------------------------------------------
+GENERATE_RTF           = NO
+RTF_OUTPUT             = rtf
+COMPACT_RTF            = NO
+RTF_HYPERLINKS         = NO
+RTF_STYLESHEET_FILE    =
+RTF_EXTENSIONS_FILE    =
+RTF_SOURCE_CODE        = NO
+#---------------------------------------------------------------------------
+# Configuration options related to the man page output
+#---------------------------------------------------------------------------
+GENERATE_MAN           = NO
+MAN_OUTPUT             = man
+MAN_EXTENSION          = .3
+MAN_SUBDIR             =
+MAN_LINKS              = NO
+#---------------------------------------------------------------------------
+# Configuration options related to the XML output
+#---------------------------------------------------------------------------
+GENERATE_XML           = YES
+XML_OUTPUT             = xml
+XML_PROGRAMLISTING     = YES
+XML_NS_MEMB_FILE_SCOPE = NO
+#---------------------------------------------------------------------------
+# Configuration options related to the DOCBOOK output
+#---------------------------------------------------------------------------
+GENERATE_DOCBOOK       = NO
+DOCBOOK_OUTPUT         = docbook
+DOCBOOK_PROGRAMLISTING = NO
+#---------------------------------------------------------------------------
+# Configuration options for the AutoGen Definitions output
+#---------------------------------------------------------------------------
+GENERATE_AUTOGEN_DEF   = NO
+#---------------------------------------------------------------------------
+# Configuration options related to the Perl module output
+#---------------------------------------------------------------------------
+GENERATE_PERLMOD       = NO
+PERLMOD_LATEX          = NO
+PERLMOD_PRETTY         = YES
+PERLMOD_MAKEVAR_PREFIX =
+#---------------------------------------------------------------------------
+# Configuration options related to the preprocessor
+#---------------------------------------------------------------------------
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = YES
+EXPAND_ONLY_PREDEF     = NO
+SEARCH_INCLUDES        = YES
+INCLUDE_PATH           =
+INCLUDE_FILE_PATTERNS  =
+PREDEFINED             =
+EXPAND_AS_DEFINED      =
+SKIP_FUNCTION_MACROS   = YES
+#---------------------------------------------------------------------------
+# Configuration options related to external references
+#---------------------------------------------------------------------------
+TAGFILES               =
+GENERATE_TAGFILE       =
+ALLEXTERNALS           = NO
+EXTERNAL_GROUPS        = YES
+EXTERNAL_PAGES         = YES
+#---------------------------------------------------------------------------
+# Configuration options related to the dot tool
+#---------------------------------------------------------------------------
+CLASS_DIAGRAMS         = YES
+DIA_PATH               =
+HIDE_UNDOC_RELATIONS   = YES
+HAVE_DOT               = NO
+DOT_NUM_THREADS        = 0
+DOT_FONTNAME           = Helvetica
+DOT_FONTSIZE           = 10
+DOT_FONTPATH           =
+CLASS_GRAPH            = YES
+COLLABORATION_GRAPH    = YES
+GROUP_GRAPHS           = YES
+UML_LOOK               = NO
+UML_LIMIT_NUM_FIELDS   = 10
+TEMPLATE_RELATIONS     = NO
+INCLUDE_GRAPH          = YES
+INCLUDED_BY_GRAPH      = YES
+CALL_GRAPH             = NO
+CALLER_GRAPH           = NO
+GRAPHICAL_HIERARCHY    = YES
+DIRECTORY_GRAPH        = YES
+DOT_IMAGE_FORMAT       = png
+INTERACTIVE_SVG        = NO
+DOT_PATH               =
+DOTFILE_DIRS           =
+MSCFILE_DIRS           =
+DIAFILE_DIRS           =
+PLANTUML_JAR_PATH      =
+PLANTUML_CFG_FILE      =
+PLANTUML_INCLUDE_PATH  =
+DOT_GRAPH_MAX_NODES    = 50
+MAX_DOT_GRAPH_DEPTH    = 0
+DOT_TRANSPARENT        = NO
+DOT_MULTI_TARGETS      = NO
+GENERATE_LEGEND        = YES
+DOT_CLEANUP            = YES
diff --git a/doc_requirements.txt b/doc_requirements.txt
index 61ce7549b..4eebb5519 100644
--- a/doc_requirements.txt
+++ b/doc_requirements.txt
@@ -5,3 +5,4 @@ scipy
 matplotlib
 pandas
 pydata-sphinx-theme
+breathe
diff --git a/numpy/core/include/numpy/.doxyfile b/numpy/core/include/numpy/.doxyfile
new file mode 100644
index 000000000..ed2aefff7
--- /dev/null
+++ b/numpy/core/include/numpy/.doxyfile
@@ -0,0 +1,2 @@
+INCLUDE_PATH += @CUR_DIR
+PREDEFINED += NPY_INTERNAL_BUILD
diff --git a/numpy/core/src/common/.doxyfile b/numpy/core/src/common/.doxyfile
new file mode 100644
index 000000000..462cbbcfa
--- /dev/null
+++ b/numpy/core/src/common/.doxyfile
@@ -0,0 +1 @@
+INCLUDE_PATH += @CUR_DIR