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/custom-class-template.rst b/docs/_templates/custom-class-template.rst new file mode 100644 index 0000000..d64b80d --- /dev/null +++ b/docs/_templates/custom-class-template.rst @@ -0,0 +1,34 @@ +{{ fullname | escape | underline}} + +.. currentmodule:: {{ module }} + +.. autoclass:: {{ objname }} + :members: + :show-inheritance: + :inherited-members: + :special-members: __call__, __add__, __mul__ + + {% block methods %} + {% if methods %} + .. rubric:: {{ _('Methods') }} + + .. autosummary:: + :nosignatures: + {% for item in methods %} + {%- if not item.startswith('_') %} + ~{{ name }}.{{ item }} + {%- endif -%} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block attributes %} + {% if attributes %} + .. rubric:: {{ _('Attributes') }} + + .. autosummary:: + {% for item in attributes %} + ~{{ name }}.{{ item }} + {%- endfor %} + {% endif %} + {% endblock %} \ No newline at end of file diff --git a/docs/_templates/custom-module-template.rst b/docs/_templates/custom-module-template.rst new file mode 100644 index 0000000..dd90e32 --- /dev/null +++ b/docs/_templates/custom-module-template.rst @@ -0,0 +1,66 @@ +{{ fullname | escape | underline}} + +.. automodule:: {{ fullname }} + + {% block attributes %} + {% if attributes %} + .. rubric:: Module attributes + + .. autosummary:: + :toctree: + {% for item in attributes %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block functions %} + {% if functions %} + .. rubric:: {{ _('Functions') }} + + .. autosummary:: + :toctree: + :nosignatures: + {% for item in functions %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block classes %} + {% if classes %} + .. rubric:: {{ _('Classes') }} + + .. autosummary:: + :toctree: + :template: custom-class-template.rst + :nosignatures: + {% for item in classes %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block exceptions %} + {% if exceptions %} + .. rubric:: {{ _('Exceptions') }} + + .. autosummary:: + :toctree: + {% for item in exceptions %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + +{% block modules %} +{% if modules %} +.. autosummary:: + :toctree: + :template: custom-module-template.rst + :recursive: +{% for item in modules %} + {{ item }} +{%- endfor %} +{% endif %} +{% endblock %} \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..9e12963 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,81 @@ +# 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 + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +import os +import pathlib + +import tomli + +project = "cSAXS" +copyright = "2023, Paul Scherrer Institute" +author = "Paul Scherrer Institute" + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +current_path = pathlib.Path(__file__).parent.parent.resolve() +version_path = f"{current_path}/pyproject.toml" + + +def get_version(): + """load the version from the version file""" + with open(version_path, "r", encoding="utf-8") as file: + res = tomli.loads(file.read()) + return res["project"]["version"] + + +release = get_version() + +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + # "sphinx.ext.coverage", + "sphinx.ext.viewcode", + "sphinx.ext.napoleon", + "sphinx_toolbox.collapse", + "sphinx_copybutton", + "myst_parser", + "sphinx_design", +] + +myst_enable_extensions = [ + "amsmath", + "attrs_inline", + "colon_fence", + "deflist", + "dollarmath", + "fieldlist", + "html_admonition", + "html_image", + "replacements", + "smartquotes", + "strikethrough", + "substitution", + "tasklist", +] + +autosummary_generate = True # Turn on sphinx.ext.autosummary +add_module_names = False # Remove namespaces from class/method signatures +autodoc_inherit_docstrings = True # If no docstring, inherit from base class +set_type_checking_flag = True # Enable 'expensive' imports for sphinx_autodoc_typehints +autoclass_content = "both" # Include both class docstring and __init__ + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + +language = "Python" + +# -- 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_css_files = ["css/custom.css"] +html_logo = "_static/bec.png" +html_theme_options = {"show_nav_level": 1, "navbar_align": "content"} diff --git a/docs/developer/developer.md b/docs/developer/developer.md new file mode 100644 index 0000000..65ea0f3 --- /dev/null +++ b/docs/developer/developer.md @@ -0,0 +1,11 @@ +(developer)= +# Development + +```{toctree} +--- +maxdepth: 1 +hidden: true +--- +reference/ +``` + diff --git a/docs/developer/reference.md b/docs/developer/reference.md new file mode 100644 index 0000000..c5c59e3 --- /dev/null +++ b/docs/developer/reference.md @@ -0,0 +1,10 @@ +## API Reference + +```{eval-rst} +.. autosummary:: + :toctree: _autosummary + :template: custom-module-template.rst + :recursive: + + csaxs_bec +``` diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..06d6db5 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,39 @@ +# cSAXS documentation + +

+ +````{grid} 3 +:gutter: 5 + +```{grid-item-card} Introduction +:link: introduction +:link-type: ref + +General information. +``` + +```{grid-item-card} User +:link: user +:link-type: ref + +Information for users. +``` + +```{grid-item-card} Developer +:link: developer +:link-type: ref + +Information for developers. +``` +```` + + +```{toctree} +--- +numbered: true +maxdepth: 1 +--- + +introduction/introduction +user/user +developer/developer diff --git a/docs/introduction/introduction.md b/docs/introduction/introduction.md new file mode 100644 index 0000000..d3d2a96 --- /dev/null +++ b/docs/introduction/introduction.md @@ -0,0 +1,2 @@ +(introduction)= +# Introduction 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/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..a300ee3 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,9 @@ +sphinx +sphinx_copybutton +recommonmark +sphinx-toolbox +pydata-sphinx-theme +sphinx-copybutton +myst-parser +sphinx-design +tomli \ No newline at end of file diff --git a/docs/user/user.md b/docs/user/user.md new file mode 100644 index 0000000..5730abd --- /dev/null +++ b/docs/user/user.md @@ -0,0 +1,2 @@ +(user)= +# User