diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /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) diff --git a/docs/_templates/autosummary/base.rst b/docs/_templates/autosummary/base.rst new file mode 100644 index 0000000..1621719 --- /dev/null +++ b/docs/_templates/autosummary/base.rst @@ -0,0 +1,2 @@ +{% extends "autosummary_core/base.rst" %} +{# The template this is inherited from is in astropy/sphinx/ext/templates/autosummary_core. If you want to modify this template, it is strongly recommended that you still inherit from the astropy template. #} diff --git a/docs/_templates/autosummary/class.rst b/docs/_templates/autosummary/class.rst new file mode 100644 index 0000000..0fa59f2 --- /dev/null +++ b/docs/_templates/autosummary/class.rst @@ -0,0 +1,2 @@ +{% extends "autosummary_core/class.rst" %} +{# The template this is inherited from is in astropy/sphinx/ext/templates/autosummary_core. If you want to modify this template, it is strongly recommended that you still inherit from the astropy template. #} diff --git a/docs/_templates/autosummary/module.rst b/docs/_templates/autosummary/module.rst new file mode 100644 index 0000000..230cd6e --- /dev/null +++ b/docs/_templates/autosummary/module.rst @@ -0,0 +1,2 @@ +{% extends "autosummary_core/module.rst" %} +{# The template this is inherited from is in astropy/sphinx/ext/templates/autosummary_core. If you want to modify this template, it is strongly recommended that you still inherit from the astropy template. #} diff --git a/docs/api-reference/cleaning/index.rst b/docs/api-reference/cleaning/index.rst new file mode 100644 index 0000000..0d02de1 --- /dev/null +++ b/docs/api-reference/cleaning/index.rst @@ -0,0 +1,16 @@ +.. _cleaning: + +*************************************** +Image Cleaning (`~radiotools.cleaning`) +*************************************** + +.. currentmodule:: radiotools.cleaning + +Image cleaning module of radiotools. + + +Reference/API +============= + +.. automodapi:: radiotools.cleaning + :inherited-members: diff --git a/docs/api-reference/gridding/index.rst b/docs/api-reference/gridding/index.rst new file mode 100644 index 0000000..0d98c80 --- /dev/null +++ b/docs/api-reference/gridding/index.rst @@ -0,0 +1,16 @@ +.. _gridding: + +********************************* +Gridding (`~radiotools.gridding`) +********************************* + +.. currentmodule:: radiotools.gridding + +Gridding module of radiotools. + + +Reference/API +============= + +.. automodapi:: radiotools.gridding + :inherited-members: diff --git a/docs/api-reference/index.rst b/docs/api-reference/index.rst new file mode 100644 index 0000000..f22811f --- /dev/null +++ b/docs/api-reference/index.rst @@ -0,0 +1,9 @@ +************* +API Reference +************* + +.. toctree:: + :maxdepth: 1 + :glob: + + */index diff --git a/docs/api-reference/layouts/index.rst b/docs/api-reference/layouts/index.rst new file mode 100644 index 0000000..e19aa4d --- /dev/null +++ b/docs/api-reference/layouts/index.rst @@ -0,0 +1,16 @@ +.. _layouts: + +******************************* +Layouts (`~radiotools.layouts`) +******************************* + +.. currentmodule:: radiotools.layouts + +Layouts module of radiotools. + + +Reference/API +============= + +.. automodapi:: radiotools.layouts + :inherited-members: diff --git a/docs/api-reference/measurements/index.rst b/docs/api-reference/measurements/index.rst new file mode 100644 index 0000000..654c2af --- /dev/null +++ b/docs/api-reference/measurements/index.rst @@ -0,0 +1,16 @@ +.. _measurements: + +***************************************** +Measurements (`~radiotools.measurements`) +***************************************** + +.. currentmodule:: radiotools.measurements + +Measurements module of radiotools. + + +Reference/API +============= + +.. automodapi:: radiotools.measurements + :inherited-members: diff --git a/docs/api-reference/utils/index.rst b/docs/api-reference/utils/index.rst new file mode 100644 index 0000000..714cf37 --- /dev/null +++ b/docs/api-reference/utils/index.rst @@ -0,0 +1,16 @@ +.. _utils: + +*************************** +Utils (`~radiotools.utils`) +*************************** + +.. currentmodule:: radiotools.utils + +Utils module of radiotools. + + +Reference/API +============= + +.. automodapi:: radiotools.utils + :inherited-members: diff --git a/docs/api-reference/visibility/index.rst b/docs/api-reference/visibility/index.rst new file mode 100644 index 0000000..3f769ba --- /dev/null +++ b/docs/api-reference/visibility/index.rst @@ -0,0 +1,16 @@ +.. _visibility: + +************************************* +Visibility (`~radiotools.visibility`) +************************************* + +.. currentmodule:: radiotools.visibility + +Visibility module of radiotools. + + +Reference/API +============= + +.. automodapi:: radiotools.visibility + :inherited-members: diff --git a/docs/changelog.rst b/docs/changelog.rst new file mode 100644 index 0000000..2120f07 --- /dev/null +++ b/docs/changelog.rst @@ -0,0 +1,5 @@ +********** +Change Log +********** + +.. include:: ../CHANGES.rst diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..c2308ac --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,121 @@ +#!/usr/bin/env python3 +import datetime +import sys +from pathlib import Path + +import radiotools + +if sys.version_info < (3, 11): + import tomli as tomllib +else: + import tomllib + +pyproject_path = Path(__file__).parent.parent / "pyproject.toml" +pyproject = tomllib.loads(pyproject_path.read_text()) + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.intersphinx", + "sphinx.ext.todo", + "sphinx.ext.coverage", + "sphinx.ext.viewcode", + "sphinx_automodapi.automodapi", + "sphinx_automodapi.smart_resolver", + "matplotlib.sphinxext.plot_directive", + "numpydoc", + "sphinx_design", + "IPython.sphinxext.ipython_console_highlighting", +] + +numpydoc_show_class_members = False +numpydoc_class_members_toctree = False + +templates_path = ["_templates"] +exclude_patterns = [ + "_build", + "Thumbs.db", + ".DS_Store", + "changes", + "*.log", +] + +source_suffix = ".rst" +master_doc = "index" + + +project = pyproject["project"]["name"] +author = pyproject["project"]["authors"][0]["name"] +copyright = "{}. Last updated {}".format( + author, datetime.datetime.now().strftime("%d %b %Y %H:%M") +) +python_requires = pyproject["project"]["requires-python"] + +# make some variables available to each page +rst_epilog = f""" +.. |python_requires| replace:: {python_requires} +""" + + +version = radiotools.__version__ +# The full version, including alpha/beta/rc tags. +release = version + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = "pydata_sphinx_theme" +html_static_path = ["_static"] + +html_file_suffix = ".html" + + +html_theme_options = { + "github_url": "https://github.com/radionets-project/radiotools", + "header_links_before_dropdown": 5, + "navbar_start": ["navbar-logo"], + "navigation_with_keys": False, + # "use_edit_page_button": True, + "icon_links_label": "Quick Links", + "icon_links": [ + { + "name": "Radionets Project", + "url": "https://github.com/radionets-project", + "type": "url", + "icon": "https://avatars.githubusercontent.com/u/77392854?s=200&v=4", # noqa: E501 + }, + ], + "announcement": """ +

radiotools is not stable yet, so expect large and rapid + changes to structure and functionality as we explore various + design choices before the 1.0 release.

+ """, +} + +html_title = f"{project}" +htmlhelp_basename = project + "docs" + + +# Configuration for intersphinx +intersphinx_mapping = { + "astropy": ("https://docs.astropy.org/en/stable", None), + "ipywidgets": ("https://ipywidgets.readthedocs.io/en/stable", None), + "joblib": ("https://joblib.readthedocs.io/en/stable", None), + "matplotlib": ("https://matplotlib.org/stable", None), + "numba": ("https://numba.readthedocs.io/en/stable", None), + "numpy": ("https://numpy.org/doc/stable", None), + "pandas": ("https://pandas.pydata.org/pandas-docs/stable", None), + "pytest": ("https://docs.pytest.org/en/stable", None), + "python": ("https://docs.python.org/3", None), + "scipy": ("https://docs.scipy.org/doc/scipy", None), + "setuptools": ("https://setuptools.pypa.io/en/stable", None), + "sklearn": ("https://scikit-learn.org/stable", None), +} + + +suppress_warnings = [ + "intersphinx.external", +] diff --git a/docs/developer-guide/getting-started.rst b/docs/developer-guide/getting-started.rst new file mode 100644 index 0000000..787a93a --- /dev/null +++ b/docs/developer-guide/getting-started.rst @@ -0,0 +1,7 @@ +.. _getting_started_dev: + +****************************** +Getting Started for Developers +****************************** + +We strongly recommend using the `Miniforge3 conda distribution `_. diff --git a/docs/developer-guide/index.rst b/docs/developer-guide/index.rst new file mode 100644 index 0000000..e26b4d2 --- /dev/null +++ b/docs/developer-guide/index.rst @@ -0,0 +1,10 @@ +.. _dev-guide: + +*************** +Developer Guide +*************** + +.. toctree:: + :maxdepth: 2 + + getting-started diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..75610e2 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,99 @@ +.. include:: references.rst + +:html_theme.sidebar_secondary.remove: true +:html_theme.sidebar_primary.remove: true + +.. _radiotools: + +########################################## +Tools for Radio Astronomy (``radiotools``) +########################################## + +.. currentmodule:: radiotools + + +**Version**: |version| **Date**: |today| + +**Useful links**: +`Source Repository `__ | +`Issue Tracker `__ | + +**License**: MIT + +**Python**: |python_requires| + + +.. _radiotools_docs: + +.. toctree:: + :maxdepth: 1 + :hidden: + + user-guide/index + developer-guide/index + api-reference/index + changelog + + +.. grid:: 1 2 2 3 + + .. grid-item-card:: + + :octicon:`book;40px` + + User Guide + ^^^^^^^^^^ + + Learn how to get started as a user. This guide + will help you install radiotools. + + +++ + + .. button-ref:: user-guide/index + :expand: + :color: primary + :click-parent: + + To the user guide + + + .. grid-item-card:: + + :octicon:`person-add;40px` + + Developer Guide + ^^^^^^^^^^^^^^^ + + Learn how to get started as a developer. + This guide will help you install radiotools + for development and explains how to contribute. + + +++ + + .. button-ref:: developer-guide/index + :expand: + :color: primary + :click-parent: + + To the developer guide + + + .. grid-item-card:: + + :octicon:`code;40px` + + API Reference + ^^^^^^^^^^^^^ + + The API reference contains detailed + descriptions of of the modules, classes + and functions included in radiotools. + + +++ + + .. button-ref:: api-reference/index + :expand: + :color: primary + :click-parent: + + To the API reference diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..32bb245 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/user-guide/getting-started.rst b/docs/user-guide/getting-started.rst new file mode 100644 index 0000000..666eff0 --- /dev/null +++ b/docs/user-guide/getting-started.rst @@ -0,0 +1,11 @@ +.. _getting_started_users: + + +************************* +Getting Started for Users +************************* + +.. warning:: + + The following guide is for *users*. If you want to contribute to + radiotools as a developer, see :ref:`getting_started_dev`. diff --git a/docs/user-guide/index.rst b/docs/user-guide/index.rst new file mode 100644 index 0000000..12eb561 --- /dev/null +++ b/docs/user-guide/index.rst @@ -0,0 +1,10 @@ +.. _user-guide: + +********** +User Guide +********** + +.. toctree:: + :maxdepth: 2 + + getting-started diff --git a/pyproject.toml b/pyproject.toml index 58bd7ae..fc3e800 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -100,7 +100,7 @@ omit = [ template = "docs/changes/template.rst" # let towncrier create proper links to the merged PR - issue_format = "`#{issue} `__" + issue_format = "`#{issue} `__" [tool.towncrier.fragment.feature] name = "New Features"