From c25700f7cba4b720473f45adb55b6a7380065143 Mon Sep 17 00:00:00 2001 From: Jason Kai Date: Thu, 29 Jun 2023 14:53:52 -0400 Subject: [PATCH 1/3] init readthedocs - Set up configuration files - Set up autodoc to get io and transform modules - Add badge to documentation on README --- .readthedocs.yml | 29 +++++++++++ README.md | 2 + afids_utils/io.py | 10 +++- docs/Makefile | 20 +++++++ docs/api/main.md | 15 ++++++ docs/conf.py | 118 ++++++++++++++++++++++++++++++++++++++++++ docs/index.md | 10 ++++ docs/requirements.txt | 7 +++ 8 files changed, 210 insertions(+), 1 deletion(-) create mode 100644 .readthedocs.yml create mode 100644 docs/Makefile create mode 100644 docs/api/main.md create mode 100644 docs/conf.py create mode 100644 docs/index.md create mode 100644 docs/requirements.txt diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 00000000..369f110d --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,29 @@ +# .readthedocs.yml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Build documentation in the docs/ directory with Sphinx +sphinx: + configuration: docs/conf.py + +# Build documentation with MkDocs +#mkdocs: +# configuration: mkdocs.yml + +# Optionally build your docs in additional formats such as PDF +formats: + - pdf + +build: + os: 'ubuntu-20.04' + tools: + python: '3.10' + +python: + install: + - requirements: docs/requirements.txt + - method: pip + path: . diff --git a/README.md b/README.md index d5765fa3..a54f6d0a 100644 --- a/README.md +++ b/README.md @@ -1 +1,3 @@ # Anatomical Fiducials (AFIDs) Utility Tools + +[![Documentation Status](https://readthedocs.org/projects/afids-utils/badge/?version=latest)](https://afids-utils.readthedocs.io/en/latest/?badge=latest) \ No newline at end of file diff --git a/afids_utils/io.py b/afids_utils/io.py index 04234315..ad8ce0a2 100644 --- a/afids_utils/io.py +++ b/afids_utils/io.py @@ -32,7 +32,15 @@ def get_afid( fcsv_path: PathLike[str] | str, fid_num: int ) -> NDArray[np.single]: - """Extract specific fiducial's spatial coordinates""" + """ + Extract specific fiducial's spatial coordinates + + Returns + ------- + NDArray[np.single] + Floating-point array containing spatial coordinates (x, y, z) of single + AFID. + """ if fid_num < 1 or fid_num > 32: raise InvalidFiducialNumberError(fid_num) fcsv_df = pl.scan_csv( diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..41c270bb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/docs/api/main.md b/docs/api/main.md new file mode 100644 index 00000000..49e254dc --- /dev/null +++ b/docs/api/main.md @@ -0,0 +1,15 @@ +# API + +## afids_utils.io + +```{eval-rst} + .. automodule:: afids_utils.io + :members: +``` + +## afids_utils.transforms + +```{eval-rst} + .. automodule:: afids_utils.transforms + :members: +``` \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..0a76a7bc --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,118 @@ +# flake8: noqa +# 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 -------------------------------------------------------------- + +import datetime +import importlib.metadata as ilm + +# 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 = "AFIDs Utils" +copyright = f"{datetime.date.today().year}, Anatomical Fiducials" +author = "Anatomical Fiducials Contributors" + + +# -- 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 = [ + "sphinxarg.ext", + "sphinx.ext.intersphinx", + "sphinx.ext.napoleon", + "sphinx.ext.autodoc", + "sphinxcontrib.asciinema", + "myst_parser", + "sphinx_copybutton", + "sphinx_reredirects", + "sphinx_design", +] + + +myst_enable_extensions = [ + "attrs_block", +] +myst_enable_extensions = [ + "attrs_block", + "attrs_inline", + "tasklist", + "deflist", + "fieldlist", +] +myst_number_code_blocks = ["python", "yaml"] + + +napoleon_google_docstring = False +napoleon_numpy_docstring = True + +autodoc_member_order = "bysource" +autodoc_typehints = "description" +# autodoc_type_aliases = { +# "ZipList": "snakebids.types.ZipList", +# "ZipListLike": "snakebids.types.ZipListLike", +# "InputsConfig": "snakebids.types.InputsConfig", +# } +autodoc_typehints_format = "short" +autosummary_imported_members = True + + +# 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"] + + +master_doc = "index" + +intersphinx_mapping = { + "python": ("https://docs.python.org/3", None), +} + + +# -- 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 = "furo" +html_theme_options = { + "source_repository": "https://github.com/afids/afids-utils", + "source_branch": "main", + "source_directory": "docs/", +} + +# 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"] +# templates_path = ["_templates"] + +html_css_files = ["css/typealiases.css"] + +# redirects = { +# "migration/0.5_to_0.6.md": "migration/0.5_to_0.8.html", +# } + +# sphinxcontrib_asciinema_defaults = { +# "preload": 1, +# "rows": 24, +# "speed": 3, +# } diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..6257b3b3 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,10 @@ +```{include} ../README.md +``` + +```{toctree} +:caption: Reference +:hidden: +:maxdepth: 1 + +api/main +``` \ No newline at end of file diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..7b6e3e85 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,7 @@ +sphinx-argparse>=0.4.0,<0.5 +sphinxcontrib-asciinema>=0.3.7,<0.4 +myst-parser>=1.0.0,<2.0 +furo>=2023.3.23,<2024 +sphinx_copybutton>=0.5.1,<0.6 +sphinx-reredirects>=0.1,<0.2 +sphinx_design>=0.4.1,<0.5.0 \ No newline at end of file From 16f3eac2f0ef904b53d16068d143ffd99102fa6d Mon Sep 17 00:00:00 2001 From: Jason Kai Date: Thu, 29 Jun 2023 15:53:49 -0400 Subject: [PATCH 2/3] Update docstrings for readthedocs - Add numpydoc - Split submodule pages and add overview page - Update afids_utils.io - Update afids_utils.transforms --- .readthedocs.yml | 12 ++++------- afids_utils/io.py | 32 +++++++++++++++++++++++------ afids_utils/transforms.py | 20 +++++++++++++++++- docs/api/io.md | 6 ++++++ docs/api/{main.md => transform.md} | 9 -------- docs/conf.py | 25 ++++++++-------------- docs/general/main.md | 33 ++++++++++++++++++++++++++++++ docs/index.md | 15 ++++++++++++-- docs/requirements.txt | 10 ++++----- 9 files changed, 114 insertions(+), 48 deletions(-) create mode 100644 docs/api/io.md rename docs/api/{main.md => transform.md} (50%) create mode 100644 docs/general/main.md diff --git a/.readthedocs.yml b/.readthedocs.yml index 369f110d..8fa269db 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -1,27 +1,23 @@ +--- # .readthedocs.yml # Read the Docs configuration file # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details # Required version: 2 - # Build documentation in the docs/ directory with Sphinx sphinx: configuration: docs/conf.py - # Build documentation with MkDocs -#mkdocs: +# mkdocs: # configuration: mkdocs.yml # Optionally build your docs in additional formats such as PDF -formats: - - pdf - +formats: [pdf] build: - os: 'ubuntu-20.04' + os: ubuntu-20.04 tools: python: '3.10' - python: install: - requirements: docs/requirements.txt diff --git a/afids_utils/io.py b/afids_utils/io.py index ad8ce0a2..29781e14 100644 --- a/afids_utils/io.py +++ b/afids_utils/io.py @@ -1,4 +1,4 @@ -"""Methods for loading and saving nifti files""" +"""Methods for loading and saving files associated with AFIDs""" from __future__ import annotations import csv @@ -34,12 +34,20 @@ def get_afid( ) -> NDArray[np.single]: """ Extract specific fiducial's spatial coordinates - + + Parameters + ---------- + fcsv_path : os.PathLike[str] | str + Path to .fcsv file to extract AFID coordinates from + + fid_num : int + Unique fiducial number to extract from .fcsv file + Returns ------- - NDArray[np.single] - Floating-point array containing spatial coordinates (x, y, z) of single - AFID. + numpy.ndarray[shape=(3,), dtype=numpy.single] + NumPy array containing spatial coordinates (x, y, z) of single AFID + coordinate """ if fid_num < 1 or fid_num > 32: raise InvalidFiducialNumberError(fid_num) @@ -59,7 +67,19 @@ def afids_to_fcsv( afid_coords: NDArray[np.single], fcsv_output: PathLike[str] | str, ) -> None: - """AFIDS to Slicer-compatible .fcsv file""" + """ + Save AFIDS to Slicer-compatible .fcsv file + + Parameters + ---------- + afid_coords : numpy.ndarray[shape=(N, 3), dtype=numpy.single] + Floating-point NumPy array containing spatial coordinates (x, y, z) of + `N` AFIDs + + fcsv_output : os.PathLike[str] | str + Path of file (including filename and extension) to save AFIDs to + + """ # Read in fcsv template with resources.open_text( "afids_utils.resources", "template.fcsv" diff --git a/afids_utils/transforms.py b/afids_utils/transforms.py index b45d00c4..91e7d9e4 100644 --- a/afids_utils/transforms.py +++ b/afids_utils/transforms.py @@ -9,7 +9,25 @@ def afid_world2voxel( afid_world: NDArray[np.float_], nii_affine: NDArray[np.float_], ) -> NDArray[np.int_]: - """Transform fiducials in world coordinates to voxel coordinates""" + """ + Transform fiducials from world coordinates to voxel coordinates + + Parameters + ---------- + afid_world : numpy.ndarray[shape=(3,), dtype=numpy.float_] + NumPy array containing floating-point spatial coordinates (x, y, z) to + transform + + nii_affine : numpy.ndarray[shape=(4, 4), dtype=numpy.float_] + NumPy array containing affine transformation associated with + NifTI image + + Returns + ------- + numpy.ndarray[shape=(3,), dtype=numpy.float_] + NumPy array containing indices corresponding to voxel location along + spatial dimensions + """ # Translation afid_voxel = afid_world.T - nii_affine[:3, 3:4] diff --git a/docs/api/io.md b/docs/api/io.md new file mode 100644 index 00000000..f1344d0e --- /dev/null +++ b/docs/api/io.md @@ -0,0 +1,6 @@ +## afids_utils.io + +```{eval-rst} + .. automodule:: afids_utils.io + :members: +``` \ No newline at end of file diff --git a/docs/api/main.md b/docs/api/transform.md similarity index 50% rename from docs/api/main.md rename to docs/api/transform.md index 49e254dc..b7f280db 100644 --- a/docs/api/main.md +++ b/docs/api/transform.md @@ -1,12 +1,3 @@ -# API - -## afids_utils.io - -```{eval-rst} - .. automodule:: afids_utils.io - :members: -``` - ## afids_utils.transforms ```{eval-rst} diff --git a/docs/conf.py b/docs/conf.py index 0a76a7bc..1a5b573b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -22,6 +22,7 @@ # -- Project information ----------------------------------------------------- project = "AFIDs Utils" +release = ilm.version("afids_utils") copyright = f"{datetime.date.today().year}, Anatomical Fiducials" author = "Anatomical Fiducials Contributors" @@ -32,15 +33,15 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ + "sphinx_copybutton", + "sphinx_design", + "sphinx_reredirects", "sphinxarg.ext", + "sphinx.ext.autodoc", "sphinx.ext.intersphinx", "sphinx.ext.napoleon", - "sphinx.ext.autodoc", - "sphinxcontrib.asciinema", "myst_parser", - "sphinx_copybutton", - "sphinx_reredirects", - "sphinx_design", + "numpydoc", ] @@ -62,15 +63,10 @@ autodoc_member_order = "bysource" autodoc_typehints = "description" -# autodoc_type_aliases = { -# "ZipList": "snakebids.types.ZipList", -# "ZipListLike": "snakebids.types.ZipListLike", -# "InputsConfig": "snakebids.types.InputsConfig", -# } +# autodoc_type_aliases = {} autodoc_typehints_format = "short" autosummary_imported_members = True - # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] @@ -84,6 +80,7 @@ intersphinx_mapping = { "python": ("https://docs.python.org/3", None), + "numpy": ("https://numpy.org/doc/1.24", None), } @@ -110,9 +107,3 @@ # redirects = { # "migration/0.5_to_0.6.md": "migration/0.5_to_0.8.html", # } - -# sphinxcontrib_asciinema_defaults = { -# "preload": 1, -# "rows": 24, -# "speed": 3, -# } diff --git a/docs/general/main.md b/docs/general/main.md new file mode 100644 index 00000000..673e1a2f --- /dev/null +++ b/docs/general/main.md @@ -0,0 +1,33 @@ +# Overview + +The purpose of the `afids_utils` package is to provide commonly used utility +functions (written in Python) that is applicable to a various anatomical +fiducial (AFIDS) projects. The `afids_utils` documentation provides a +comprehensive reference guide designed to assist users and developers in +effectively utilizing the functionalities provided by the package's +application programming interface (API). It serves as a centralized resource +that offers detailed information about the various modules, classes, functions, +and constants available within the `afids_utils` package. + +Following the introduction, the API Reference pages provide a structured +organization of the package's modules and classes. Each module is described, explaining its role and the specific functionalities it offers. Detailed +information is provided for each class, including its methods, attributes, and +inheritance hierarchy, along with explanations of their purposes and usage. + +Additionally, the API page includes comprehensive documentation for the +functions and constants within the package. It describes the parameters +expected by each function, their data types, and their respective return +values. The documentation also highlights any optional parameters, default +values, and notable exceptions that may be raised. + +To assist developers in understanding and effectively utilizing the +`afids_utils` package, the API page may include code examples that +demonstrate the practical usage of the various modules, classes, functions, +and constants. These examples showcase common use cases, allowing developers +to grasp the concepts quickly and integrate them into their own projects. + +Furthermore, the API page may provide guidelines and best practices specific to +the `afids_utils` package. It may include recommendations on code structure, +error handling, performance optimization, and any other considerations that can +enhance the developer experience and ensure reliable and efficient usage of the +package. \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 6257b3b3..f8cdc82d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,9 +2,20 @@ ``` ```{toctree} -:caption: Reference +:caption: General +:name: general +:hidden: +:maxdepth: 2 + +general/main +``` + +```{toctree} +:caption: API Reference +:name: api_reference :hidden: :maxdepth: 1 -api/main +api/io +api/transform ``` \ No newline at end of file diff --git a/docs/requirements.txt b/docs/requirements.txt index 7b6e3e85..ba91c21c 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,7 +1,7 @@ sphinx-argparse>=0.4.0,<0.5 -sphinxcontrib-asciinema>=0.3.7,<0.4 -myst-parser>=1.0.0,<2.0 -furo>=2023.3.23,<2024 -sphinx_copybutton>=0.5.1,<0.6 +sphinx-copybutton>=0.5.1,<0.6 +sphinx-design>=0.4.1,<0.5.0 sphinx-reredirects>=0.1,<0.2 -sphinx_design>=0.4.1,<0.5.0 \ No newline at end of file +furo>=2023.3.23,<2024 +myst-parser>=1.0.0,<2.0 +numpydoc>=1.5.0,<1.6 \ No newline at end of file From c56ac94dfeb272072c5090d0cddc02b91162e452 Mon Sep 17 00:00:00 2001 From: Jason Kai Date: Mon, 31 Jul 2023 11:10:42 -0400 Subject: [PATCH 3/3] simplify main doc page - Simplify explanation from docs to README (to be fully updated later) --- README.md | 7 ++++++- docs/general/main.md | 33 --------------------------------- docs/index.md | 9 --------- 3 files changed, 6 insertions(+), 43 deletions(-) delete mode 100644 docs/general/main.md diff --git a/README.md b/README.md index a54f6d0a..ce788b7a 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,8 @@ # Anatomical Fiducials (AFIDs) Utility Tools -[![Documentation Status](https://readthedocs.org/projects/afids-utils/badge/?version=latest)](https://afids-utils.readthedocs.io/en/latest/?badge=latest) \ No newline at end of file +[![Documentation Status](https://readthedocs.org/projects/afids-utils/badge/?version=latest)](https://afids-utils.readthedocs.io/en/latest/?badge=latest) + +The `afids_utils` package provides common utilities for projects involving +anatomical fiducials (AFIDs). For a comprehensive list of available utilities +refer to the [documentation](https://afids-utils.readthedocs.io/en/stable) +page. \ No newline at end of file diff --git a/docs/general/main.md b/docs/general/main.md deleted file mode 100644 index 673e1a2f..00000000 --- a/docs/general/main.md +++ /dev/null @@ -1,33 +0,0 @@ -# Overview - -The purpose of the `afids_utils` package is to provide commonly used utility -functions (written in Python) that is applicable to a various anatomical -fiducial (AFIDS) projects. The `afids_utils` documentation provides a -comprehensive reference guide designed to assist users and developers in -effectively utilizing the functionalities provided by the package's -application programming interface (API). It serves as a centralized resource -that offers detailed information about the various modules, classes, functions, -and constants available within the `afids_utils` package. - -Following the introduction, the API Reference pages provide a structured -organization of the package's modules and classes. Each module is described, explaining its role and the specific functionalities it offers. Detailed -information is provided for each class, including its methods, attributes, and -inheritance hierarchy, along with explanations of their purposes and usage. - -Additionally, the API page includes comprehensive documentation for the -functions and constants within the package. It describes the parameters -expected by each function, their data types, and their respective return -values. The documentation also highlights any optional parameters, default -values, and notable exceptions that may be raised. - -To assist developers in understanding and effectively utilizing the -`afids_utils` package, the API page may include code examples that -demonstrate the practical usage of the various modules, classes, functions, -and constants. These examples showcase common use cases, allowing developers -to grasp the concepts quickly and integrate them into their own projects. - -Furthermore, the API page may provide guidelines and best practices specific to -the `afids_utils` package. It may include recommendations on code structure, -error handling, performance optimization, and any other considerations that can -enhance the developer experience and ensure reliable and efficient usage of the -package. \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index f8cdc82d..3beca1fb 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,15 +1,6 @@ ```{include} ../README.md ``` -```{toctree} -:caption: General -:name: general -:hidden: -:maxdepth: 2 - -general/main -``` - ```{toctree} :caption: API Reference :name: api_reference