From 037ba3bbd075ad2fe019421f4ec0d0878bcd021f Mon Sep 17 00:00:00 2001 From: Jon Clucas Date: Mon, 7 Aug 2023 11:58:58 -0400 Subject: [PATCH 01/13] :alien: Update some automodules for FCP-INDI/C-PAC#1919 --- docs/_sources/developer/index.rst | 1 + docs/_sources/developer/utils.rst | 5 +++++ 2 files changed, 6 insertions(+) create mode 100644 docs/_sources/developer/utils.rst 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/utils.rst b/docs/_sources/developer/utils.rst new file mode 100644 index 000000000..9a0ee6b7a --- /dev/null +++ b/docs/_sources/developer/utils.rst @@ -0,0 +1,5 @@ +Utilities +========= + +.. automodule:: CPAC.utils + :members: From 193adc2479cd6fc8a7e6905360a45a5a201339bc Mon Sep 17 00:00:00 2001 From: Jon Clucas Date: Mon, 7 Aug 2023 14:03:38 -0400 Subject: [PATCH 02/13] =?UTF-8?q?:construction=5Fworker:=20Upgrade=20Circl?= =?UTF-8?q?eCI's=20Python=20version=20(3.7=20=E2=86=92=203.10)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .circleci/config.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index 99a29969a..8767ec485 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -115,7 +115,7 @@ jobs: build-nightly: working_directory: /home/circleci/build docker: - - image: cimg/python:3.7 + - image: cimg/python:3.10 steps: - checkout: path: /home/circleci/build @@ -131,7 +131,7 @@ jobs: build-version: working_directory: /home/circleci/build docker: - - image: cimg/python:3.7 + - image: cimg/python:3.10 steps: - checkout: path: /home/circleci/build @@ -148,7 +148,7 @@ jobs: deploy-nightly: working_directory: /home/circleci/ docker: - - image: cimg/python:3.7 + - image: cimg/python:3.10 steps: - attach_workspace: at: /home/circleci/ @@ -157,7 +157,7 @@ jobs: deploy-version: working_directory: /home/circleci/ docker: - - image: cimg/python:3.7 + - image: cimg/python:3.10 steps: - attach_workspace: at: /home/circleci/ From 7f5aef50a4db383717d40df60615b64c9d60f529 Mon Sep 17 00:00:00 2001 From: Jon Clucas Date: Mon, 7 Aug 2023 19:02:55 -0400 Subject: [PATCH 03/13] :arrow_up: Upgrade cpac (wrapper)@aa73ce2 --- .circleci/config.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index 8767ec485..57da55037 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -33,7 +33,7 @@ commands: cd /home/circleci/build python -m venv ~/simple source ~/simple/bin/activate - pip install git+https://github.com/FCP-INDI/cpac.git@cabac8b820075876cfc28966071306b9314c139e semver + pip install git+https://github.com/FCP-INDI/cpac.git@aa73ce266d3e599b6d9a1ad9721959c69dd0c4d3 semver deactivate run-cpac-commands: From 946f13214b72f71b21a8013042adb32043bc0032 Mon Sep 17 00:00:00 2001 From: Jon Clucas Date: Mon, 7 Aug 2023 19:14:11 -0400 Subject: [PATCH 04/13] :arrow_up: Upgrade `sphinx` and `sphinxcontrib-bibtex` @7.1.2 & 2.5.0, respectively --- requirements.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/requirements.txt b/requirements.txt index 3c6e7311e..76b15ea63 100644 --- a/requirements.txt +++ b/requirements.txt @@ -8,8 +8,8 @@ m2r mistune==0.8.4 nbsphinx PyGithub -sphinx==4.0 -sphinxcontrib-bibtex==2.4.2 +sphinx==7.1.2 +sphinxcontrib-bibtex==2.5.0 sphinxcontrib-programoutput semver torch From a798ad821fd7c9637d75f6789a2c9bf99cdccd39 Mon Sep 17 00:00:00 2001 From: Jon Clucas Date: Mon, 7 Aug 2023 20:16:59 -0400 Subject: [PATCH 05/13] :loud_sound: Get more specific with some `automodule`s --- docs/_sources/developer/utils.rst | 95 ++++++++++++++++++- .../developer/workflows/func_preproc.rst | 6 +- 2 files changed, 99 insertions(+), 2 deletions(-) diff --git a/docs/_sources/developer/utils.rst b/docs/_sources/developer/utils.rst index 9a0ee6b7a..3360da889 100644 --- a/docs/_sources/developer/utils.rst +++ b/docs/_sources/developer/utils.rst @@ -1,5 +1,98 @@ Utilities ========= -.. automodule:: CPAC.utils +.. automodule:: CPAC.utils.bids_utils + :members: + +.. automodule:: CPAC.utils.bids_data_config + :members: + +.. automodule:: CPAC.utils.configuration + :members: + +.. automodule:: CPAC.utils.create_flame_model_files + :members: + +.. automodule:: CPAC.utils.create_fsl_flame_preset + :members: + +.. automodule:: CPAC.utils.create_fsl_model + :members: + +.. automodule:: CPAC.utils.create_group_analysis_info_files + :members: + +.. automodule:: CPAC.utils.datasource + :members: + +.. automodule:: CPAC.utils.datatypes + :members: + +.. automodule:: CPAC.utils.docs + :members: + +.. automodule:: CPAC.utils.extract_data + :members: + +.. automodule:: CPAC.utils.extract_data_multiscan + :members: + +.. automodule:: CPAC.utils.extract_parameters + :members: + +.. automodule:: CPAC.utils.ga + :members: + +.. automodule:: CPAC.utils.interfaces + :members: + +.. automodule:: CPAC.utils.misc + :members: + +.. automodule:: CPAC.utils.monitoring + :members: + +.. automodule:: CPAC.utils.ndmg_utils + :members: + +.. automodule:: CPAC.utils.nifti_utils + :members: + +.. automodule:: CPAC.utils.outputs + :members: + +.. automodule:: CPAC.utils.pytest + :members: + +.. automodule:: CPAC.utils.serialization + :members: + +.. automodule:: CPAC.utils.strategy + :members: + +.. automodule:: CPAC.utils.symlinks + :members: + +.. automodule:: CPAC.utils.test_init + :members: + +.. automodule:: CPAC.utils.test_mocks + :members: + +.. automodule:: CPAC.utils.test_resources + :members: + +.. automodule:: CPAC.utils.tests + :members: + +.. automodule:: CPAC.utils.trimmer + :members: + +.. automodule:: CPAC.utils.typing + :members: + +.. automodule:: CPAC.utils.utils + :members: + +.. automodule:: CPAC.utils.versioning :members: diff --git a/docs/_sources/developer/workflows/func_preproc.rst b/docs/_sources/developer/workflows/func_preproc.rst index 2999555ae..843988ab7 100644 --- a/docs/_sources/developer/workflows/func_preproc.rst +++ b/docs/_sources/developer/workflows/func_preproc.rst @@ -1,5 +1,9 @@ Functional Preprocessing ======================== -.. automodule:: CPAC.func_preproc +.. automodule:: CPAC.func_preproc.func_motion :members: + +.. automodule:: CPAC.func_preproc.func_preproc + :members: + From 3e68d022fc84211dd74c6ca8df72b524388ac0d4 Mon Sep 17 00:00:00 2001 From: Jon Clucas Date: Tue, 8 Aug 2023 15:28:06 -0400 Subject: [PATCH 06/13] :tractor: Add submodule headers --- docs/_sources/developer/utils.rst | 106 +++++++++++++++++- .../developer/workflows/func_preproc.rst | 17 +++ 2 files changed, 122 insertions(+), 1 deletion(-) diff --git a/docs/_sources/developer/utils.rst b/docs/_sources/developer/utils.rst index 3360da889..d248ed9bb 100644 --- a/docs/_sources/developer/utils.rst +++ b/docs/_sources/developer/utils.rst @@ -1,98 +1,202 @@ Utilities ========= +BIDS Utilities +^^^^^^^^^^^^^^ + .. automodule:: CPAC.utils.bids_utils :members: +BIDS Data Configuration +^^^^^^^^^^^^^^^^^^^^^^^ + .. automodule:: CPAC.utils.bids_data_config :members: +Configuration +^^^^^^^^^^^^^ + .. automodule:: CPAC.utils.configuration :members: +Create FMRIB's Local Analysis of Mixed Effects (FLAME) Model Files +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + .. automodule:: CPAC.utils.create_flame_model_files :members: +Create FSL FLAME Preset +^^^^^^^^^^^^^^^^^^^^^^^ + .. automodule:: CPAC.utils.create_fsl_flame_preset :members: +Create FSL create_fsl_model +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + .. automodule:: CPAC.utils.create_fsl_model :members: +Create Group Analysis Info Files +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + .. automodule:: CPAC.utils.create_group_analysis_info_files :members: +Datasource +^^^^^^^^^^ + .. automodule:: CPAC.utils.datasource :members: +Datatypes +^^^^^^^^^ + .. automodule:: CPAC.utils.datatypes :members: +Documentation +^^^^^^^^^^^^^ + .. automodule:: CPAC.utils.docs :members: +Extract Data +^^^^^^^^^^^^ + .. automodule:: CPAC.utils.extract_data :members: +Extract Data (Multiscan) +^^^^^^^^^^^^^^^^^^^^^^^^ + .. automodule:: CPAC.utils.extract_data_multiscan :members: +Extract Parameters +^^^^^^^^^^^^^^^^^^ + .. automodule:: CPAC.utils.extract_parameters :members: +Google Analytics +^^^^^^^^^^^^^^^^ + .. automodule:: CPAC.utils.ga :members: -.. automodule:: CPAC.utils.interfaces +Interfaces +^^^^^^^^^^ + +Function Interfaces +------------------- + +.. automodule:: CPAC.utils.interfaces.function + :members: + +Tests +----- + +.. automodule:: CPAC.utils.interfaces.tests :members: +Miscellaneous +^^^^^^^^^^^^^ + .. automodule:: CPAC.utils.misc :members: +Monitoring +^^^^^^^^^^ + .. automodule:: CPAC.utils.monitoring :members: +NeuroData's MRI to Graphs (NDMG | m2g) Utilities +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + .. automodule:: CPAC.utils.ndmg_utils :members: +Neuroimaging Informatics Technology Initiative (NIfTI) Utilities +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + .. automodule:: CPAC.utils.nifti_utils :members: +Outputs +^^^^^^^ + .. automodule:: CPAC.utils.outputs :members: +pytest +^^^^^^ + .. automodule:: CPAC.utils.pytest :members: +Serialization +^^^^^^^^^^^^^ + .. automodule:: CPAC.utils.serialization :members: +Strategy +^^^^^^^^ + .. automodule:: CPAC.utils.strategy :members: +Symlinks +^^^^^^^^ + .. automodule:: CPAC.utils.symlinks :members: +Test Initialization +^^^^^^^^^^^^^^^^^^^ + .. automodule:: CPAC.utils.test_init :members: +Test Mocks +^^^^^^^^^^ + .. automodule:: CPAC.utils.test_mocks :members: +Test Resources +^^^^^^^^^^^^^^ + .. automodule:: CPAC.utils.test_resources :members: +Tests +^^^^^ + .. automodule:: CPAC.utils.tests :members: +The Trimmer +^^^^^^^^^^^ + .. automodule:: CPAC.utils.trimmer :members: +Typing +^^^^^^ + .. automodule:: CPAC.utils.typing :members: +Utilities +^^^^^^^^^ + .. automodule:: CPAC.utils.utils :members: +Versioning +^^^^^^^^^^ .. automodule:: CPAC.utils.versioning :members: diff --git a/docs/_sources/developer/workflows/func_preproc.rst b/docs/_sources/developer/workflows/func_preproc.rst index 843988ab7..03f07b0e2 100644 --- a/docs/_sources/developer/workflows/func_preproc.rst +++ b/docs/_sources/developer/workflows/func_preproc.rst @@ -1,9 +1,26 @@ Functional Preprocessing ======================== +Ingress +^^^^^^^ + +.. automodule:: CPAC.func_preproc.func_ingress + :members: + +Motion +^^^^^^ + .. automodule:: CPAC.func_preproc.func_motion :members: +Preprocessing +^^^^^^^^^^^^^ + .. automodule:: CPAC.func_preproc.func_preproc :members: +Utilities +^^^^^^^^^ + +.. automodule:: CPAC.func_preproc.utils + :members: From 1c696faaead42d585bf97692d1157af21c56ad0a Mon Sep 17 00:00:00 2001 From: Jon Clucas Date: Wed, 9 Aug 2023 09:05:35 -0400 Subject: [PATCH 07/13] :memo: Include undocumented functions in dev doc --- docs/_sources/developer/utils.rst | 33 +++++++++++++++++++ .../developer/workflows/func_preproc.rst | 4 +++ 2 files changed, 37 insertions(+) diff --git a/docs/_sources/developer/utils.rst b/docs/_sources/developer/utils.rst index d248ed9bb..ee6bf514f 100644 --- a/docs/_sources/developer/utils.rst +++ b/docs/_sources/developer/utils.rst @@ -6,84 +6,98 @@ 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 ^^^^^^^^^^ @@ -93,110 +107,129 @@ 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 03f07b0e2..fa864aed1 100644 --- a/docs/_sources/developer/workflows/func_preproc.rst +++ b/docs/_sources/developer/workflows/func_preproc.rst @@ -6,21 +6,25 @@ 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: From aa4376de4ea0d57a57160d582b610a021e66f2f2 Mon Sep 17 00:00:00 2001 From: Jon Clucas Date: Tue, 15 Aug 2023 08:54:32 -0400 Subject: [PATCH 08/13] :memo: Autodoc `CPAC.pipeline.utils` --- docs/_sources/developer/pipeline.rst | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) 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: From adb74ff094f217c476851e98f012de2fa8ed937a Mon Sep 17 00:00:00 2001 From: Jon Clucas Date: Tue, 15 Aug 2023 22:08:40 -0400 Subject: [PATCH 09/13] :necktie: Document NodeBlockFunctions as functions --- docs/_sources/conf.py | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/docs/_sources/conf.py b/docs/_sources/conf.py index 0dce401ef..b407f8001 100644 --- a/docs/_sources/conf.py +++ b/docs/_sources/conf.py @@ -15,15 +15,18 @@ 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 import semver +from sphinx.ext.autodoc import FunctionDocumenter from pybtex.plugin import register_plugin sys.path.append(os.path.dirname(__file__)) @@ -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 @@ -628,4 +643,8 @@ def initialize_factory() -> None: def setup(app) -> None: """Extend Sphinx""" - app.connect('autodoc-process-docstring', autodoc_process_docstring) + # Node Block Function customizations + app.setup_extension('sphinx.directives') + app.add_autodocumenter(DocumentNodeBlockFunction) + # modify docstrings before parsing RST + app.connect('autodoc-process-docstring', autodoc_process_docstring) \ No newline at end of file From ef862aa35f39a1f3dd9868fa3372c92284ebc01b Mon Sep 17 00:00:00 2001 From: Jon Clucas Date: Wed, 16 Aug 2023 10:13:07 -0400 Subject: [PATCH 10/13] :necktie: Handle NodeBlockFunctions as their own type of object --- docs/_sources/autodoc_nodeblock.py | 46 ++++++++++++++++++++++++++++++ docs/_sources/conf.py | 23 ++++++++------- 2 files changed, 58 insertions(+), 11 deletions(-) create mode 100644 docs/_sources/autodoc_nodeblock.py diff --git a/docs/_sources/autodoc_nodeblock.py b/docs/_sources/autodoc_nodeblock.py new file mode 100644 index 000000000..a706380af --- /dev/null +++ b/docs/_sources/autodoc_nodeblock.py @@ -0,0 +1,46 @@ +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 format_name(self) -> str: + """Prepend "NodeBlockFunction" to the name""" + return f'NodeBlockFunction: {super().format_name()}' + + +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 b407f8001..121dde430 100644 --- a/docs/_sources/conf.py +++ b/docs/_sources/conf.py @@ -39,16 +39,16 @@ # https://python-semver.readthedocs.io/en/latest/usage.html -class DocumentNodeBlockFunction(FunctionDocumenter): - """Document Node Block Functions""" - objtype = 'Function' - priority = 10 +# 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) +# @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): @@ -163,6 +163,7 @@ def yaml_to_rst(path): 'sphinx.ext.napoleon', 'sphinx.ext.viewcode', 'sphinxcontrib.programoutput', + 'autodoc_nodeblock', 'exec', 'nbsphinx'] @@ -644,7 +645,7 @@ def initialize_factory() -> None: def setup(app) -> None: """Extend Sphinx""" # Node Block Function customizations - app.setup_extension('sphinx.directives') - app.add_autodocumenter(DocumentNodeBlockFunction) + # app.setup_extension('sphinx.directives') + # app.add_autodocumenter(DocumentNodeBlockFunction) # modify docstrings before parsing RST app.connect('autodoc-process-docstring', autodoc_process_docstring) \ No newline at end of file From c25a9fa9a4b182318d858c85dee9827b53bd563c Mon Sep 17 00:00:00 2001 From: Jon Clucas Date: Wed, 16 Aug 2023 16:28:37 -0400 Subject: [PATCH 11/13] :art: Set intersphinx and napoleon options --- docs/_sources/conf.py | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/_sources/conf.py b/docs/_sources/conf.py index 121dde430..260477f46 100644 --- a/docs/_sources/conf.py +++ b/docs/_sources/conf.py @@ -25,8 +25,8 @@ from github.GithubException import RateLimitExceededException, \ UnknownObjectException import m2r +from nipype import __version__ as _nipype_version import semver -from sphinx.ext.autodoc import FunctionDocumenter from pybtex.plugin import register_plugin sys.path.append(os.path.dirname(__file__)) @@ -171,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'] From 39ad79b37ebbeb40901caff450391262f6d60812 Mon Sep 17 00:00:00 2001 From: Jon Clucas Date: Wed, 16 Aug 2023 16:33:28 -0400 Subject: [PATCH 12/13] :art: Restore final newline --- docs/_sources/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/_sources/conf.py b/docs/_sources/conf.py index 260477f46..5cc2a495c 100644 --- a/docs/_sources/conf.py +++ b/docs/_sources/conf.py @@ -654,4 +654,4 @@ def setup(app) -> None: # app.setup_extension('sphinx.directives') # app.add_autodocumenter(DocumentNodeBlockFunction) # modify docstrings before parsing RST - app.connect('autodoc-process-docstring', autodoc_process_docstring) \ No newline at end of file + app.connect('autodoc-process-docstring', autodoc_process_docstring) From 847f814784e0f82f9c5944e3cdbdb1f36390b4a7 Mon Sep 17 00:00:00 2001 From: Jon Clucas Date: Wed, 16 Aug 2023 17:30:35 -0400 Subject: [PATCH 13/13] :art: Prepend NodeBlockFunction to the name of NodeBlockFunctions --- docs/_sources/autodoc_nodeblock.py | 29 ++++++++++++++++++++++++++--- docs/_sources/conf.py | 3 --- 2 files changed, 26 insertions(+), 6 deletions(-) diff --git a/docs/_sources/autodoc_nodeblock.py b/docs/_sources/autodoc_nodeblock.py index a706380af..cc91d5098 100644 --- a/docs/_sources/autodoc_nodeblock.py +++ b/docs/_sources/autodoc_nodeblock.py @@ -5,9 +5,32 @@ class NBFMixin(Documenter): - def format_name(self) -> str: - """Prepend "NodeBlockFunction" to the name""" - return f'NodeBlockFunction: {super().format_name()}' + 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): diff --git a/docs/_sources/conf.py b/docs/_sources/conf.py index 5cc2a495c..b0b142281 100644 --- a/docs/_sources/conf.py +++ b/docs/_sources/conf.py @@ -650,8 +650,5 @@ def initialize_factory() -> None: def setup(app) -> None: """Extend Sphinx""" - # Node Block Function customizations - # app.setup_extension('sphinx.directives') - # app.add_autodocumenter(DocumentNodeBlockFunction) # modify docstrings before parsing RST app.connect('autodoc-process-docstring', autodoc_process_docstring)