Add documentation infrastructure

Add documentation infrastructure and some sample content.

Documentation is generated by sphinx using extensions to support
Markdown an restructuredText for simple documentation writing.

Signed-off-by: Bobby Noelte <b0661n0e17e@gmail.com>

.gitignore

@@ -1,5 +1,3 @@
-docs/
-
 # Default ignore folders and files for VS Code, Python
 
 .vscode/*

Makefile

@@ -12,7 +12,7 @@ help:
 	@echo "  pip-dev    - Install dependencies from requirements-dev.txt."
 	@echo "  install    - Install EOS in editable form (development mode) into virtual environment."
 	@echo "  docker-run - Run entire setup on docker
-	@echo "  docs       - Generate HTML documentation using pdoc."
+	@echo "  docs       - Generate HTML documentation (in build/docs/html/)."
 	@echo "  run        - Run flask_server in the virtual environment (needs install before)."
 	@echo "  dist       - Create distribution (in dist/)."
 	@echo "  clean      - Remove generated documentation, distribution and virtual environment."
@@ -46,13 +46,13 @@ dist: pip
 	@echo "Distribution created (see dist/)."
 
 # Target to generate HTML documentation
-docs: pip
-	pdoc --html --force modules -o docs
+docs: pip-dev
+	.venv/bin/sphinx-build -M html docs build/docs
+	@echo "Documentation generated to build/docs/html/."
 
 # Clean target to remove generated documentation, distribution and virtual environment
 clean:
 	@echo "Cleaning virtual env, distribution and documentation directories"
-	rm -rf docs
 	rm -rf dist
 	rm -rf .venv
 

docs/akkudoktoreos/about.rst

@@ -0,0 +1,14 @@
+..
+    Copyright (c) 2024 Bobby Noelte
+    SPDX-License-Identifier: Apache-2.0
+
+.. _akkudoktoreos_about:
+
+About Akkudoktor EOS
+####################
+
+The Energy System Simulation and Optimization System (EOS) provides a comprehensive solution for
+simulating and optimizing an energy system based on renewable energy sources. With a focus on
+photovoltaic (PV) systems, battery storage (batteries), load management (consumer requirements),
+heat pumps, electric vehicles, and consideration of electricity price data, this system enables
+forecasting and optimization of energy flow and costs over a specified period.

docs/conf.py

@@ -0,0 +1,48 @@
+# 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
+
+# Make source file directories available to sphinx
+sys.path.insert(0, str(Path("..", "src").resolve()))
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "Akkudoktor EOS"
+copyright = "2024, Andreas Schmitz"
+author = "Andreas Schmitz"
+release = "0.0.1"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx_rtd_theme",
+    "myst_parser",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = []
+
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".txt": "markdown",
+    ".md": "markdown",
+}
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]
+html_logo = "_static/logo.png"
+html_theme_options = {
+    "logo_only": False,
+    "titles_only": True,
+}

docs/develop/CONTRIBUTING.md

@@ -0,0 +1,48 @@
+# Contributing to EOS
+
+Thanks for taking the time to read this!
+
+The `EOS` project is in early development, therefore we encourage contribution in the following ways:
+
+## Bug Reports
+
+Please report flaws or vulnerabilities in the [GitHub Issue Tracker]((https://github.com/Akkudoktor-EOS/EOS/issues)) using the corresponding issue template.
+
+## Ideas & Features
+
+Please first discuss the idea in a [GitHub Discussion](https://github.com/Akkudoktor-EOS/EOS/discussions) or the [Akkudoktor Forum](https://www.akkudoktor.net/forum/diy-energie-optimierungssystem-opensource-projekt/) before opening an issue.
+
+There are just too many possibilities and the project would drown in tickets otherwise.
+
+## Code Contributions
+
+We welcome code contributions and bug fixes via [Pull Requests](https://github.com/Akkudoktor-EOS/EOS/pulls).
+To make collaboration easier, we require pull requests to pass code style and unit tests.
+
+### Code Style
+
+Our code style checks use [`pre-commit`](https://pre-commit.com).
+
+```bash
+pip install -r requirements.txt
+```
+
+To run formatting automatically before every commit:
+
+```bash
+pre-commit install
+```
+
+Or run them manually:
+
+```bash
+pre-commit --all
+```
+
+### Tests
+
+Use `pytest` to run tests locally:
+
+```bash
+python -m pytest -vs --cov modules --cov-report term-missing tests/
+```

docs/develop/getting_started.rst

@@ -0,0 +1,84 @@
+..
+    SPDX-License-Identifier: Apache-2.0
+
+.. _akkudoktoreos_getting_started:
+
+Getting Started
+###############
+
+Installation
+************
+
+`Good installation guide <https://meintechblog.de/2024/09/05/andreas-schmitz-joerg-installiert-mein-energieoptimierungssystem/>`_
+
+The project requires Python 3.10 or newer.
+
+Quick Start Guide
+-----------------
+
+On Linux (Ubuntu/Debian):
+
+```bash
+sudo apt install make
+```
+
+On MacOS (requires `Homebrew <https://brew.sh>`_):
+
+```zsh
+brew install make
+```
+
+Next, adjust `config.py`.
+The server can then be started with `make run`. A full overview of the main shortcuts is given by `make help`.
+
+Detailed Instructions
+---------------------
+
+All necessary dependencies can be installed via `pip`. Clone the repository and install the required packages with:
+
+```bash
+git clone https://github.com/Akkudoktor-EOS/EOS
+cd EOS
+```
+
+Next, create a virtual environment. This serves to store the Python dependencies, which we will install later using `pip`:
+
+```bash
+virtualenv .venv
+```
+
+Finally, install the Python dependencies for EOS:
+
+```bash
+.venv/bin/pip install -r requirements.txt
+```
+
+To always use the Python version from the virtual environment, you should activate it before working in EOS:
+
+```bash
+source .venv/bin/activate
+```
+(for Bash users, the default under Linux) or
+
+```zsh
+. .venv/bin/activate
+```
+(if using zsh, primarily for MacOS users).
+
+If `pip install` fails to install the mariadb dependency, the following commands may help:
+
+* Debian/Ubuntu: `sudo apt-get install -y libmariadb-dev`
+* MacOS/Homebrew: `brew install mariadb-connector-c`
+
+Followed by a renewed `pip install -r requirements.txt`.
+
+Usage
+*****
+
+Adjust `config.py`.
+
+To start the server:
+
+```bash
+make run
+```

docs/index.rst

@@ -0,0 +1,17 @@
+..
+    Copyright (c) 2024 Bobby Noelte
+    SPDX-License-Identifier: Apache-2.0
+
+.. _akkudoktoreos:
+
+Akkudoktor EOS documentation
+============================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   welcome
+   akkudoktoreos/about
+   develop/getting_started
+   develop/CONTRIBUTING

docs/welcome.rst

@@ -0,0 +1,19 @@
+..
+    Copyright (c) 2024 Bobby Noelte
+    SPDX-License-Identifier: Apache-2.0
+
+.. _akkudoktoreos_welcome:
+
+Welcome to the EOS documentation!
+#################################
+
+This documentation is continuously written. It is edited via text files in the
+`reStructuredText(reST) <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_
+markup language and then compiled into a static website/offline document using the open source tool
+`Sphinx <https://www.sphinx-doc.org>`_ and will hopefully someday land on
+`Read the Docs <https://akkudoktoreos.readthedocs.io/en/latest/index.html>`_.
+
+You can contribute to EOS's documentation by opening
+`GitHub issues <https://github.com/Akkudoktor-EOS/EOS/issues>`_
+or sending patches via pull requests on its
+`GitHub repository <https://github.com/Akkudoktor-EOS/EOS>`_.

requirements-dev.txt

@@ -1,4 +1,7 @@
 build==1.2.2.post1
+myst-parser==4.0.0
+sphinx==8.0.2
+sphinx_rtd_theme==3.0.1
 pytest==8.3.3
 pytest-xprocess==1.0.2
 requests==2.32.3