DaVinci API documentation

Phys/DaVinci/python/DaVinci/config.py

@@ -8,7 +8,8 @@
 # granted to it by virtue of its status as an Intergovernmental Organization  #
 # or submit itself to any jurisdiction.                                       #
 ###############################################################################
-"""DaVinci configured using PyConf components.
+"""
+DaVinci configured using PyConf components.
 """
 
 from __future__ import absolute_import
@@ -59,32 +60,38 @@ def davinci_control_flow(options, user_analysis_nodes=[], fsr_nodes=[]):
     """
     DaVinci control flow is split in a few sections as described in DaVinci/issue#2 (then simplified)
 
+    .. code-block:: text
+
        DaVinci (LAZY_AND)
-       *-- LuminosityNode (NONLAZY_OR)
-       |   *-- EventAccounting/EventAccount
-       *-- UserAnalysisNode (NONLAZY_OR)
-           +-- DVUser1Node (LAZY_AND)
-           |   *-- PVFilter
-           |   *-- ParticlesFilter
-           |   *-- Candidate1Combiner
-           |   *-- AlgorithmsForTuple1
-           |   *-- Tuple1
-           +-- DVUser2Node (LAZY_AND)
-               *-- PVFilter
-               *-- ParticlesFilter
-               *-- Candidate2Combiner
-               *-- AlgorithmsForTuple2
-               *-- Tuple2
+       ├── LuminosityNode (NONLAZY_OR)
+       │   └── EventAccounting/EventAccount
+       └── UserAnalysisNode (NONLAZY_OR)
+           ├── DVUser1Node (LAZY_AND)
+           │   ├── PVFilter
+           │   ├── ParticlesFilter
+           │   ├── Candidate1Combiner
+           │   ├── AlgorithmsForTuple1
+           │   ├── Tuple1
+           └── DVUser2Node (LAZY_AND)
+               ├── PVFilter
+               ├── ParticlesFilter
+               ├── Candidate2Combiner
+               ├── AlgorithmsForTuple2
+               └── Tuple2
 
     The main parts are
-        . LuminosityNode
-        . UserAnalysisNode
+
+        * LuminosityNode
+        * UserAnalysisNode
+
     who are in AND among each other and can accomodate nodes (defined with the class DVNode)
     in OR among themselves.
 
     To prepare the control flow there are a few options:
+    
         1. take a dictionary as input where all the nodes are listed in their categories
         2. take a various lists as input each related to a specific category of nodes
+    
     This function is then used to fill the control flow
     """
     options.finalize()
@@ -114,10 +121,14 @@ def davinci_control_flow(options, user_analysis_nodes=[], fsr_nodes=[]):
 def prepare_davinci_nodes(user_algs):
     """
     This helper function takes as input a dictionary of user algorithms in the form
-    {
+
+    .. code-block:: python
+    
+        {
         'DVNode1' : [<list of algs>],
         'DVNode2' : [<list of algs>],
-    }
+        }
+    
     and creates the node to send to `davinci_control_flow`.
     """
     dv_nodes = []

doc/conf.py

@@ -48,12 +48,18 @@ extensions = [
     "sphinx.ext.todo",
     "graphviz_linked",
     "sphinxcontrib.autodoc_pydantic",
+    "autoapi.extension",
 ]
 
 # Control the display of the DaVinci.Options object
 autodoc_pydantic_model_show_json = True
 autodoc_pydantic_settings_show_json = False
 
+autoapi_dirs = ['../Phys/DaVinci/python/DaVinci']
+autoapi_add_toctree_entry = False
+autoapi_generate_api_docs = True
+autoapi_keep_files = True  # useful to check for errors and warnings
+
 # Assume unmarked references (in backticks) refer to Python objects
 default_role = "py:obj"
 

doc/davinci/api_index.rst

-
-DaVinci
-=======
-
-.. toctree::
-
-    options
-

doc/davinci/options.rst

@@ -4,17 +4,21 @@ Options YAML
 The YAML provided to populate the ``options`` object passed to the user provided function, often called ``options.yaml``, is parsed using the following model:
 
 .. autopydantic_model:: DaVinci.Options
+   :noindex:
    :inherited-members: BaseModel
    :model-show-field-summary: False
 
 .. autoclass:: GaudiConf.LbExec.options.DataTypeEnum
+   :noindex:
    :members:
    :undoc-members:
 
 .. autoclass:: GaudiConf.LbExec.options.FileFormats
+   :noindex:
    :members:
    :undoc-members:
 
 .. autoclass:: GaudiConf.LbExec.options.EventStores
+   :noindex:
    :members:
    :undoc-members:

doc/index.rst

@@ -42,6 +42,11 @@ and Turbo output.
    :caption: API Reference
    :maxdepth: 3
 
+   autoapi/DaVinci/index
+   davinci/options
+   framework/pyconf
+   
+.. 
    davinci/api_index
    framework/pyconf
 

doc/requirements.txt

@@ -5,3 +5,4 @@ sphinx==4.4.0
 sphinx_rtd_theme==1.0.0
 gitpython
 autodoc_pydantic==1.6.2
+sphinx-autoapi

doc/tutorials/running.rst

@@ -50,6 +50,7 @@ Also make a file named ``options.yaml`` containing:
 
 
 .. code-block:: yaml
+    
     input_files:
     - root://eoslhcb.cern.ch//eos/lhcb/wg/dpa/wp3/tests/hlt2_passthrough_thor_lines.dst
     annsvc_config: root://eoslhcb.cern.ch//eos/lhcb/wg/dpa/wp3/tests/hlt2_passthrough_thor_lines.tck.json