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..dc1312ab --- /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/rtd_environment.yml b/docs/rtd_environment.yml new file mode 100644 index 00000000..8e1a6d47 --- /dev/null +++ b/docs/rtd_environment.yml @@ -0,0 +1,17 @@ +--- +name: lcm-docs +channels: + - conda-forge +dependencies: + - python=3.12 + - pip + - setuptools_scm + - sphinx + - sphinxcontrib-bibtex + - sphinx-copybutton + - sphinx-design + - sphinx-panels + - myst-nb + - furo + - pip: + - ../ diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 00000000..e8c314a5 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,96 @@ +# Configuration file for the Sphinx documentation builder. # noqa: INP001 +# +# 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 sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = "lcm" +copyright = "2024, Tim Mensinger, Janos Gabler" # noqa: A001 +author = "Tim Mensinger, Janos Gabler" + + +# Set variable so that todos are shown in local build +on_rtd = os.environ.get("READTHEDOCS") == "True" + + +# -- 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.autodoc", + "sphinx.ext.todo", + "sphinx.ext.coverage", + "sphinx.ext.extlinks", + "sphinx.ext.intersphinx", + "sphinx.ext.mathjax", + "sphinx.ext.viewcode", + "sphinx.ext.napoleon", + "sphinx_copybutton", + "myst_nb", + "sphinx_panels", + "sphinx_design", +] + +myst_enable_extensions = [ + "colon_fence", + "dollarmath", + "html_image", +] + +copybutton_prompt_text = ">>> " +copybutton_only_copy_prompt_lines = False + +extlinks = { + "ghuser": ("https://github.com/%s", "@"), + "gh": ("https://github.com/optimagic-dev/optimagic/pulls/%s", "#"), +} + +intersphinx_mapping = { + "numpy": ("https://docs.scipy.org/doc/numpy", None), + "pandas": ("https://pandas.pydata.org/pandas-docs/stable", None), + "python": ("https://docs.python.org/3.12", None), + "jax": ("https://jax.readthedocs.io/en/latest", None), +} + +linkcheck_ignore = [ + r"https://tinyurl\.com/*.", +] + + +# 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" +html_title = "lcm" + +# 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/development/changes.md b/docs/source/development/changes.md new file mode 100644 index 00000000..d841a673 --- /dev/null +++ b/docs/source/development/changes.md @@ -0,0 +1,4 @@ +(changes)= + +```{include} ../../../CHANGES.md +``` diff --git a/docs/source/development/enhancement_proposals.md b/docs/source/development/enhancement_proposals.md new file mode 100644 index 00000000..65408e0c --- /dev/null +++ b/docs/source/development/enhancement_proposals.md @@ -0,0 +1,12 @@ +# Enhancement Proposals + +LCM Enhancement Proposals (EPs) can be used to discuss and design large changes. + +These EPs are currently in place: + +```{toctree} +--- +maxdepth: 1 +--- +ep-00-refactoring.md +``` diff --git a/docs/source/development/ep-00-refactoring.md b/docs/source/development/ep-00-refactoring.md new file mode 100644 index 00000000..ecf53f98 --- /dev/null +++ b/docs/source/development/ep-00-refactoring.md @@ -0,0 +1,25 @@ +(ep-00)= + +# EP-00: Refactoring + +```{eval-rst} ++------------+------------------------------------------------------------------+ +| Author | `Tim Mensinger `_, | +| | `JanoĊ› Gabler `_ | ++------------+------------------------------------------------------------------+ +| Status | Draft | ++------------+------------------------------------------------------------------+ +| Type | Standards Track | ++------------+------------------------------------------------------------------+ +| Created | 2024-09-06 | ++------------+------------------------------------------------------------------+ +| Resolution | | ++------------+------------------------------------------------------------------+ +``` + + +## Abstract + +This LEP proposes a refactoring of LCM's entry point using newly developed model block +classes. This will move LCM closer to a framework in which users have greater control +over all model aspects, e.g., the model solution and simulation. diff --git a/docs/source/development/index.md b/docs/source/development/index.md new file mode 100644 index 00000000..d18120e8 --- /dev/null +++ b/docs/source/development/index.md @@ -0,0 +1,9 @@ +# Development + +```{toctree} +--- +maxdepth: 1 +--- +enhancement_proposals +changes +``` diff --git a/docs/source/index.md b/docs/source/index.md new file mode 100644 index 00000000..1a7be20c --- /dev/null +++ b/docs/source/index.md @@ -0,0 +1,10 @@ +# LCM + + +```{toctree} +--- +hidden: true +maxdepth: 1 +--- +development/index +```