From 573b6c81d81f4fdb727bb5f5f80e457f450da1e6 Mon Sep 17 00:00:00 2001 From: gschnabel <40870991+gschnabel@users.noreply.github.com> Date: Sun, 20 Mar 2022 16:48:47 +0100 Subject: [PATCH] first commit of documentation stub --- docs/Makefile | 20 +++++++++++++++ docs/make.bat | 35 +++++++++++++++++++++++++ docs/source/api.rst | 10 ++++++++ docs/source/conf.py | 60 +++++++++++++++++++++++++++++++++++++++++++ docs/source/index.rst | 20 +++++++++++++++ docs/source/usage.rst | 35 +++++++++++++++++++++++++ 6 files changed, 180 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/make.bat create mode 100644 docs/source/api.rst create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.rst create mode 100644 docs/source/usage.rst diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..d0c3cbf1 --- /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 = source +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/make.bat b/docs/make.bat new file mode 100644 index 00000000..6fcf05b4 --- /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=source +set BUILDDIR=build + +if "%1" == "" goto help + +%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 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/source/api.rst b/docs/source/api.rst new file mode 100644 index 00000000..c14f5b96 --- /dev/null +++ b/docs/source/api.rst @@ -0,0 +1,10 @@ +API +=== + +.. autosummary:: + :toctree: generated + + gmapi.inference + gmapi.data_management.tablefuns + gmapi.data_management.uncfuns + diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 00000000..fe50c726 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,60 @@ +# 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 -------------------------------------------------------------- + +# 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 pathlib +import sys +sys.path.insert(0, (pathlib.Path(__file__).parents[2] / 'source').resolve().as_posix()) + + +# -- Project information ----------------------------------------------------- + +project = 'gmapi' +copyright = '2022, Georg Schnabel' +author = 'Georg Schnabel' + +# The full version, including alpha/beta/rc tags +release = '0.10' + + +# -- 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.ext.duration', + 'sphinx.ext.doctest', + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary' +] + +# 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 = [] + + +# -- 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' + +# 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'] diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 00000000..a3d9791e --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,20 @@ +Welcome to gmapi's documentation! +================================= + +**gmapi** is a package that provides facilities to +read the information on nuclear experiments from +a database file in the format used by the GMAP code. +Furthermore, this package contains functions to +apply the Generalized Least Squares (GLS) method +for inference on the retrieved experimental data sets. + +Check out the :doc:`usage` section for further information, +including how to :ref:`install ` the project. + +Contents +-------- + +.. toctree:: + usage + api + diff --git a/docs/source/usage.rst b/docs/source/usage.rst new file mode 100644 index 00000000..ad4b3cea --- /dev/null +++ b/docs/source/usage.rst @@ -0,0 +1,35 @@ +Usage +===== + +.. _installation: + +Installation +------------ + +To use gmapi, first install it using git clone: + +.. code-block:: console + + git clone https://github.com/iaea-nds/GMAP-Python + + +Creating recipes +---------------- + +Here is an example of function documentation. +Try out the awesome function ``gmapi.new_gls_update()``. + +.. py:function:: gmapi.new_gls_update(priortable, exptable, refvalues) + + Perform the GLS method to obtain evaluated estimates and uncertainties. + + :param priortable: dataframe with prior quantities + :type priortable: DataFrame + :return: A dictionary with ``upd_vals`` and ``upd_cov``. + :type: dictionary + + +Here is the real deal: + +.. autofunction:: gmapi.inference.new_gls_update +