From e1acd702d0bef0bcd947e394672a53fc720e9980 Mon Sep 17 00:00:00 2001 From: Steven Rieder Date: Thu, 14 Nov 2024 13:45:52 +0100 Subject: [PATCH 1/7] Add initial Sphinx API documentation --- docs/Makefile | 20 ++++++++++++++++++++ docs/api.rst | 12 ++++++++++++ docs/conf.py | 36 ++++++++++++++++++++++++++++++++++++ docs/index.rst | 18 ++++++++++++++++++ docs/requirements.txt | 2 ++ 5 files changed, 88 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/api.rst create mode 100644 docs/conf.py create mode 100644 docs/index.rst create mode 100644 docs/requirements.txt 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/api.rst b/docs/api.rst new file mode 100644 index 0000000..07bdabf --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,12 @@ +API +=== + +.. autosummary:: + :toctree: generated + + sunbather + sunbather.construct_parker + sunbather.convergeT_parker + sunbather.install_cloudy + sunbather.solveT + sunbather.tools diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..8ed865e --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,36 @@ +# 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 + +import sys +from pathlib import Path + +sys.path.insert(0, str(Path('..', 'src').resolve())) + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = "sunbather" +copyright = "2024, Dion Linssen" +author = "Dion Linssen" + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "myst_parser", +] + +templates_path = ["_templates"] +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +# html_theme = 'alabaster' +html_theme = "sphinx_rtd_theme" +html_static_path = ["_static"] diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..cde744e --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,18 @@ +.. sunbather documentation master file, created by + sphinx-quickstart on Wed Nov 13 11:48:00 2024. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +sunbather documentation +======================= + +Add your content using ``reStructuredText`` syntax. See the +`reStructuredText `_ +documentation for details. + + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + api diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..bfbfd38 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,2 @@ +Sphinx==8.1.3 +sphinx-rtd-theme==3.0.1 From a8281f7e09e9ece70164e6754c1525ceb52b6454 Mon Sep 17 00:00:00 2001 From: Steven Rieder Date: Mon, 18 Nov 2024 12:08:50 +0100 Subject: [PATCH 2/7] Update conf.py for Read the Docs --- docs/conf.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 8ed865e..73ac00e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -19,6 +19,7 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration extensions = [ + "sphinx_rtd_theme", "sphinx.ext.autodoc", "sphinx.ext.autosummary", "myst_parser", @@ -34,3 +35,7 @@ # html_theme = 'alabaster' html_theme = "sphinx_rtd_theme" html_static_path = ["_static"] + + +# Configuration for Read the Docs +html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "/") From fb0c0fa61a6e9c1ef4fecaf3db7507e82ec8f1d3 Mon Sep 17 00:00:00 2001 From: Steven Rieder Date: Mon, 18 Nov 2024 12:11:09 +0100 Subject: [PATCH 3/7] Create .readthedocs.yaml --- .readthedocs.yaml | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 .readthedocs.yaml diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..1235053 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,35 @@ +# Read the Docs configuration file for Sphinx projects +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the OS, Python version and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.8" + # You can also specify other tool versions: + # nodejs: "20" + # rust: "1.70" + # golang: "1.20" + +# Build documentation in the "docs/" directory with Sphinx +sphinx: + configuration: docs/conf.py + # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs + # builder: "dirhtml" + # Fail on all warnings to avoid broken references + # fail_on_warning: true + +# Optionally build your docs in additional formats such as PDF and ePub +# formats: +# - pdf +# - epub + +# Optional but recommended, declare the Python requirements required +# to build your documentation +# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html +# python: +# install: +# - requirements: docs/requirements.txt From 6dd07d3172e66a7c39fe231ecd5f8ff7dd446cc9 Mon Sep 17 00:00:00 2001 From: Steven Rieder Date: Mon, 18 Nov 2024 13:53:25 +0100 Subject: [PATCH 4/7] Update conf.py --- docs/conf.py | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/conf.py b/docs/conf.py index 73ac00e..827410d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -4,6 +4,7 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html import sys +import os from pathlib import Path sys.path.insert(0, str(Path('..', 'src').resolve())) From 03e38fc6cabf7f3bf5c45dc5edff88572e9afa34 Mon Sep 17 00:00:00 2001 From: Steven Rieder Date: Mon, 18 Nov 2024 13:55:38 +0100 Subject: [PATCH 5/7] Update .readthedocs.yaml --- .readthedocs.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 1235053..5216efc 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -30,6 +30,6 @@ sphinx: # Optional but recommended, declare the Python requirements required # to build your documentation # See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html -# python: -# install: -# - requirements: docs/requirements.txt +python: + install: + - requirements: docs/requirements.txt From c0ac2441aa00a751d594fb356fbd0f999f297f65 Mon Sep 17 00:00:00 2001 From: Steven Rieder Date: Mon, 18 Nov 2024 13:56:52 +0100 Subject: [PATCH 6/7] Update requirements.txt --- docs/requirements.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/requirements.txt b/docs/requirements.txt index bfbfd38..6b104fb 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,2 +1,2 @@ -Sphinx==8.1.3 -sphinx-rtd-theme==3.0.1 +Sphinx +sphinx-rtd-theme From 6b639064c8d58ca9b70bf7432afcbfac45ac45f4 Mon Sep 17 00:00:00 2001 From: Steven Rieder Date: Mon, 18 Nov 2024 14:29:16 +0100 Subject: [PATCH 7/7] Update conf.py --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 827410d..2a6d44a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -23,7 +23,7 @@ "sphinx_rtd_theme", "sphinx.ext.autodoc", "sphinx.ext.autosummary", - "myst_parser", + # "myst_parser", ] templates_path = ["_templates"]