-
Notifications
You must be signed in to change notification settings - Fork 3
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Documentation Page #8
Merged
Merged
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,25 @@ | ||
--- | ||
# .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: . |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,6 @@ | ||
## afids_utils.io | ||
|
||
```{eval-rst} | ||
.. automodule:: afids_utils.io | ||
:members: | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,6 @@ | ||
## afids_utils.transforms | ||
|
||
```{eval-rst} | ||
.. automodule:: afids_utils.transforms | ||
:members: | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,109 @@ | ||
# 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" | ||
release = ilm.version("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 = [ | ||
"sphinx_copybutton", | ||
"sphinx_design", | ||
"sphinx_reredirects", | ||
"sphinxarg.ext", | ||
"sphinx.ext.autodoc", | ||
"sphinx.ext.intersphinx", | ||
"sphinx.ext.napoleon", | ||
"myst_parser", | ||
"numpydoc", | ||
] | ||
|
||
|
||
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 = {} | ||
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), | ||
"numpy": ("https://numpy.org/doc/1.24", 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", | ||
# } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 | ||
kaitj marked this conversation as resolved.
Show resolved
Hide resolved
|
||
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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,21 @@ | ||
```{include} ../README.md | ||
``` | ||
|
||
```{toctree} | ||
:caption: General | ||
:name: general | ||
:hidden: | ||
:maxdepth: 2 | ||
|
||
general/main | ||
``` | ||
|
||
```{toctree} | ||
:caption: API Reference | ||
:name: api_reference | ||
:hidden: | ||
:maxdepth: 1 | ||
|
||
api/io | ||
api/transform | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
sphinx-argparse>=0.4.0,<0.5 | ||
sphinx-copybutton>=0.5.1,<0.6 | ||
sphinx-design>=0.4.1,<0.5.0 | ||
sphinx-reredirects>=0.1,<0.2 | ||
furo>=2023.3.23,<2024 | ||
myst-parser>=1.0.0,<2.0 | ||
numpydoc>=1.5.0,<1.6 |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This seems like a really long section of text mostly describing the purpose of documentation, most of which I don't think we need. I'd keep an adjusted version of the first sentence and maybe add some examples of the kinds of operations we're talking about (or just point to the API docs).
I'd also just move whatever remains to the readme and get rid of this file/section.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think for now I will move the majority of this as a comment to the
README
until we have time to fully flesh it out in a separate PR.