From f2ac7bbeb8ce95e0202c88ee4c4002b6fb37fce3 Mon Sep 17 00:00:00 2001 From: Michele Peresano Date: Wed, 17 May 2023 23:21:08 +0200 Subject: [PATCH 1/4] Add sphinx-argparse to documentation dependencies --- documentation/source/conf.py | 6 +----- requirements/development.txt | 1 + 2 files changed, 2 insertions(+), 5 deletions(-) diff --git a/documentation/source/conf.py b/documentation/source/conf.py index c1cf8c34..7434a789 100644 --- a/documentation/source/conf.py +++ b/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", diff --git a/requirements/development.txt b/requirements/development.txt index 35b1c56d..cf39022c 100644 --- a/requirements/development.txt +++ b/requirements/development.txt @@ -11,4 +11,5 @@ types-Pygments black==22.3.0 sphinx-copybutton +sphinx-argparse furo \ No newline at end of file From 9c311b745fe799a466996221cd951435d9085e18 Mon Sep 17 00:00:00 2001 From: Michele Peresano Date: Wed, 17 May 2023 23:22:38 +0200 Subject: [PATCH 2/4] Update apidoc.py - make argparse parser global for sphinx-argparse to find - PEP8-compliant formatting --- breathe/apidoc.py | 144 ++++++++++++++++++++++++---------------------- 1 file changed, 75 insertions(+), 69 deletions(-) diff --git a/breathe/apidoc.py b/breathe/apidoc.py index e7ff33eb..f5d4718a 100644 --- a/breathe/apidoc.py +++ b/breathe/apidoc.py @@ -86,7 +86,11 @@ def write_file(name, text, args): def format_heading(level, text): """Create a heading of [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 and create one reST file with breathe generation directives per definition in the . 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("."): From dfdaf7c2048c5f41a8f6bcd551f78df8c769088b Mon Sep 17 00:00:00 2001 From: Michele Peresano Date: Wed, 17 May 2023 23:23:09 +0200 Subject: [PATCH 3/4] Add new apidoc.rst page to documentation --- documentation/source/apidoc.rst | 18 ++++++++++++++++++ documentation/source/index.rst | 1 + 2 files changed, 19 insertions(+) create mode 100644 documentation/source/apidoc.rst diff --git a/documentation/source/apidoc.rst b/documentation/source/apidoc.rst new file mode 100644 index 00000000..93899344 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/documentation/source/index.rst b/documentation/source/index.rst index 45995253..e138f6f1 100644 --- a/documentation/source/index.rst +++ b/documentation/source/index.rst @@ -54,6 +54,7 @@ Setup & Usage :maxdepth: 1 quickstart + apidoc directives differences readthedocs From 4cb759d9510b0e3ea58104c99791911579424385 Mon Sep 17 00:00:00 2001 From: Michele Peresano Date: Wed, 17 May 2023 23:23:45 +0200 Subject: [PATCH 4/4] Update quickstart.rst for auto API documentation --- documentation/source/quickstart.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/documentation/source/quickstart.rst b/documentation/source/quickstart.rst index f1c7748c..d711e262 100644 --- a/documentation/source/quickstart.rst +++ b/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. +