Improve docstrings, add API section to Sphinx (#112)

.gitignore

@@ -52,6 +52,7 @@ coverage.xml
 
 # Sphinx documentation
 docs/_build/
+docs/api
 
 # PyBuilder
 target/

README.rst

@@ -19,14 +19,14 @@ Features
 * Merge test result xml files.
 * Specify xml parser. For example you can use lxml to speed things up.
 * Invoke from command line, or `python -m junitparser`
-* Python 2 and 3 support (As of Nov 2020, 1/4 of the users are still on Python 
+* Python 2 and 3 support (As of Nov 2020, 1/4 of the users are still on Python
   2, so there is no plan to drop Python 2 support)
 
 Note on version 2
 -----------------
 
-Version 2 improved support for pytest result xml files by fixing a few issues, 
-notably that there could be multiple <Failure> or <Error> entries. There is a 
+Version 2 improved support for pytest result xml files by fixing a few issues,
+notably that there could be multiple <Failure> or <Error> entries. There is a
 breaking change that ``TestCase.result`` is now a list instead of a single item.
 If you are using this attribute, please update your code accordingly.
 
@@ -232,7 +232,7 @@ read them out:
 Command Line
 ------------
 
-.. code-block:: shell
+.. code-block:: console
 
     $ junitparser --help
     usage: junitparser [-h] [-v] {merge} ...
@@ -249,7 +249,7 @@ Command Line
     -v, --version  show program's version number and exit
 
 
-.. code-block:: shell
+.. code-block:: console
 
     $ junitparser merge --help
     usage: junitparser merge [-h] [--glob] paths [paths ...] output
@@ -264,7 +264,7 @@ Command Line
       --suite-name SUITE_NAME
                   Name added to <testsuites>.
 
-.. code-block:: shell
+.. code-block:: console
 
     $ junitparser verify --help
     usage: junitparser verify [-h] [--glob] paths [paths ...]

docs/Makefile

@@ -6,6 +6,7 @@ SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build
+SPHINXAPIDOC  = sphinx-apidoc
 
 # Put it first so that "make" without argument is like "make help".
 help:
@@ -16,4 +17,5 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXAPIDOC) -f -o api/ -H "API" -e ../junitparser
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/api/inheritance_diagram.rst

@@ -0,0 +1,5 @@
+Class Inheritance
+=================
+
+.. inheritance-diagram:: junitparser.junitparser
+   :parts: 5

docs/conf.py

@@ -16,12 +16,13 @@
 import sys
 
 sys.path.insert(0, os.path.abspath("../junitparser"))
+sys.path.insert(0, os.path.abspath("../"))
 
 
 # -- Project information -----------------------------------------------------
 
 project = "junitparser"
-copyright = "2019, Joel Wang"
+copyright = "2019-2023, Joel Wang"
 author = "Joel Wang"
 
 # The short X.Y version
@@ -41,8 +42,16 @@
 # ones.
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.inheritance_diagram",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
 ]
 
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+}
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
@@ -60,7 +69,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -87,7 +96,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
+# html_static_path = ["_static"]
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.

docs/index.rst

@@ -1,17 +1,11 @@
-.. junitparser documentation master file, created by
-   sphinx-quickstart on Fri Mar  1 10:40:19 2019.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+.. include:: ../README.rst
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
-
-.. include:: ../README.rst
-
-.. .. automodule:: junitparser
-..    :members:
+   :hidden:
 
+   api/inheritance_diagram
+   api/modules
 
 Indices and tables
 ==================

junitparser/cli.py

@@ -6,7 +6,7 @@
 
 
 def merge(paths, output, suite_name):
-    """Merge xml report."""
+    """Merge XML report."""
     result = JUnitXml()
     for path in paths:
         result += JUnitXml.fromfile(path)
@@ -45,7 +45,7 @@ def _parser(prog_name=None):  # pragma: no cover
 
     # command: merge
     merge_parser = command_parser.add_parser(
-        "merge", help="Merge Junit XML format reports with junitparser."
+        "merge", help="Merge JUnit XML format reports with junitparser."
     )
     merge_parser.add_argument(
         "--glob",
@@ -56,7 +56,7 @@ def _parser(prog_name=None):  # pragma: no cover
     )
     merge_parser.add_argument("paths", nargs="+", help="Original XML path(s).")
     merge_parser.add_argument(
-        "output", help='Merged XML Path, setting to "-" will output console'
+        "output", help='Merged XML Path, setting to "-" will output to the console'
     )
     merge_parser.add_argument(
         "--suite-name",