📝 Document FCP-INDI/C-PAC#1919 (👔 Use filtered movement parameters to…

… calculate FD-J) (#306)

docs/_sources/autodoc_nodeblock.py

@@ -0,0 +1,69 @@
+from typing import TYPE_CHECKING, Any
+from CPAC.pipeline.nodeblock import NodeBlockFunction
+from docutils.statemachine import StringList
+from sphinx.ext.autodoc import Documenter, FunctionDocumenter, bool_option
+
+
+class NBFMixin(Documenter):
+    def add_directive_header(self, sig: str) -> None:
+        """Prepend "NodeBlockFunction" to the name & add the directive
+        header and options to the generated content."""
+        domain = getattr(self, 'domain', 'py')
+        directive = getattr(self, 'directivetype', self.objtype)
+        name = self.format_name()
+        sourcename = self.get_sourcename()
+
+        # Prepend NodeBlockFunction pseudoheader
+        self.add_line(f'*NodeBlockFunction*: **{self.object.name}**',
+                      sourcename)
+        self.add_line('', sourcename)
+        # one signature per line, indented by column
+        prefix = f'.. {domain}:{directive}:: '
+        for i, sig_line in enumerate(sig.split("\n")):
+            self.add_line(f'{prefix}{name}{sig_line}',
+                          sourcename)
+            if i == 0:
+                prefix = " " * len(prefix)
+
+        if self.options.no_index or self.options.noindex:
+            self.add_line('   :no-index:', sourcename)
+        if self.objpath:
+            # Be explicit about the module, this is necessary since .. class::
+            # etc. don't support a prepended module name
+            self.add_line('   :module: %s' % self.modname, sourcename)
+
+
+class NodeBlockFunctionDocumenter(NBFMixin, FunctionDocumenter):
+    """Sphinx Documenter for NodeBlockFunction"""
+    objtype = 'NodeBlockFunction'
+    directivetype = FunctionDocumenter.objtype
+    priority = 10 + FunctionDocumenter.priority
+    option_spec = dict(FunctionDocumenter.option_spec)
+    option_spec['hex'] = bool_option
+
+    @classmethod
+    def can_document_member(cls, member: Any, membername: str, isattr: bool,
+                            parent: Any) -> bool:
+        """Determine if a member is a NodeBlockFunction"""
+        return isinstance(member, NodeBlockFunction)
+
+    def add_content(self,
+                    more_content: StringList | None
+                    ) -> None:
+
+        super().add_content(more_content)
+
+        source_name = self.get_sourcename()
+        # nbf_object: NodeBlockFunction = self.object
+        self.add_line('', source_name)
+
+
+
+def setup(app: 'Sphinx') -> dict[str, Any]:
+    app.setup_extension('sphinx.ext.autodoc')  # Require autodoc extension
+    app.add_autodocumenter(NodeBlockFunctionDocumenter)
+    return {
+        'version': '0.1',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }

docs/_sources/conf.py

@@ -15,14 +15,17 @@
 import os
 import re
 import sys
+from typing import Any
 
 from dateutil import parser as dparser
 from CPAC import __version__
+from CPAC.pipeline.nodeblock import NodeBlockFunction
 from CPAC.utils.monitoring import custom_logging
 from github import Github
 from github.GithubException import RateLimitExceededException, \
     UnknownObjectException
 import m2r
+from nipype import __version__ as _nipype_version
 import semver
 from pybtex.plugin import register_plugin
 
@@ -36,6 +39,18 @@
 # https://python-semver.readthedocs.io/en/latest/usage.html
 
 
+# class DocumentNodeBlockFunction(FunctionDocumenter):
+#     """Document Node Block Functions"""
+#     objtype = 'Function'
+#     priority = 10
+
+#     @classmethod
+#     def can_document_member(cls, member: Any, membername: str, isattr: bool,
+#                             parent: Any) -> bool:
+#         """Determine if a member is a NodeBlockFunction"""
+#         return isinstance(member, NodeBlockFunction)
+
+
 def coerce(version):
     """
     Convert an incomplete version string into a semver-compatible VersionInfo
@@ -148,13 +163,20 @@ def yaml_to_rst(path):
     'sphinx.ext.napoleon',
     'sphinx.ext.viewcode',
     'sphinxcontrib.programoutput',
+    'autodoc_nodeblock',
     'exec',
     'nbsphinx']
 
 bibtex_bibfiles = [f'references/{bib}' for bib in os.listdir('references') if
                    bib.endswith('.bib')]
 bibtex_default_style = 'cpac_docs_style'
 
+intersphinx_mapping = {
+    'nipype': (f'https://nipype.readthedocs.io/en/{_nipype_version}/', None),
+    'python': ('https://docs.python.org/3', None)}
+
+napoleon_preprocess_types = True
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -629,4 +651,5 @@ def initialize_factory() -> None:
 
 def setup(app) -> None:
     """Extend Sphinx"""
+    # modify docstrings before parsing RST
     app.connect('autodoc-process-docstring', autodoc_process_docstring)

docs/_sources/developer/index.rst

@@ -24,6 +24,7 @@ Contents:
    workflow_documentation
    workflows/index
    xcpqc
+   utils
    testing
    continuous_integration
    deprecating

docs/_sources/developer/pipeline.rst

@@ -1,4 +1,11 @@
 Pipeline Development
 ====================
 
-.. include:: /developer/schema.rst
+.. include:: /developer/schema.rst
+
+Pipeline Utilities
+^^^^^^^^^^^^^^^^^^
+
+.. automodule:: CPAC.pipeline.utils
+    :members:
+    :undoc-members:

docs/_sources/developer/utils.rst

@@ -0,0 +1,235 @@
+Utilities
+=========
+
+BIDS Utilities
+^^^^^^^^^^^^^^
+
+.. automodule:: CPAC.utils.bids_utils
+    :members:
+    :undoc-members:
+
+BIDS Data Configuration
+^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: CPAC.utils.bids_data_config
+    :members:
+    :undoc-members:
+
+Configuration
+^^^^^^^^^^^^^
+
+.. automodule:: CPAC.utils.configuration
+    :members:
+    :undoc-members:
+
+Create FMRIB's Local Analysis of Mixed Effects (FLAME) Model Files
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: CPAC.utils.create_flame_model_files
+    :members:
+    :undoc-members:
+
+Create FSL FLAME Preset
+^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: CPAC.utils.create_fsl_flame_preset
+    :members:
+    :undoc-members:
+
+Create FSL create_fsl_model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: CPAC.utils.create_fsl_model
+    :members:
+    :undoc-members:
+
+Create Group Analysis Info Files
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: CPAC.utils.create_group_analysis_info_files
+    :members:
+    :undoc-members:
+
+Datasource
+^^^^^^^^^^
+
+.. automodule:: CPAC.utils.datasource
+    :members:
+    :undoc-members:
+
+Datatypes
+^^^^^^^^^
+
+.. automodule:: CPAC.utils.datatypes
+    :members:
+    :undoc-members:
+
+Documentation
+^^^^^^^^^^^^^
+
+.. automodule:: CPAC.utils.docs
+    :members:
+    :undoc-members:
+
+Extract Data
+^^^^^^^^^^^^
+
+.. automodule:: CPAC.utils.extract_data
+    :members:
+    :undoc-members:
+
+Extract Data (Multiscan)
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: CPAC.utils.extract_data_multiscan
+    :members:
+    :undoc-members:
+
+Extract Parameters
+^^^^^^^^^^^^^^^^^^
+
+.. automodule:: CPAC.utils.extract_parameters
+    :members:
+    :undoc-members:
+
+Google Analytics
+^^^^^^^^^^^^^^^^
+
+.. automodule:: CPAC.utils.ga
+    :members:
+    :undoc-members:
+
+Interfaces
+^^^^^^^^^^
+
+Function Interfaces
+-------------------
+
+.. automodule:: CPAC.utils.interfaces.function
+    :members:
+    :undoc-members:
+
+Tests
+-----
+
+.. automodule:: CPAC.utils.interfaces.tests
+    :members:
+    :undoc-members:
+
+Miscellaneous
+^^^^^^^^^^^^^
+
+.. automodule:: CPAC.utils.misc
+    :members:
+    :undoc-members:
+
+Monitoring
+^^^^^^^^^^
+
+.. automodule:: CPAC.utils.monitoring
+    :members:
+    :undoc-members:
+
+NeuroData's MRI to Graphs (NDMG | m2g) Utilities
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: CPAC.utils.ndmg_utils
+    :members:
+    :undoc-members:
+
+Neuroimaging Informatics Technology Initiative (NIfTI) Utilities
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: CPAC.utils.nifti_utils
+    :members:
+    :undoc-members:
+
+Outputs
+^^^^^^^
+
+.. automodule:: CPAC.utils.outputs
+    :members:
+    :undoc-members:
+
+pytest
+^^^^^^
+
+.. automodule:: CPAC.utils.pytest
+    :members:
+    :undoc-members:
+
+Serialization
+^^^^^^^^^^^^^
+
+.. automodule:: CPAC.utils.serialization
+    :members:
+    :undoc-members:
+
+Strategy
+^^^^^^^^
+
+.. automodule:: CPAC.utils.strategy
+    :members:
+    :undoc-members:
+
+Symlinks
+^^^^^^^^
+
+.. automodule:: CPAC.utils.symlinks
+    :members:
+    :undoc-members:
+
+Test Initialization
+^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: CPAC.utils.test_init
+    :members:
+    :undoc-members:
+
+Test Mocks
+^^^^^^^^^^
+
+.. automodule:: CPAC.utils.test_mocks
+    :members:
+    :undoc-members:
+
+Test Resources
+^^^^^^^^^^^^^^
+
+.. automodule:: CPAC.utils.test_resources
+    :members:
+    :undoc-members:
+
+Tests
+^^^^^
+
+.. automodule:: CPAC.utils.tests
+    :members:
+    :undoc-members:
+
+The Trimmer
+^^^^^^^^^^^
+
+.. automodule:: CPAC.utils.trimmer
+    :members:
+    :undoc-members:
+
+Typing
+^^^^^^
+
+.. automodule:: CPAC.utils.typing
+    :members:
+    :undoc-members:
+
+Utilities
+^^^^^^^^^
+
+.. automodule:: CPAC.utils.utils
+    :members:
+    :undoc-members:
+
+Versioning
+^^^^^^^^^^
+.. automodule:: CPAC.utils.versioning
+    :members:
+    :undoc-members: