From 4f0f261e966489e589a4321773e143e69d58500b Mon Sep 17 00:00:00 2001 From: appleb_m Date: Mon, 5 Jan 2026 13:15:43 +0100 Subject: [PATCH] added docs for autodeploy, renamed changelog to CHANGELOG for consistency --- docs/{changelog.md => CHANGELOG.md} | 0 docs/README.md | 0 docs/conf.py | 131 ++++++++++++++++++++++++++++ docs/index.rst | 31 +++++++ docs/requirements.txt | 37 ++++++++ 5 files changed, 199 insertions(+) rename docs/{changelog.md => CHANGELOG.md} (100%) create mode 100644 docs/README.md create mode 100644 docs/conf.py create mode 100644 docs/index.rst create mode 100644 docs/requirements.txt diff --git a/docs/changelog.md b/docs/CHANGELOG.md similarity index 100% rename from docs/changelog.md rename to docs/CHANGELOG.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..3fb8043a --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,131 @@ +# 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 sys + +# Add project root to Python path so autodoc can import modules +sys.path.insert(0, os.path.abspath('..')) +sys.path.insert(0, os.path.abspath('../daq/src')) # <-- ensure 'src' is on path +sys.path.insert(0, os.path.abspath('../gui/src')) +sys.path.insert(0, os.path.abspath('../common/src')) + +project = 'AareDAQ' +copyright = '2025, Paul Scherrer Institute' +author = 'M. Vears Appleby' +release = '0.2.70' +master_doc = 'index' +root_doc = 'index' +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +autodoc_mock_imports = [ + 'aaredb', + 'aareDBclient', + 'numpy', + 'requests', + 'PyYAML', + 'loguru', + 'utility_tools', + 'extract_results', + 'testxds', + 'db_slurm_handler', + 'websocket', + 'dateutil' +] + +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +extensions = [ + 'myst_parser', + 'sphinx_immaterial', + 'sphinx.ext.autodoc', # Add this + 'sphinx.ext.viewcode', # Optional: source code links + 'sphinx.ext.napoleon' # Optional: Google/NumPy docstring support +] + + +templates_path = ['_templates'] +exclude_patterns = [] +myst_enable_extensions = ['linkify', 'smartquotes'] + + +myst_heading_anchor = 3 + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'sphinx_immaterial' +# html_static_path = ['../broker/redoc-static.html'] +#html_theme_options = { +# 'sidebar_width': '300px', +# 'page_width': 'auto' +#} + +# html_theme_options = { +# 'repo_url': 'https://gitea.psi.ch/mx/aaredaq', +# 'repo_name': 'AareDaq', +# 'nav_title': 'PSI AareDaq', +# # 'html_minify': True, +# # 'css_minify': True, +# 'globaltoc_depth': 2, +# # 'repo_type': 'gitlab', +# 'color_primary': 'indigo', +# 'color_accent': 'lime', +# # 'logo_icon': '' +# } + +# html_logo = 'jfjoch.png' +# html_favicon = 'jfjoch.png' +html_theme_options = { + "icon": { + "repo": "fontawesome/brands/github", # or gitlab/gitea icon + }, + "site_url": "https://gitea.psi.ch/mx/aaredaq", + "repo_url": "https://gitea.psi.ch/mx/aaredaq", + "repo_name": "AareDAQ", + "palette": [ + { + "media": "(prefers-color-scheme: light)", + "scheme": "default", + "primary": "indigo", + "accent": "lime", + "toggle": { + "icon": "material/lightbulb-outline", + "name": "Switch to dark mode", + }, + }, + { + "media": "(prefers-color-scheme: dark)", + "scheme": "slate", + "primary": "indigo", + "accent": "lime", + "toggle": { + "icon": "material/lightbulb", + "name": "Switch to light mode", + }, + }, + ], + "features": [ + "navigation.expand", + "navigation.sections", + "navigation.top", + "search.share", + "toc.follow", + ], + "globaltoc_collapse": False, +} +html_theme_options["google_fonts"] = [] +html_sidebars = { + "**": ["logo-text.html", "globaltoc.html", "searchbox.html"] +} + + +html_show_sourcelink = False + +# language = "Python" + diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000..a206f065 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,31 @@ +.. AareProc documentation master file, created by + sphinx-quickstart on Sun Dec 21 14:22:05 2025. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to AareDAQ's documentation! +==================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + :glob: + + README + CHANGELOG + +.. toctree:: + :maxdepth: 4 + :caption: OpenAPI Python client + + modules/daq.src + modules/gui.src + modules/common.src + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..86a4ba7f --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,37 @@ +alabaster==1.0.0 +babel==2.16.0 +beautifulsoup4==4.12.3 +certifi==2024.8.30 +charset-normalizer==3.4.0 +css-html-js-minify==2.5.5 +docutils==0.21.2 +idna==3.10 +imagesize==1.4.1 +Jinja2==3.1.4 +linkify-it-py==2.0.3 +lxml==5.3.0 +markdown-it-py==3.0.0 +MarkupSafe==3.0.2 +mdit-py-plugins==0.4.2 +mdurl==0.1.2 +myst-parser==4.0.0 +packaging==24.2 +Pygments==2.18.0 +python-slugify==8.0.4 +PyYAML==6.0.2 +requests==2.32.3 +snowballstemmer==2.2.0 +soupsieve==2.6 +Sphinx==8.1.3 +sphinx-material==0.0.36 +sphinxcontrib-applehelp==2.0.0 +sphinxcontrib-devhelp==2.0.0 +sphinxcontrib-htmlhelp==2.1.0 +sphinxcontrib-jsmath==1.0.1 +sphinxcontrib-qthelp==2.0.0 +sphinxcontrib-serializinghtml==2.0.0 +text-unidecode==1.3 +uc-micro-py==1.0.3 +Unidecode==1.3.8 +urllib3==2.2.3 +sphinx_immaterial==0.13.8