From 41c34e8b33fdb38a2b3b59c63ca1463f3fb5e733 Mon Sep 17 00:00:00 2001 From: Dacheng Xu Date: Sun, 19 May 2024 21:17:33 -0400 Subject: [PATCH] Add structure of documentation (#80) * Add structure of documentation * Install axidence * Add documentation requirements * Fix bug --- .gitignore | 3 ++ .readthedocs.yaml | 2 + docs/Makefile | 19 ++++++++++ docs/make.bat | 35 +++++++++++++++++ docs/make_docs.sh | 6 +++ docs/requirements.txt | 11 ++++++ docs/source/build_release_notes.py | 10 +++++ docs/source/conf.py | 60 ++++++++++++++++++++++++++++++ docs/source/index.rst | 34 ++++++++++++++++- docs/source/pairing_plugins.rst | 0 docs/source/plugins_factory.rst | 0 docs/source/salting_plugins.rst | 0 12 files changed, 179 insertions(+), 1 deletion(-) create mode 100644 docs/Makefile create mode 100644 docs/make.bat create mode 100755 docs/make_docs.sh create mode 100644 docs/source/build_release_notes.py create mode 100644 docs/source/pairing_plugins.rst create mode 100644 docs/source/plugins_factory.rst create mode 100644 docs/source/salting_plugins.rst diff --git a/.gitignore b/.gitignore index b363de6..a8d5d3f 100644 --- a/.gitignore +++ b/.gitignore @@ -7,3 +7,6 @@ resource_cache *.gv *.gv.svg strax_test_data +build +docs/source/reference/* +docs/source/reference/release_notes.rst diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 41fa756..7108fbf 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -26,3 +26,5 @@ formats: python: install: - requirements: docs/requirements.txt + - method: pip + path: . diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..eca5a27 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,19 @@ +# 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 0000000..dc1312a --- /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 + +%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/make_docs.sh b/docs/make_docs.sh new file mode 100755 index 0000000..1f2ea20 --- /dev/null +++ b/docs/make_docs.sh @@ -0,0 +1,6 @@ +#!/usr/bin/env bash +make clean +rm -r source/reference +sphinx-apidoc -o source/reference ../axidence +rm source/reference/modules.rst +make html #SPHINXOPTS="-W --keep-going -n" diff --git a/docs/requirements.txt b/docs/requirements.txt index e69de29..bf1139b 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -0,0 +1,11 @@ +# File for the requirements of the documentation +commonmark==0.9.1 +graphviz==0.20.1 +m2r==0.2.1 +mistune==0.8.4 +nbsphinx==0.8.9 +recommonmark==0.7.1 +sphinx==5.2.3 +sphinx_rtd_theme==1.0.0 +Jinja2==3.0.3 +lxml_html_clean diff --git a/docs/source/build_release_notes.py b/docs/source/build_release_notes.py new file mode 100644 index 0000000..c53b4f9 --- /dev/null +++ b/docs/source/build_release_notes.py @@ -0,0 +1,10 @@ +import os +from straxen.docs_utils import convert_release_notes + + +if __name__ == "__main__": + this_dir = os.path.dirname(os.path.realpath(__file__)) + notes = os.path.join(this_dir, "..", "..", "HISTORY.md") + target = os.path.join(this_dir, "reference", "release_notes.rst") + pull_url = "https://github.com/XENONnT/axidence/pull" + convert_release_notes(notes, target, pull_url) diff --git a/docs/source/conf.py b/docs/source/conf.py index e69de29..a0d0790 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -0,0 +1,60 @@ +# 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 axidence + +project = "XENON axidence" +copyright = "2024, axidence contributors, the XENON collaboration" + +release = axidence.__version__ +version = axidence.__version__ + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.viewcode", + "nbsphinx", +] + +templates_path = ["_templates"] +exclude_patterns = [] # type: ignore + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +# -- Options for HTML output + +html_theme = "sphinx_rtd_theme" +# html_static_path = ['_static'] + +# Lets disable notebook execution for now +nbsphinx_allow_errors = True +nbsphinx_execute = "never" + + +def setup(app): + # app.add_css_file('css/custom.css') + # Hack to import something from this dir. Apparently we're in a weird + # situation where you get a __name__ is not in globals KeyError + # if you just try to do a relative import... + import os + import sys + + sys.path.append(os.path.dirname(os.path.realpath(__file__))) + from build_release_notes import convert_release_notes + + this_dir = os.path.dirname(os.path.realpath(__file__)) + notes = os.path.join(this_dir, "..", "..", "HISTORY.md") + os.makedirs(os.path.join(this_dir, "reference"), exist_ok=True) + target = os.path.join(this_dir, "reference", "release_notes.rst") + pull_url = "https://github.com/XENONnT/axidence/pull" + + convert_release_notes(notes, target, pull_url) diff --git a/docs/source/index.rst b/docs/source/index.rst index 68ee89e..bbecd2d 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -9,7 +9,39 @@ Axidence is a strax-based data-driven accidental coincidence background simulati :maxdepth: 1 :caption: Installation - installation.rst + installation + +.. toctree:: + :maxdepth: 1 + :caption: Plugins Factory + + plugins_factory + +.. toctree:: + :maxdepth: 1 + :caption: Salting Plugins + + salting_plugins + reference/salting_plugins_tree + +.. toctree:: + :maxdepth: 1 + :caption: Pairing Plugins + + pairing_plugins + reference/pairing_plugins_tree + +.. toctree:: + :maxdepth: 1 + :caption: Reference + + reference/axidence + +.. toctree:: + :maxdepth: 2 + :caption: Release notes + + reference/release_notes Indices and tables ================== diff --git a/docs/source/pairing_plugins.rst b/docs/source/pairing_plugins.rst new file mode 100644 index 0000000..e69de29 diff --git a/docs/source/plugins_factory.rst b/docs/source/plugins_factory.rst new file mode 100644 index 0000000..e69de29 diff --git a/docs/source/salting_plugins.rst b/docs/source/salting_plugins.rst new file mode 100644 index 0000000..e69de29