Setup for sphinx + doxygen documentation

c++/app4triqs/app4triqs.cpp

@@ -1,3 +1,8 @@
+/**
+ * @file
+ * @brief Implementation details for app4triqs.hpp
+ */
+
 #include <cmath>
 #include "./app4triqs.hpp"
 

c++/app4triqs/app4triqs.hpp

@@ -1,13 +1,22 @@
+/**
+ * @file
+ * @brief Provides various functions and classes for the **app4triqs** application.
+ */
+
 #pragma once
 #include <h5/h5.hpp>
 
 namespace app4triqs {
 
+  /**
+   * @addtogroup mygroup
+   * @{
+   */
+
   /**
    * A very useful and important class
    *
    * @note A Useful note
-   * @include app4triqs/app4triqs.hpp
    */
   class toto {
 
@@ -19,7 +28,7 @@ namespace app4triqs {
     /**
      * Construct from integer
      *
-     * @param i_ a scalar  :math:`G(\tau)`
+     * @param i_ a scalar \f$ G(\tau) \f$
      */
     explicit toto(int i_) : i(i_) {}
 
@@ -31,13 +40,13 @@ namespace app4triqs {
 
     /// Copy/Move assignment
     toto &operator=(toto const &) = default;
-    toto &operator=(toto &&) = default;
+    toto &operator=(toto &&)      = default;
 
     /// Simple accessor
     [[nodiscard]] int get_i() const { return i; }
 
     /** 
-     * A simple function with :math:`G(\tau)`
+     * A simple function with \f$ G(\tau) \f$
      *
      * @param u Nothing useful
      */
@@ -57,22 +66,23 @@ namespace app4triqs {
     friend void h5_read(h5::group grp, std::string subgroup_name, toto &m);
 
     /// Serialization
-    void serialize(auto &ar) const { ar &i; }
-    void deserialize(auto &ar) { ar &i; }
+    void serialize(auto &ar) const { ar & i; }
+    void deserialize(auto &ar) { ar & i; }
   };
 
   /**
-   * Chain digits of two integers
+   * @brief Chain digits of two integers
    *
-   * @head A set of functions that implement chaining
+   * @details A set of functions that implement chaining
    *
-   * @tail Do I really need to explain more ? 
+   * Do I really need to explain more ? 
    *
    * @param i The first integer
    * @param j The second integer
    * @return An integer containing the digits of both i and j
-   *
    */
   int chain(int i, int j);
 
+  /** @} */
+
 } // namespace app4triqs

doc/CMakeLists.txt

@@ -4,7 +4,6 @@ configure_file(${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in ${CMAKE_CURRENT_BINARY_DIR
 # --------------------------------------------------------
 # Build & Run the C++ doc examples and capture the output
 # --------------------------------------------------------
-
 add_custom_target(${PROJECT_NAME}_docs_example_output)
 file(GLOB_RECURSE ExampleList RELATIVE ${CMAKE_CURRENT_SOURCE_DIR} *.cpp)
 foreach(example ${ExampleList})
@@ -55,3 +54,8 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/ COMPONENT documentation DEST
   REGEX "\\.(html|pdf|png|gif|jpg|svg|ico|js|xsl|css|py|txt|inv|bib|ttf|woff2|eot|sh)$"
   PATTERN "_*"
 )
+
+# ---------------------------------
+# Build doxygen documentation
+# ---------------------------------
+add_subdirectory(doxygen)

doc/ChangeLog.md

@@ -1,5 +1,3 @@
-(changelog)=
-
 # Changelog
 
 ## Version 3.1.0

doc/_templates/autosummary_class_template.rst

@@ -4,26 +4,31 @@
 
 .. autoclass:: {{ objname }}
 
-{% block methods %}
-{% if methods %}
-.. rubric:: {{ _('Methods') }}
+  {% block methods %}
+   .. HACK -- the point here is that we don't want this to appear in the output, but the autosummary should still generate the pages.
+      .. autosummary::
+         :toctree:
+      {% for item in all_methods %}
+         {%- if not item.startswith('_') or item in ['__call__', '__mul__', '__getitem__', '__len__', '__pow__'] %}
+         {{ name }}.{{ item }}
+         {%- endif -%}
+      {%- endfor %}
+      {% for item in inherited_members %}
+         {%- if item in ['__call__', '__mul__', '__getitem__', '__len__', '__pow__'] %}
+         {{ name }}.{{ item }}
+         {%- endif -%}
+      {%- endfor %}
+  {% endblock %}
 
-.. autosummary::
-    :toctree:                             
-    {% for item in methods %}
-      ~{{ name }}.{{ item }}
-    {%- endfor %}
-{% endif %}
-{% endblock %}
-
-{% block attributes %}
-{% if attributes %}
-.. rubric:: {{ _('Attributes') }}
-
-.. autosummary::
-    :toctree:                             
-    {% for item in attributes %}
-      ~{{ name }}.{{ item }}
-    {%- endfor %}
-{% endif %}
-{% endblock %}
+  {% block attributes %}
+  {% if attributes %}
+   .. HACK -- the point here is that we don't want this to appear in the output, but the autosummary should still generate the pages.
+      .. autosummary::
+         :toctree:
+      {% for item in all_attributes %}
+         {%- if not item.startswith('_') %}
+         {{ name }}.{{ item }}
+         {%- endif -%}
+      {%- endfor %}
+  {% endif %}
+  {% endblock %}

doc/conf.py.in

@@ -6,7 +6,7 @@ import sys
 sys.path.insert(0, "@CMAKE_CURRENT_SOURCE_DIR@/sphinxext")
 
 # exclude these folders from scanning by sphinx
-exclude_patterns = ['_templates']
+exclude_patterns = ['_templates', 'doxygen']
 
 extensions = ['sphinx.ext.autodoc',
               'sphinx.ext.mathjax',
@@ -38,11 +38,14 @@ myst_enable_extensions = [
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
-source_suffix = '.rst'
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.md': 'markdown',
+}
 
 # Turn on sphinx.ext.autosummary
 autosummary_generate = True
-autosummary_imported_members=False
+autosummary_imported_members = False
 
 project = '@PROJECT_NAME@'
 version = '@PROJECT_VERSION@'
@@ -99,10 +102,9 @@ plot_html_show_formats = False
 
 intersphinx_mapping = {'python': ('https://docs.python.org/3.11', None), 'triqslibs': ('https://triqs.github.io/triqs/latest', None)}
 
-# numpydoc options
-numpydoc_show_class_members = False
-numpydoc_show_inherited_class_members = False
-numpydoc_class_members_toctree = False
+# configure numpydoc if enabled
+numpydoc_attributes_as_param_list = False
+
 
 # open links in new tab instead of same window
 from sphinx.writers.html import HTMLTranslator
@@ -139,10 +141,112 @@ class PatchedHTMLTranslator(HTMLTranslator):
         if 'target' in node:
             atts['target'] = node['target']
         self.body.append(self.starttag(node, 'a', '', **atts))
- 
+
         if node.get('secnumber'):
             self.body.append(('%s' + self.secnumber_suffix) %
                              '.'.join(map(str, node['secnumber'])))
 
+
+# process doc strings for better rst/html output
+import re
+
+# regular expressions for docstring parsing
+_autosummary_re = re.compile(r'^\s*\.\.\s+autosummary::', re.M)
+_dispatched_desc_re = re.compile(r'^\s*(?:\[([^\]]*)\]\s*)?([^\n]*)')
+
+
+def mark_autosummary_sources(app, docname, source):
+    """
+    Sphinx hook to mark rst files that contain an autosummary directive.
+
+    This is needed in the processing hook to identify files with autosummary
+    directives. 
+
+    Parameters
+    ----------
+    app : Sphinx application object
+        The Sphinx application instance.
+    docname : str
+        The name of the document being processed.
+    source : list of str
+        The source content of the document.
+    """
+    text = source[0]
+    marks = getattr(app.env, "_docs_with_autosummary", set())
+    if _autosummary_re.search(text):
+        marks.add(docname)
+    app.env._docs_with_autosummary = marks
+
+
+def process_docstring(app, what, name, obj, options, lines):
+    """
+    Process doc string lines for autosummary tables.
+
+    Note: For functions, any changes to the doc string are not reflected in the actual documentation page.
+    For classes, this is not the case!
+
+    Parameters
+    ----------
+    app : Sphinx application object
+        The Sphinx application instance.
+    what : str
+        The type of the object being documented (e.g., 'function', 'class').
+    name : str
+        The fully qualified name of the object.
+    obj : object
+        The object being documented.
+    options : object
+        The options given to the directive.
+    lines : list of str
+        The lines of the doc string to process.
+    """
+    if not lines:
+        return
+
+    # process doc string only for autosummary tables
+    docname = app.env.temp_data.get('docname') or getattr(app.env, 'docname', None)
+    if docname in getattr(app.env, "_docs_with_autosummary", set()):
+        # find the first line which is not empty, not whitespace-only and not intended
+        first_idx = next((i for i, s in enumerate(lines) if s and s.strip() and s == s.lstrip()), None)
+
+        # if no such line is found, do nothing (what else could we do?)
+        first_line = lines[first_idx] if first_idx is not None else None
+        if not first_line:
+            return
+
+        # handle wrapped classes with no description
+        if first_line == 'Dispatched C++ constructor(s).' or first_line == 'Synthesized constructor with the following keyword arguments:':
+            # somehow this not only changes the table but also the actual documentation page
+            lines.insert(0, 'Wrapped C++ class.')
+            lines.insert(1, '')
+            return
+
+        # handle dispatched functions
+        if first_line == 'Dispatched C++ function(s).':
+            # try to find a doc string
+            doc_str = ''
+            for i in range(first_idx + 3, len(lines)):
+                if lines[i].strip() and lines[i] == lines[i].lstrip():
+                    doc_str = lines[i].strip()
+                    break
+
+            # empty doc string, use "Dispatched C++ function(s)."
+            if doc_str == '..':
+                return
+
+            # try to match "[...] str_desc"
+            match = _dispatched_desc_re.match(doc_str)
+
+            # we only care about lines[0] since autosummary uses it for the function table
+            lines[0] = match.group(2) if match.group(1) else doc_str 
+            lines[1] = ''
+
+
 def setup(app):
     app.set_translator('html', PatchedHTMLTranslator)
+
+    # use process_docstring to modify docstrings
+    app.connect("source-read", mark_autosummary_sources)
+    app.connect('autodoc-process-docstring', process_docstring, priority=1000)
+
+    return {'version': '1.0'}

doc/documentation.rst

@@ -13,10 +13,7 @@ Documentation
 C++ reference manual
 ====================
 
-.. toctree::
-   :maxdepth: 5
-
-   cpp2rst_generated/contents
+The C++ reference manual can be found `here <./doxygen/index.html>`_.
 
 Python reference manual
 =======================

doc/doxygen/CMakeLists.txt

@@ -0,0 +1,35 @@
+# ############
+# Doxygen
+find_package(Doxygen REQUIRED)
+
+# Configure Doxyfile
+configure_file(${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile @ONLY)
+
+# Configure markdown files
+configure_file(${CMAKE_CURRENT_SOURCE_DIR}/overview.md.in ${CMAKE_CURRENT_BINARY_DIR}/overview.md @ONLY)
+
+# Fetch doxygen-awesome-css
+include(FetchContent)
+FetchContent_Declare(doxyawesome
+  GIT_REPOSITORY https://github.com/jothepro/doxygen-awesome-css.git
+  GIT_TAG v2.3.2)
+FetchContent_MakeAvailable(doxyawesome)
+file(COPY ${doxyawesome_SOURCE_DIR}/doxygen-awesome.css DESTINATION ${CMAKE_CURRENT_BINARY_DIR})
+file(COPY ${doxyawesome_SOURCE_DIR}/doxygen-awesome-sidebar-only.css DESTINATION ${CMAKE_CURRENT_BINARY_DIR})
+
+# Add custom target for Doxygen
+add_custom_target(doxygen ALL
+  COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
+  WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+  COMMENT "Generating Doxygen documentation"
+  VERBATIM
+)
+
+# copy doxygen/html output folder to sphinx/html folder
+add_custom_command(TARGET doxygen POST_BUILD 
+  COMMAND "${CMAKE_COMMAND}" -E make_directory 
+         "${CMAKE_CURRENT_BINARY_DIR}/../html/doxygen"
+  COMMAND "${CMAKE_COMMAND}" -E copy_directory
+     "${CMAKE_CURRENT_BINARY_DIR}/html"
+     "${CMAKE_CURRENT_BINARY_DIR}/../html/doxygen" 
+  COMMENT "Copying doxygen output to sphinx/html/doxygen directory")