[wip] More doxygen tuning and addition of python auto generation

doc/Doxyfile

@@ -203,7 +203,7 @@ JAVADOC_BANNER         = NO
 # requiring an explicit \brief command for a brief description.)
 # The default value is: NO.
 
-QT_AUTOBRIEF           = YES
+QT_AUTOBRIEF           = NO
 
 # The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make doxygen treat a
 # multi-line C++ special comment block (i.e. a block of //! or /// comments) as
@@ -308,9 +308,8 @@ OPTIMIZE_OUTPUT_SLICE  = NO
 # the files are not read by doxygen.
 
 EXTENSION_MAPPING      = h=C++ \
-                         icpp=C++ \
-                         icc=C++ \
-                         inl=C++
+                         ipp=C++ \
+                         cc=C++
 
 # If the MARKDOWN_SUPPORT tag is enabled then doxygen pre-processes all comments
 # according to the Markdown format, which allows for more readable
@@ -337,7 +336,7 @@ TOC_INCLUDE_HEADINGS   = 5
 # globally by setting AUTOLINK_SUPPORT to NO.
 # The default value is: YES.
 
-AUTOLINK_SUPPORT       = YES
+AUTOLINK_SUPPORT       = NO
 
 # If you use STL classes (i.e. std::string, std::vector, etc.) but do not want
 # to include (a tag file for) the STL sources as input, then you should set this
@@ -347,7 +346,7 @@ AUTOLINK_SUPPORT       = YES
 # diagrams that involve STL classes more complete and accurate.
 # The default value is: NO.
 
-BUILTIN_STL_SUPPORT    = NO
+BUILTIN_STL_SUPPORT    = YES
 
 # If you use Microsoft's C++/CLI language, you should set this option to YES to
 # enable parsing support.
@@ -460,7 +459,7 @@ EXTRACT_ALL            = YES
 # be included in the documentation.
 # The default value is: NO.
 
-EXTRACT_PRIVATE        = YES
+EXTRACT_PRIVATE        = NO
 
 # If the EXTRACT_PRIV_VIRTUAL tag is set to YES, documented private virtual
 # methods of a class will be included in the documentation.
@@ -486,7 +485,7 @@ EXTRACT_STATIC         = NO
 # for Java sources.
 # The default value is: YES.
 
-EXTRACT_LOCAL_CLASSES  = YES
+EXTRACT_LOCAL_CLASSES  = NO
 
 # This flag is only useful for Objective-C code. If set to YES, local methods,
 # which are defined in the implementation section but not in the interface are
@@ -2143,7 +2142,7 @@ SEARCH_INCLUDES        = YES
 # preprocessor.
 # This tag requires that the tag SEARCH_INCLUDES is set to YES.
 
-INCLUDE_PATH           =
+INCLUDE_PATH           = ../include
 
 # You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard
 # patterns (like *.h and *.hpp) to filter out the header-files in the
@@ -2161,7 +2160,7 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-PREDEFINED             =
+PREDEFINED             = DOXYGEN
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The

doc/conf.py

@@ -13,6 +13,7 @@
 import os
 import sys
 import subprocess
+import shutil
 from pathlib import Path
 
 
@@ -41,20 +42,29 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    "myst_parser",
-    "breathe",
     # auto generation of python bindings documentation from docstrings
     "sphinx.ext.napoleon",
+    "myst_parser",
+    "breathe",
 ]
 
+source_suffix = {".rst": "restructuredtext", ".md": "markdown"}
+
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ["_templates"]
+# templates_path = ["_templates"]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "cpp_api.rst", "py_api.rst"]
+
+# cpp as main language
+primary_domain = "cpp"
+highlight_language = "cpp"
 
+# -- Options for MyST parser -------------------------------------------------
+myst_enable_extensions = ["colon_fence", "html_image"]
+myst_heading_anchor = 3
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -63,20 +73,30 @@
 #
 html_theme = "sphinx_rtd_theme"
 
-# 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"]
+# # 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 tml_static_path = ["_static"]
 
+# Do not copy the source markdown / rst files to the generated documentation
+html_copy_source = False
+html_show_sourcelink = False
 
-# Make sure that the __init__ docstrings appear as part of the class
-# documentation
-autoclass_content = "both"
+html_theme_options = {
+    "collapse_navigation": False,
+    "navigation_depth": 4,
+    "prev_next_buttons_location": None,  # no navigation buttons
+}
 
 # -- Doxygen integration with Breathe -----------------------------------------
 
+breathe_projects = {"PODIO": "_build/cpp/doxygen-xml"}
+breathe_default_project = "PODIO"
+breathe_domain_by_extension = {"h": "cpp", "cc": "cpp", "ipp": "cpp"}
+breathe_default_members = ("members", "undoc-members")
 
-# -- Automatic API documentation ----------------------------------------------
+
+# -- Automatic API documentation (c++) ----------------------------------------
 
 print(f"Executing doxygen in {doc_dir}")
 doxygen_version = subprocess.check_output(["doxygen", "--version"], encoding="utf-8")
@@ -91,7 +111,7 @@
     ["doxygen", "Doxyfile"], stdout=subprocess.PIPE, cwd=doc_dir, env=env
 )
 
-api_index_targetdir = doc_dir / "cpp_api/api.md"
+cpp_api_index_target = doc_dir / "cpp_api/api.rst"
 
 print(f"Executing breath apidoc in {doc_dir}")
 subprocess.check_call(
@@ -100,3 +120,32 @@
     cwd=doc_dir,
     env=env,
 )
+
+if not cpp_api_index_target.exists():
+    shutil.copyfile(doc_dir / "cpp_api.rst", cpp_api_index_target)
+
+print("Done with c++ API doc generation")
+
+# -- Automatic API documentation (python) --------------------------------------
+
+# Make sure that the __init__ docstrings appear as part of the class
+# documentation
+autoclass_content = "both"
+
+print("Executing sphinx-apidoc for python API")
+print(f"Executing sphinx-apidoc in {doc_dir}")
+subprocess.check_call(
+    [
+        sys.executable,
+        "-m",
+        "sphinx.ext.apidoc",
+        "--force",
+        "-o",
+        "py_api",
+        "../python",
+        "*/test_*.py",  # exclude tests
+        "podio_version.py",  # exclude the convenience version wrapper
+    ]
+)
+
+print("Done with python API doc generation")

doc/cpp_api.rst

@@ -0,0 +1,10 @@
+C++ API documentation
+=====================
+
+.. toctree::
+   :maxdepth: 1
+
+   classlist
+   structlist
+   namespacelist
+   grouplist

python/podio_gen/generator_base.py

@@ -47,6 +47,7 @@ class ClassGeneratorBaseMixin:
   augment the common processing with language specifics.
 
   The following members are initialized and accessible from inheriting classes
+
   - yamlfile (the path to the yamlfile)
   - install_dir (top level directory into which the code should be generated)
   - package_name (the name of the package)