🔀 Merge docs/profiler into docs/nested-config

Author: shnizzedy

docs/_sources/conf.py

@@ -391,7 +391,7 @@ def _unireplace(release_note, unireplace):
 # default_role = None
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
-# add_function_parentheses = True
+add_function_parentheses = False
 
 # If true, the current module name will be prepended to all description
 # unit titles (such as .. function::).

docs/_sources/developer/index.rst

@@ -3,6 +3,8 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
+.. title:: Developer Documentation
+
 Welcome to CPAC's developer documentation!
 ==========================================
 
@@ -12,6 +14,7 @@ Contents:
    :maxdepth: 2
 
    installation
+   nodes
    workflow_documentation
    workflows/index
    testing

docs/_sources/developer/nodes.rst

@@ -0,0 +1,45 @@
+*****
+Nodes
+*****
+
+.. _mem_gb:
+
+.. _n_procs:
+
+.. _n_cpus:
+
+.. warning::
+   A Nipype :py:class:`~nipype.pipeline.engine.nodes.Node` has an initialization parameter ``mem_gb`` that differs from the :doc:`commandline option </user/run/help>` ``--mem_gb``. While the commandline option is **a limit**, the Node initialization parameter is **an estimate** of the most memory that Node will consume when run. The Node parameter is not a limit; rather, this value is used to allocate system resources at runtime.
+   
+   Conversely, the commandline option ``--n_cpus`` is **a limit** and the Node initialization parameter ``n_procs`` is **also a limit** of the maximum number of threads a Node will be permmitted to consume.
+   
+   C-PAC automatically creates a JSON-like file called ``callback.log`` (via the function :py:func:`~CPAC.utils.monitoring.log_nodes_cb`) when running. This file includes for each Node:
+
+      * estimated memory,
+      * memory usage observed at runtime,
+      * specified maximum number of threads per Node, and
+      * threads used at runtime.
+   
+   The Nipype utility function :py:func:`~nipype.utils.draw_gantt_chart.log_to_dict` reads a log file generated by ``log_nodes_cb`` to a Python dictionary. 
+   
+   When a developer creates or modifies a Node in C-PAC, a ``mem_gb`` and ``n_procs`` argument should be provided unless the respective defaults of 0.2 and None (number of available system cores) are expected to be sufficient. When testing, the ``mem_gb`` and ``n_procs`` arguments should be adjusted if the observed memory and/or thread usage of a Node exceeds the estimate.
+ 
+
+.. autoclass:: CPAC.pipeline.nipype_pipeline_engine.Node
+   :special-members: __init__
+   :members:
+   :inherited-members:
+
+.. autoclass:: CPAC.pipeline.nipype_pipeline_engine.MapNode
+   :special-members: __init__
+   :members:
+   :inherited-members:
+
+.. autofunction:: CPAC.utils.monitoring.log_nodes_cb
+
+draw_gantt_chart
+================
+
+.. automodule:: CPAC.utils.monitoring.draw_gantt_chart
+   :members: resource_report, log_to_dict, generate_gantt_chart, resource_overusage_report
+   :inherited-members:

docs/_sources/index.rst

@@ -11,8 +11,8 @@ Contents:
 .. toctree::
    :maxdepth: 1
 
-   User Guide<user/index>
-   Developer Documentation<developer/index>
+   User Guide <user/index>
+   Developer Documentation <developer/index>
 
 
 Indices and tables