From de33e0228915ec1a1148c5c3bc4697a3fd1cd503 Mon Sep 17 00:00:00 2001 From: Jon Clucas Date: Thu, 18 Jul 2024 09:55:01 -0400 Subject: [PATCH 1/7] :memo: Document ":recycle: Split `ResourcePool` into three classes" --- docs/_sources/developer/pipeline.rst | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/_sources/developer/pipeline.rst b/docs/_sources/developer/pipeline.rst index 850d26aa9..9836c7fdb 100644 --- a/docs/_sources/developer/pipeline.rst +++ b/docs/_sources/developer/pipeline.rst @@ -3,6 +3,23 @@ Pipeline Development .. include:: /developer/schema.rst +Engine +^^^^^^ + +NodeBlock +--------- + +.. automodule:: CPAC.pipeline.engine.nodeblock + :members: + :undoc-members: + +Resource +-------- + +.. automodule:: CPAC.pipeline.engine.resource + :members: + :undoc-members: + Pipeline Utilities ^^^^^^^^^^^^^^^^^^ From bf377e7843b66256c1cdaa889f53291f3fd27191 Mon Sep 17 00:00:00 2001 From: Jon Clucas Date: Thu, 18 Jul 2024 10:42:53 -0400 Subject: [PATCH 2/7] :alien: Update nodeblock module location --- docs/_sources/autodoc_nodeblock.py | 2 +- docs/_sources/conf.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/_sources/autodoc_nodeblock.py b/docs/_sources/autodoc_nodeblock.py index cc91d5098..adf20d1b3 100644 --- a/docs/_sources/autodoc_nodeblock.py +++ b/docs/_sources/autodoc_nodeblock.py @@ -1,5 +1,5 @@ from typing import TYPE_CHECKING, Any -from CPAC.pipeline.nodeblock import NodeBlockFunction +from CPAC.pipeline.engine.nodeblock import NodeBlockFunction from docutils.statemachine import StringList from sphinx.ext.autodoc import Documenter, FunctionDocumenter, bool_option diff --git a/docs/_sources/conf.py b/docs/_sources/conf.py index ba3e2d7b4..b9f912175 100644 --- a/docs/_sources/conf.py +++ b/docs/_sources/conf.py @@ -19,7 +19,7 @@ from dateutil import parser as dparser from CPAC import __version__ -from CPAC.pipeline.nodeblock import NodeBlockFunction +from CPAC.pipeline.engine.nodeblock import NodeBlockFunction from CPAC.utils.monitoring import custom_logging from github import Github from github.GithubException import RateLimitExceededException, \ From 4d06c2946ed0d37ad5aa6ea4369cedac7dafc28d Mon Sep 17 00:00:00 2001 From: Jon Clucas Date: Thu, 18 Jul 2024 11:02:26 -0400 Subject: [PATCH 3/7] :art: Adjust heading level for schema --- docs/_sources/developer/schema.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/_sources/developer/schema.rst b/docs/_sources/developer/schema.rst index 1c0557977..1faad9334 100644 --- a/docs/_sources/developer/schema.rst +++ b/docs/_sources/developer/schema.rst @@ -1,8 +1,7 @@ .. _validation_schema: -***************** Validation Schema -***************** +^^^^^^^^^^^^^^^^^ C-PAC uses `voluptuous `_ to validate pipeline configurations against defined types and value restrictions. Default values should be set in :doc:`the default pipeline ` along with comments explaining each option. From ab036ec29fc88023c31cc5a166162c534d1e0e8a Mon Sep 17 00:00:00 2001 From: Jon Clucas Date: Thu, 18 Jul 2024 12:42:29 -0400 Subject: [PATCH 4/7] :wrench: Update config for formatting engine docs --- docs/_sources/conf.py | 10 ++++++++++ docs/_sources/developer/pipeline.rst | 4 ++++ 2 files changed, 14 insertions(+) diff --git a/docs/_sources/conf.py b/docs/_sources/conf.py index b9f912175..342e2ea9a 100644 --- a/docs/_sources/conf.py +++ b/docs/_sources/conf.py @@ -169,6 +169,12 @@ def yaml_to_rst(path): 'exec', 'nbsphinx'] +add_module_names = False +maximum_signature_line_length = 90 + +autodoc_typehints = "both" +autodoc_typehints_format = "short" + bibtex_bibfiles = [f'references/{bib}' for bib in os.listdir('references') if bib.endswith('.bib')] bibtex_default_style = 'cpac_docs_style' @@ -179,7 +185,11 @@ def yaml_to_rst(path): issues_github_path = 'FCP-INDI/C-PAC' +napoleon_attr_annotations = True +napoleon_include_private_with_doc = True napoleon_preprocess_types = True +napoleon_use_admonition_for_notes = True + # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/docs/_sources/developer/pipeline.rst b/docs/_sources/developer/pipeline.rst index 9836c7fdb..69fdf970e 100644 --- a/docs/_sources/developer/pipeline.rst +++ b/docs/_sources/developer/pipeline.rst @@ -11,6 +11,8 @@ NodeBlock .. automodule:: CPAC.pipeline.engine.nodeblock :members: + :special-members: + :private-members: :undoc-members: Resource @@ -18,6 +20,8 @@ Resource .. automodule:: CPAC.pipeline.engine.resource :members: + :special-members: + :private-members: :undoc-members: Pipeline Utilities From d1aaf686f0e4907ddd4ce79fc78bd5653218403a Mon Sep 17 00:00:00 2001 From: Jon Clucas Date: Thu, 18 Jul 2024 12:44:17 -0400 Subject: [PATCH 5/7] :memo: Add engine tests to engine docs --- docs/_sources/developer/pipeline.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/_sources/developer/pipeline.rst b/docs/_sources/developer/pipeline.rst index 69fdf970e..2ec72c160 100644 --- a/docs/_sources/developer/pipeline.rst +++ b/docs/_sources/developer/pipeline.rst @@ -24,6 +24,15 @@ Resource :private-members: :undoc-members: +Tests +----- + +.. automodule:: CPAC.pipeline.test.test_engine + :members: + :special-members: + :private-members: + :undoc-members: + Pipeline Utilities ^^^^^^^^^^^^^^^^^^ From 93e0c4e8734a2f0ba2d2181de08478b874610940 Mon Sep 17 00:00:00 2001 From: Jon Clucas Date: Thu, 18 Jul 2024 14:39:49 -0400 Subject: [PATCH 6/7] :art: More formatting for ResourcePool refactor --- docs/_sources/_templates/layout.html | 6 +++++- docs/_sources/conf.py | 1 + docs/_sources/developer/logging.rst | 1 - docs/_sources/developer/nodes.rst | 5 ----- docs/_sources/developer/pipeline.rst | 7 ++++--- docs/_sources/developer/workflows/network_centrality.rst | 3 --- 6 files changed, 10 insertions(+), 13 deletions(-) diff --git a/docs/_sources/_templates/layout.html b/docs/_sources/_templates/layout.html index d3feb2edc..da38154dc 100644 --- a/docs/_sources/_templates/layout.html +++ b/docs/_sources/_templates/layout.html @@ -1,5 +1,9 @@ {% extends "!layout.html" %} - +{%- block scripts %} + {{ super() }} + + +{%- endblock %} {% block footer %} {{ super() }} diff --git a/docs/_sources/conf.py b/docs/_sources/conf.py index 342e2ea9a..6b8e99e36 100644 --- a/docs/_sources/conf.py +++ b/docs/_sources/conf.py @@ -172,6 +172,7 @@ def yaml_to_rst(path): add_module_names = False maximum_signature_line_length = 90 +autoclass_content = "both" autodoc_typehints = "both" autodoc_typehints_format = "short" diff --git a/docs/_sources/developer/logging.rst b/docs/_sources/developer/logging.rst index acea66843..fca5feb7d 100644 --- a/docs/_sources/developer/logging.rst +++ b/docs/_sources/developer/logging.rst @@ -26,7 +26,6 @@ A ``CPAC.utils.monitoring.custom_logging.MockLogger`` can be used in place of a .. autofunction:: CPAC.utils.monitoring.custom_logging.getLogger .. autoclass:: CPAC.utils.monitoring.custom_logging.MockLogger - :special-members: __init__ :members: :inherited-members: diff --git a/docs/_sources/developer/nodes.rst b/docs/_sources/developer/nodes.rst index 3744ec920..e11e5a4fd 100644 --- a/docs/_sources/developer/nodes.rst +++ b/docs/_sources/developer/nodes.rst @@ -30,17 +30,14 @@ For nodes that will use a varying amount of memory depending on the node's input .. 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: .. autoclass:: nipype.interfaces.base.core.Interface - :special-members: __init__ :members: :inherited-members: @@ -50,12 +47,10 @@ For nodes that will use a varying amount of memory depending on the node's input .. autoclass:: CPAC.utils.interfaces.function.Function - :special-members: __init__ :members: :inherited-members: .. autoclass:: CPAC.pipeline.nipype_pipeline_engine.Workflow - :special-members: __init__ :members: :inherited-members: diff --git a/docs/_sources/developer/pipeline.rst b/docs/_sources/developer/pipeline.rst index 2ec72c160..077eca26f 100644 --- a/docs/_sources/developer/pipeline.rst +++ b/docs/_sources/developer/pipeline.rst @@ -11,7 +11,7 @@ NodeBlock .. automodule:: CPAC.pipeline.engine.nodeblock :members: - :special-members: + :inherited-members: :private-members: :undoc-members: @@ -20,7 +20,7 @@ Resource .. automodule:: CPAC.pipeline.engine.resource :members: - :special-members: + :inherited-members: :private-members: :undoc-members: @@ -29,7 +29,7 @@ Tests .. automodule:: CPAC.pipeline.test.test_engine :members: - :special-members: + :inherited-members: :private-members: :undoc-members: @@ -38,4 +38,5 @@ Pipeline Utilities .. automodule:: CPAC.pipeline.utils :members: + :inherited-members: :undoc-members: diff --git a/docs/_sources/developer/workflows/network_centrality.rst b/docs/_sources/developer/workflows/network_centrality.rst index e4edd5fad..80620ce8a 100644 --- a/docs/_sources/developer/workflows/network_centrality.rst +++ b/docs/_sources/developer/workflows/network_centrality.rst @@ -2,19 +2,16 @@ Network Centrality ================== .. automodule:: CPAC.network_centrality.network_centrality - :special-members: __init__ :members: :private-members: :undoc-members: .. automodule:: CPAC.network_centrality.pipeline - :special-members: __init__ :members: :private-members: :undoc-members: .. automodule:: CPAC.network_centrality.utils - :special-members: __init__ :members: :private-members: :undoc-members: From f66e9611e8ba0dee1e102eda81cb40f11d91317f Mon Sep 17 00:00:00 2001 From: Jon Clucas Date: Thu, 18 Jul 2024 21:03:02 -0400 Subject: [PATCH 7/7] :heavy_plus_sign: Install Pytest to autodocument tests --- requirements.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/requirements.txt b/requirements.txt index 77b5010eb..d892e303e 100644 --- a/requirements.txt +++ b/requirements.txt @@ -8,6 +8,7 @@ m2r mistune==0.8.4 nbsphinx PyGithub +pytest sphinx==7.3.2 sphinx-basic-ng>=1.0.0.beta2 sphinxcontrib-bibtex==2.5.0