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/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..72d35e01 --- /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