diff --git a/docs/_sources/autodoc_nodeblock.py b/docs/_sources/autodoc_nodeblock.py new file mode 100644 index 000000000..cc91d5098 --- /dev/null +++ b/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, + } diff --git a/docs/_sources/conf.py b/docs/_sources/conf.py index 75710ce84..ae5f222fb 100644 --- a/docs/_sources/conf.py +++ b/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,6 +163,7 @@ def yaml_to_rst(path): 'sphinx.ext.napoleon', 'sphinx.ext.viewcode', 'sphinxcontrib.programoutput', + 'autodoc_nodeblock', 'exec', 'nbsphinx'] @@ -155,6 +171,12 @@ def yaml_to_rst(path): 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) diff --git a/docs/_sources/developer/index.rst b/docs/_sources/developer/index.rst index e9a1a2799..934f25de4 100644 --- a/docs/_sources/developer/index.rst +++ b/docs/_sources/developer/index.rst @@ -24,6 +24,7 @@ Contents: workflow_documentation workflows/index xcpqc + utils testing continuous_integration deprecating diff --git a/docs/_sources/developer/pipeline.rst b/docs/_sources/developer/pipeline.rst index c4a8ff172..850d26aa9 100644 --- a/docs/_sources/developer/pipeline.rst +++ b/docs/_sources/developer/pipeline.rst @@ -1,4 +1,11 @@ Pipeline Development ==================== -.. include:: /developer/schema.rst \ No newline at end of file +.. include:: /developer/schema.rst + +Pipeline Utilities +^^^^^^^^^^^^^^^^^^ + +.. automodule:: CPAC.pipeline.utils + :members: + :undoc-members: diff --git a/docs/_sources/developer/utils.rst b/docs/_sources/developer/utils.rst new file mode 100644 index 000000000..ee6bf514f --- /dev/null +++ b/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: diff --git a/docs/_sources/developer/workflows/func_preproc.rst b/docs/_sources/developer/workflows/func_preproc.rst index 2999555ae..fa864aed1 100644 --- a/docs/_sources/developer/workflows/func_preproc.rst +++ b/docs/_sources/developer/workflows/func_preproc.rst @@ -1,5 +1,30 @@ Functional Preprocessing ======================== -.. automodule:: CPAC.func_preproc +Ingress +^^^^^^^ + +.. automodule:: CPAC.func_preproc.func_ingress + :members: + :undoc-members: + +Motion +^^^^^^ + +.. automodule:: CPAC.func_preproc.func_motion + :members: + :undoc-members: + +Preprocessing +^^^^^^^^^^^^^ + +.. automodule:: CPAC.func_preproc.func_preproc + :members: + :undoc-members: + +Utilities +^^^^^^^^^ + +.. automodule:: CPAC.func_preproc.utils :members: + :undoc-members: diff --git a/requirements.txt b/requirements.txt index fc431a00c..76b15ea63 100644 --- a/requirements.txt +++ b/requirements.txt @@ -8,8 +8,8 @@ m2r mistune==0.8.4 nbsphinx PyGithub -sphinx==4.2 -sphinxcontrib-bibtex==2.4.2 +sphinx==7.1.2 +sphinxcontrib-bibtex==2.5.0 sphinxcontrib-programoutput semver torch