From 0e553b55a3f6b27a18ca5dad69a3ebe08f92dc67 Mon Sep 17 00:00:00 2001 From: Tom Close Date: Tue, 26 Mar 2024 14:39:21 +1100 Subject: [PATCH] updated docs with aramis-style --- .github/workflows/ci-cd.yaml | 46 +++++++++ README.md | 184 +++++++++++++++++++++++++++++++++++ README.rst | 154 ----------------------------- docs/conf.py | 51 ---------- docs/index.rst | 15 --- docs/source/api.rst | 7 ++ docs/source/conf.py | 26 +++++ docs/source/index.rst | 24 +++++ pyproject.toml | 3 +- 9 files changed, 289 insertions(+), 221 deletions(-) create mode 100644 README.md delete mode 100644 README.rst delete mode 100644 docs/conf.py delete mode 100644 docs/index.rst create mode 100644 docs/source/api.rst create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.rst diff --git a/.github/workflows/ci-cd.yaml b/.github/workflows/ci-cd.yaml index 055fc5c..c43e4e6 100644 --- a/.github/workflows/ci-cd.yaml +++ b/.github/workflows/ci-cd.yaml @@ -20,6 +20,11 @@ env: # Define environment variables ANTS_VERSION: v2.5.1 ANTS_INSTALL_PATH: /opt/ants +permissions: + contents: read + pages: write + id-token: write + jobs: nipype-conv: @@ -310,6 +315,47 @@ jobs: draft: false prerelease: false + # docs: + # needs: deploy + # environment: + # name: github-pages + # url: ${{ steps.deployment.outputs.page_url }} + # runs-on: ubuntu-latest + # steps: + # - uses: actions/checkout@v4 + # - uses: actions/setup-python@v5 + # with: + # python-version: '3.x' + + # - name: Download tasks converted from Nipype + # uses: actions/download-artifact@v4 + # with: + # name: converted-nipype + # path: pydra/tasks/freesurfer/auto + + # - name: Install dependencies + # run: python -m pip install related-packages/fileformats .[doc] + + # - name: Build docs + # run: | + # pushd docs + # make html + # popd + + # - name: Upload artifact + # uses: actions/upload-pages-artifact@v3 + # with: + # path: 'docs/build/html' + + # - name: Setup GitHub Pages + # if: github.event_name == 'release' || github.event_name == 'repository_dispatch' + # uses: actions/configure-pages@v4 + + # - name: Deploy to GitHub Pages + # if: github.event_name == 'release' || github.event_name == 'repository_dispatch' + # id: deployment + # uses: actions/deploy-pages@v4 + # Deploy on tags if PYPI_API_TOKEN is defined in the repository secrets. # Secrets are not accessible in the if: condition [0], so set an output variable [1] # [0] https://github.community/t/16928 diff --git a/README.md b/README.md new file mode 100644 index 0000000..c8d257f --- /dev/null +++ b/README.md @@ -0,0 +1,184 @@ +# pydra-ants + +[![PyPI - Version][pypi-version]][pypi-project] +[![PyPI - Python Version][pypi-pyversions]][pypi-project] +[![PyPI - Downloads][pypi-downloads]][pypi-project] +[![Status-docs][status-docs-badge]][status-docs-link] +[![Status-CICD][status-cicd-badge]][status-cicd-link] + +---- + + +Pydra tasks for ANTs + +[Pydra][pydra] is a dataflow engine which provides +a set of lightweight abstractions for DAG +construction, manipulation, and distributed execution. + +[ANTs][ants] is a toolbox for multi-variate image registration, +segmentation and statistical analysis. + +**Table of Contents** + +- [Available Tasks](#available-tasks) +- [Installation](#installation) +- [Development](#development) +- [License](#license) + +## Available Tasks + +- ApplyTransforms +- CreateJacobianDeterminantImage +- N4BiasFieldCorrection +- Registration, registration_syn, registration_syn_quick + +## Installation + +```console +pip install pydra-ants +``` + +A separate installation of ANTs is required to use this package. + +An official conda package is available through conda-forge: + +```console +conda install -c conda-forge ants +``` + +## Automatic Conversion + +Automatically generated tasks can be found in the `pydra.tasks.ants.auto` sub-package. +These interfaces should be treated with caution as they likely do not pass testing. +Generated tasks that have been edited and pass testing will be imported into one or more of the +`pydra.tasks.ants.v*` sub-packages (e.g. `pydra.tasks.ants.v7_4`) corresponding +to the version of the ants toolkit they are designed for. + + +### Continuous integration + +This template uses [GitHub Actions](https://docs.github.com/en/actions/) to run tests and +deploy packages to PYPI. New packages are built and uploaded when releases are created on +GitHub, or new releases of Nipype or the Nipype2Pydra conversion tool are released. +Releases triggered by updates to Nipype or Nipype2Pydra are signified by the `postN` +suffix where `N = ` with the '.'s stripped, e.g. +`v0.2.3post185010` corresponds to the v0.2.3 tag of this repository with auto-generated +packages from Nipype 1.8.5 using Nipype2Pydra 0.1.0. + +## Development + +### Methodology + +The development of this package is expected to have two phases + +1. Where the corresponding Nipype interfaces are considered to be the ground truth, and + the Pydra tasks are generated from them +2. When the Pydra tasks are considered be mature and they are edited by hand + +Different tasks will probably mature at different times so there will probably be an +intermediate phase between 1 and 2. + +### Developer installation + +First install the requirements for running the auto-conversion script and generate the +Pydra task interfaces from their Nipype counterparts + +```console +pip install -r nipype-auto-conv/requirements.txt +``` + +The run the conversion script to convert Nipype interfaces to Pydra + +```console +nipype-auto-conv/generate +``` + +Install repo in developer mode from the source directory and install pre-commit to +ensure consistent code-style and quality. + +```console +pip install -e .[test,dev] +pre-commit install +``` + +### Auto-conversion phase + +The auto-converted Pydra tasks are generated from their corresponding Nipype interface +in combination with "conversion hints" contained in YAML specs +located in `nipype-auto-conv/specs/`. The self-documented conversion specs are +to be edited by hand in order to assist the auto-converter produce valid pydra tasks. +After editing one or more conversion specs the `pydra.tasks.ants.auto` package should +be regenerated by running + +```console +nipype-auto-conv/generate +``` + +The tests should be run on the auto-generated tasks to see if they are valid + +```console +pytest pydra/tasks/ants/auto/tests/test_.py +``` + +If the test passes you should then edit the `pydra/tasks/ants/v*/__init__.py` file +to import the auto-generated task interface to signify that it has been validated and is +ready for use, where v* corresponds to the version of ANTs that you have tested +it against e.g. + +```console +from pydra.tasks.ants.auto import +``` + +and copy the test file `pydra/tasks/ants/auto/tests/test_.py` +into `pydra/tasks/ants/v*/tests`. + + +### File-formats and sample test data + +The automatically generated tests will attempt to provided the task instance to be tested +with sensible default values based on the type of the field and any constraints it has +on it. However, these will often need to be manually overridden after consulting the +underlying tool's documentation. + +For file-based data, automatically generated file-system objects will be created for +selected format types, e.g. Nifti, Dicom. Therefore, it is important to specify the +format of the file using the "mime-like" string corresponding to a +[fileformats](https://github.com/ArcanaFramework/fileformats) class +in the `inputs > types` and `outputs > types` dicts of the YAML spec. + +If the required file-type is not found implemented within fileformats, please see the `fileformats` +docs [https://arcanaframework.github.io/fileformats/developer.html] for instructions on how to define +new fileformat types, and see +[fileformats-medimage-extras](https://github.com/ArcanaFramework/fileformats-medimage-extras/blob/6c2dabe91e95687eebc2639bb6f034cf9595ecfc/fileformats/extras/medimage/nifti.py#L30-L48) +for an example on how to implement methods to generate sample data for them. Implementations of +new fileformats that are specific to ANTs, and functions to +generate sample data for them, should be defined in `related-packages/fileformats` +and `related-packages/fileformats-extras`, respectively. + + + +## License + +This project is distributed under the terms of the [Apache License, Version 2.0][license]. + +[ants]: https://github.com/ANTsX/ANTs + +[license]: https://spdx.org/licenses/Apache-2.0.html + +[pydra]: https://pydra.readthedocs.io/ + +[pypi-downloads]: https://static.pepy.tech/badge/pydra-ants + +[pypi-project]: https://pypi.org/project/pydra-ants + +[pypi-pyversions]: https://img.shields.io/pypi/pyversions/pydra-ants.svg + +[pypi-version]: https://img.shields.io/pypi/v/pydra-ants.svg + +[status-docs-badge]: https://img.shields.io/badge/docs-latest-brightgreen.svg?style=flat + +[status-cicd-badge]: https://github.com/nipype/pydra-ants/actions/workflows/ci-cd.yaml/badge.svg + +[status-docs-link]: https://nipype.github.io/pydra-ants/ + +[status-cicd-link]: https://github.com/nipype/pydra-ants/actions/workflows/ci-cd.yaml diff --git a/README.rst b/README.rst deleted file mode 100644 index 7f81500..0000000 --- a/README.rst +++ /dev/null @@ -1,154 +0,0 @@ -=========================== -Pydra task package for ants -=========================== - -.. image:: https://github.com/nipype/pydra-ants/actions/workflows/ci-cd.yaml/badge.svg - :target: https://github.com/nipype/pydra-ants/actions/workflows/ci-cd.yaml -.. image:: https://codecov.io/gh/nipype/pydra-ants/branch/main/graph/badge.svg?token=UIS0OGPST7 - :target: https://codecov.io/gh/nipype/pydra-ants -.. image:: https://img.shields.io/pypi/pyversions/pydra-ants.svg - :target: https://pypi.python.org/pypi/pydra-ants/ - :alt: Supported Python versions -.. image:: https://img.shields.io/pypi/v/pydra-ants.svg - :target: https://pypi.python.org/pypi/pydra-ants/ - :alt: Latest Version - - -This package contains a collection of Pydra task interfaces for the ants toolkit. -The basis of this collection has been formed by the semi-automatic conversion of -existing `Nipype `__ interfaces to Pydra using the -`Nipype2Pydra `__ tool - - -Automatically-generated vs manually-curated tasks -------------------------------------------------- - -Automatically generated tasks can be found in the `pydra.tasks.ants.auto` package. -These packages should be treated with extreme caution as they likely do not pass testing. -Generated tasks that have been edited and pass testing are imported into one or more of the -`pydra.tasks.ants.v*` packages, corresponding to the version of the ants toolkit -they are designed for. - -Tests ------ - -This package comes with a battery of automatically generated test modules. To install -the necessary dependencies to run the tests - -.. code-block:: - - $ pip install -e .[test] - -Then the tests, including `doctests` `__, can be launched using - -.. code-block:: - - $ pytest --doctest-modules pydra/tasks/* - -By default, the tests are set to time-out after 10s, after which the underlying tool is -assumed to have passed the validation/initialisation phase and we assume that it will -run to completion. To disable this and run the test(s) through to completion run - -.. code-block:: - - $ pytest --doctest-modules --timeout-pass 0 pydra/tasks/* - -Continuous integration ----------------------- - -This template uses `GitHub Actions `__` to run tests and -deploy packages to PYPI. New packages are built and uploaded when releases are created on -GitHub, or new releases of Nipype or the Nipype2Pydra conversion tool are released. -Releases triggered by updates to Nipype or Nipype2Pydra are signified by the `postN` -suffix where `N = ` with the '.'s stripped, e.g. -`v0.2.3post185010` corresponds to the v0.2.3 tag of this repository with auto-generated -packages from Nipype 1.8.5 using Nipype2Pydra 0.1.0. - - -Contributing to this package ----------------------------- - -Developer installation -~~~~~~~~~~~~~~~~~~~~~~ - -Install repo in developer mode from the source directory and install pre-commit to -ensure consistent code-style and quality. - -.. code-block:: - - $ pip install -e .[test,dev] - $ pre-commit install - -Next install the requirements for running the auto-conversion script and generate the -Pydra task interfaces from their Nipype counterparts - -.. code-block:: - - $ pip install -r nipype-auto-conv/requirements.txt - -The run the conversion script to convert Nipype interfaces to Pydra - -.. code-block:: - - $ nipype-auto-conv/generate - -Methodology -~~~~~~~~~~~ - -The development of this package is expected to have two phases - -1. Where the corresponding Nipype interfaces are considered to be the ground truth, and - the Pydra tasks are generated from them -2. When the Pydra tasks are considered be mature and they are edited by hand - -Different tasks will probably mature at different times so there will probably be an -intermediate phase between 1 and 2. - -Auto-conversion phase -~~~~~~~~~~~~~~~~~~~~~ - -The auto-converted Pydra tasks are generated from their corresponding Nipype interface -in combination with "conversion hints" contained in YAML specs -located in `nipype-auto-conv/specs/`. The self-documented conversion specs are -to be edited by hand in order to assist the auto-converter produce valid pydra tasks. -After editing one or more conversion specs the `pydra.tasks.ants.auto` package should -be regenerated by running - -.. code-block:: - - $ nipype-auto-conv/generate - -The tests should be run on the auto-generated tasks to see if they are valid - -.. code-block:: - - $ pytest pydra/tasks/ants/auto/tests/test_.py - -If the test passes you should then edit the `pydra/tasks/ants/v/__init__.py` file -to import the now valid task interface to signify that it has been validated and is ready -for use, e.g. - -.. code-block::python - - from pydra.tasks.ants.auto import - - -Typing and sample test data -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The automatically generated tests will attempt to provided the task instance to be tested -with sensible default values based on the type of the field and any constraints it has -on it. However, these will often need to be manually overridden after consulting the -underlying tool's documentation. - -For file-based data, automatically generated file-system objects will be created for -selected format types, e.g. Nifti, Dicom. Therefore, it is important to specify the -format of the file using the "mime-like" string corresponding to a -`fileformats `__ class -in the ``inputs > types`` and ``outputs > types`` dicts of the YAML spec. - -If the required file-type is not found implemented within fileformats, please see the `fileformats -docs `__ for instructions on how to define -new fileformat types, and see -`fileformats-medimage-extras `__ -for an example on how to implement methods to generate sample data for them. diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index c3d62e6..0000000 --- a/docs/conf.py +++ /dev/null @@ -1,51 +0,0 @@ -# Configuration file for the Sphinx documentation builder. -# -# This file only contains a selection of the most common options. For a full -# list see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html - -# -- Path setup -------------------------------------------------------------- - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) - - -# -- Project information ----------------------------------------------------- - -project = "pydra-ants" -copyright = "2020, Xihe Xie" -author = "Xihe Xie" - - -# -- General configuration --------------------------------------------------- - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = [] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ["_templates"] - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path. -exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] - - -# -- Options for HTML output ------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = "alabaster" - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ["_static"] diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index ea4caee..0000000 --- a/docs/index.rst +++ /dev/null @@ -1,15 +0,0 @@ -Welcome to pydra-ants's documentation! -========================================= - -.. toctree:: - :maxdepth: 2 - :caption: Contents: - - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/docs/source/api.rst b/docs/source/api.rst new file mode 100644 index 0000000..52594e8 --- /dev/null +++ b/docs/source/api.rst @@ -0,0 +1,7 @@ +API +=== + +.. autosummary:: + :toctree: generated + +.. automodule:: pydra.tasks.freesurfer diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..ec3130f --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,26 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +from pydra.tasks.freesurfer import __version__ # noqa + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = "pydra-ants" +author = "Pydra Developers" +copyright = f"2022-2023, {author}" +release = __version__ + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = ["sphinx.ext.autosummary", "sphinx.ext.napoleon"] +templates_path = ["_templates"] +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = "pydata_sphinx_theme" diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..97c52a9 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,24 @@ +About pydra-ants +================ + +`Pydra`_ is a dataflow engine which provides a set of lightweight abstractions for DAG construction, manipulation, and distributed execution. + +`ANTs`_ is an open source package for the analysis and visualization of structural, functional, and diffusion neuroimaging data from cross-sectional and longitudinal studies. + +pydra-ants provides Pydra tasks for running and composing FreeSurfer commands. + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + api + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + +.. _Pydra: https://nipype.github.io/pydra/ +.. _ANTs: https://github.com/ANTsX/ANTs diff --git a/pyproject.toml b/pyproject.toml index 66583e5..6647bb4 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -5,7 +5,7 @@ build-backend = "hatchling.build" [project] name = "pydra-ants" description = "Pydra tasks package for ANTs" -readme = "README.rst" +readme = "README.md" requires-python = ">=3.8" keywords = ["ants", "neuroimaging", "pydra", "registration"] dependencies = [ @@ -52,6 +52,7 @@ doc = [ "sphinxcontrib-apidoc ~=0.3.0", "sphinxcontrib-napoleon", "sphinxcontrib-versioning", + "pydata-sphinx-theme >=0.13", ] test = [ "nipype2pydra",