Add documentation for breathe-apidoc

breathe/apidoc.py

@@ -86,7 +86,11 @@ def write_file(name, text, args):
 
 def format_heading(level, text):
     """Create a heading of <level> [1, 2 or 3 supported]."""
-    underlining = ["=", "-", "~",][
+    underlining = [
+        "=",
+        "-",
+        "~",
+    ][
         level - 1
     ] * len(text)
     return "%s\n%s\n\n" % (text, underlining)
@@ -153,78 +157,80 @@ def __call__(self, parser, namespace, values, option_string=None):
         setattr(namespace, self.dest, value_list)
 
 
-def main():
-    """Parse and check the command line arguments."""
-    parser = argparse.ArgumentParser(
-        description="""\
+"""Parse and check the command line arguments."""
+parser = argparse.ArgumentParser(
+    description="""\
 Parse XML created by Doxygen in <rootpath> and create one reST file with
 breathe generation directives per definition in the <DESTDIR>.
 
 Note: By default this script will not overwrite already created files.""",
-        formatter_class=argparse.RawDescriptionHelpFormatter,
-    )
-
-    parser.add_argument(
-        "-o",
-        "--output-dir",
-        action="store",
-        dest="destdir",
-        help="Directory to place all output",
-        required=True,
-    )
-    parser.add_argument(
-        "-f", "--force", action="store_true", dest="force", help="Overwrite existing files"
-    )
-    parser.add_argument(
-        "-m",
-        "--members",
-        action="store_true",
-        dest="members",
-        help="Include members for types: %s" % MEMBERS_TYPES,
-    )
-    parser.add_argument(
-        "-n",
-        "--dry-run",
-        action="store_true",
-        dest="dryrun",
-        help="Run the script without creating files",
-    )
-    parser.add_argument(
-        "-T",
-        "--no-toc",
-        action="store_true",
-        dest="notoc",
-        help="Don't create a table of contents file",
-    )
-    parser.add_argument(
-        "-s",
-        "--suffix",
-        action="store",
-        dest="suffix",
-        help="file suffix (default: rst)",
-        default="rst",
-    )
-    parser.add_argument(
-        "-p",
-        "--project",
-        action="store",
-        dest="project",
-        help="project to add to generated directives",
-    )
-    parser.add_argument(
-        "-g",
-        "--generate",
-        action=TypeAction,
-        dest="outtypes",
-        help="types of output to generate, comma-separated list",
-    )
-    parser.add_argument(
-        "-q", "--quiet", action="store_true", dest="quiet", help="suppress informational messages"
-    )
-    parser.add_argument(
-        "--version", action="version", version="Breathe (breathe-apidoc) %s" % __version__
-    )
-    parser.add_argument("rootpath", type=str, help="The directory contains index.xml")
+    formatter_class=argparse.RawDescriptionHelpFormatter,
+)
+
+parser.add_argument(
+    "-o",
+    "--output-dir",
+    action="store",
+    dest="destdir",
+    help="Directory to place all output",
+    required=True,
+)
+parser.add_argument(
+    "-f", "--force", action="store_true", dest="force", help="Overwrite existing files"
+)
+parser.add_argument(
+    "-m",
+    "--members",
+    action="store_true",
+    dest="members",
+    help="Include members for types: %s" % MEMBERS_TYPES,
+)
+parser.add_argument(
+    "-n",
+    "--dry-run",
+    action="store_true",
+    dest="dryrun",
+    help="Run the script without creating files",
+)
+parser.add_argument(
+    "-T",
+    "--no-toc",
+    action="store_true",
+    dest="notoc",
+    help="Don't create a table of contents file",
+)
+parser.add_argument(
+    "-s",
+    "--suffix",
+    action="store",
+    dest="suffix",
+    help="file suffix (default: rst)",
+    default="rst",
+)
+parser.add_argument(
+    "-p",
+    "--project",
+    action="store",
+    dest="project",
+    help="project to add to generated directives",
+)
+parser.add_argument(
+    "-g",
+    "--generate",
+    action=TypeAction,
+    dest="outtypes",
+    help="types of output to generate, comma-separated list",
+)
+parser.add_argument(
+    "-q", "--quiet", action="store_true", dest="quiet", help="suppress informational messages"
+)
+parser.add_argument(
+    "--version", action="version", version="Breathe (breathe-apidoc) %s" % __version__
+)
+parser.add_argument("rootpath", type=str, help="The directory contains index.xml")
+
+
+def main():
     args = parser.parse_args()
 
     if args.suffix.startswith("."):

documentation/source/apidoc.rst

@@ -0,0 +1,18 @@
+.. _apidoc:
+
+Automatic API documentation
+===========================
+
+The ``breathe-apidoc`` command can be used to automatically generate
+``.rst`` files related to the selected API members.
+
+It uses the XML output generated by Doxygen, so you need to make sure that
+its ``GENERATE_XML`` option is set to ``YES``.
+
+Usage
+-----
+
+.. argparse::
+   :module: breathe.apidoc
+   :func: parser
+   :prog: breathe-apidoc

documentation/source/conf.py

@@ -35,6 +35,7 @@
     "sphinx.ext.ifconfig",
     "sphinx.ext.graphviz",
     "sphinx_copybutton",
+    "sphinxarg.ext",
 ]
 
 read_the_docs_build = os.environ.get("READTHEDOCS", None) == "True"
@@ -60,7 +61,6 @@
 git_tag = git_tag.decode("ascii")
 
 if travis_build:
-
     # Don't attempt to set the path as breathe is installed to virtualenv on travis
 
     # Set values with simple strings
@@ -69,7 +69,6 @@
     documentation_build = "travis"
 
 elif read_the_docs_build:
-
     # On RTD we'll be in the 'source' directory
     sys.path.append("../../")
 
@@ -96,7 +95,6 @@
         documentation_build = "readthedocs_latest"
 
 else:
-
     # For our usual dev build we'll be in the 'documentation' directory but Sphinx seems to set the
     # current working directory to 'source' so we append relative to that
     sys.path.append("../../")
@@ -396,7 +394,6 @@ def generate_doxygen_xml(app):
     read_the_docs_build = os.environ.get("READTHEDOCS", None) == "True"
 
     if read_the_docs_build:
-
         # Attempt to build the doxygen files on the RTD server. Explicitly override the path/name used
         # for executing doxygen to simply be 'doxygen' to stop the makefiles looking for the executable.
         # This is because the `which doxygen` effort seemed to fail when tested on the RTD server.
@@ -406,7 +403,6 @@ def generate_doxygen_xml(app):
 
 
 def setup(app):
-
     # Approach borrowed from the Sphinx docs
     app.add_object_type(
         "confval",

documentation/source/index.rst

@@ -54,6 +54,7 @@ Setup & Usage
    :maxdepth: 1
 
    quickstart
+   apidoc
    directives
    differences
    readthedocs

documentation/source/quickstart.rst

@@ -64,3 +64,7 @@ For each of these commands the following directives may be specified:
 ``path``
    Directly specifies the path to the folder with the doxygen output. This
    overrides the project and default project.
+
+It is also possible to generate API documentation automatically,
+please refer to :ref:`apidoc` for more details.
+

requirements/development.txt

@@ -11,4 +11,5 @@ types-Pygments
 black==22.3.0
 
 sphinx-copybutton
+sphinx-argparse
 furo