From 9d5ade2bcd0824f687ce00e9643e244e2db045e4 Mon Sep 17 00:00:00 2001 From: Holger Frey Date: Wed, 31 Aug 2022 15:33:24 +0200 Subject: [PATCH] added mkdocks for documentation A method to add and build documentation pages was added to the project. --- .gitignore | 3 ++- Makefile | 15 ++++++++++++--- README.md | 5 ++++- docs/explanation.md | 18 ++++++++++++++++++ docs/how-to-guides.md | 6 ++++++ docs/index.md | 20 ++++++++++++++++++++ docs/reference.md | 11 +++++++++++ docs/tutorials.md | 17 +++++++++++++++++ mkdocs.yml | 17 +++++++++++++++++ pyproject.toml | 5 +++++ 10 files changed, 112 insertions(+), 5 deletions(-) create mode 100644 docs/explanation.md create mode 100644 docs/how-to-guides.md create mode 100644 docs/index.md create mode 100644 docs/reference.md create mode 100644 docs/tutorials.md create mode 100644 mkdocs.yml diff --git a/.gitignore b/.gitignore index 1d77a72..a1e005a 100644 --- a/.gitignore +++ b/.gitignore @@ -53,8 +53,9 @@ coverage.xml # Django stuff: *.log -# Sphinx documentation +# documentation docs/_build/ +site/ # PyBuilder target/ diff --git a/Makefile b/Makefile index a6d1dab..db6442e 100644 --- a/Makefile +++ b/Makefile @@ -29,7 +29,7 @@ BROWSER := python -c "$$BROWSER_PYSCRIPT" help: @python -c "$$PRINT_HELP_PYSCRIPT" < $(MAKEFILE_LIST) -clean: clean-build clean-pyc clean-test ## remove all build, test, coverage and Python artifacts +clean: clean-build clean-docs clean-pyc clean-test ## remove all build, test, coverage and Python artifacts clean-build: ## remove build artifacts rm -fr build/ @@ -38,6 +38,9 @@ clean-build: ## remove build artifacts find . -name '*.egg-info' -exec rm -fr {} + find . -name '*.egg' -exec rm -f {} + +clean-docs: ## remove documentation artifacts + rm -fr site/ + clean-pyc: ## remove Python file artifacts find . -name '*.pyc' -exec rm -f {} + find . -name '*.pyo' -exec rm -f {} + @@ -54,7 +57,7 @@ lint: ## reformat with black and check style with flake8 isort src isort tests black src tests - flake8 src + flake8 src flake8 --ignore S101 tests test: lint ## run tests quickly, stop on first error @@ -79,6 +82,12 @@ coverall: lint ## full test suite, check code coverage and open coverage report tox: ## run fully isolated tests with tox tox +docs: ## build the documentation using mkdocs + mkdocs build + +serve-docs: docs ## build the documentation and serve them in a web server + mkdocs serve + install: ## install updated project.toml with flint flit install --pth-file @@ -98,5 +107,5 @@ repo: prepareenv ## complete project setup with development environment and git git branch -m main git remote add origin https://git.cpi.imtek.uni-freiburg.de/holgi/sensospot_tools.git git push -u origin main --no-verify - + .venv/bin/pre-commit install --install-hooks diff --git a/README.md b/README.md index 52fc312..5e543c4 100644 --- a/README.md +++ b/README.md @@ -92,7 +92,7 @@ The function will raise a KeyError if any of the provided column names is not present in the data frame ### normalize(data: DataFrame, normalized_time: Union[int, float], time_column: str, value_columns: list[str], template: str) -> DataFrame: - + normalizes values to a normalized exposure time Will raise a KeyError, if any column is not in the data frame; @@ -110,3 +110,6 @@ To install the development version of Sensospot Tools: make devenv To run the tests, use `make tests` or `make coverage` for a complete report. + +To generate the documentation pages use `make docs` or `make serve-docs` for +starting a webserver with the generated documentation diff --git a/docs/explanation.md b/docs/explanation.md new file mode 100644 index 0000000..71077ee --- /dev/null +++ b/docs/explanation.md @@ -0,0 +1,18 @@ +# Explanation + +This part of the project documentation focuses on a +**learning-oriented** approach. You'll learn how to +get started with the code in this project. + +> **Note:** Expand this section by considering the +> following points: + +- Help newcomers with getting started +- Teach readers about your library by making them + write code +- Inspire confidence through examples that work for + everyone, repeatably +- Give readers an immediate sense of achievement +- Show concrete examples, no abstractions +- Provide the minimum necessary explanation +- Avoid any distractions diff --git a/docs/how-to-guides.md b/docs/how-to-guides.md new file mode 100644 index 0000000..54df9be --- /dev/null +++ b/docs/how-to-guides.md @@ -0,0 +1,6 @@ +# How-To Guides + +This part of the project documentation focuses on a +**problem-oriented** approach. You'll tackle common +tasks that you might have, with the help of the code +provided in this project. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..45a32e8 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,20 @@ +# SensoSpot Tools Documentation + +This site contains the project documentation for the +`sensospot_tools` project. + + +## Table Of Contents + +The documentation follows the best practice for +project documentation as described by Daniele Procida +in the [Diátaxis documentation framework](https://diataxis.fr/) +and consists of four separate parts: + +1. [Tutorials](tutorials.md) +2. [How-To Guides](how-to-guides.md) +3. [Reference](reference.md) +4. [Explanation](explanation.md) + +Quickly find what you're looking for depending on +your use case by looking at the different pages. diff --git a/docs/reference.md b/docs/reference.md new file mode 100644 index 0000000..c974133 --- /dev/null +++ b/docs/reference.md @@ -0,0 +1,11 @@ +# Reference + +This part of the project documentation focuses on +an **information-oriented** approach. Use it as a +reference for the technical implementation of the +`sensospot_tools` project code. + + +::: sensospot_tools.hdr + +::: sensospot_tools.selection diff --git a/docs/tutorials.md b/docs/tutorials.md new file mode 100644 index 0000000..fba5682 --- /dev/null +++ b/docs/tutorials.md @@ -0,0 +1,17 @@ +# Tutorials + +This part of the project documentation focuses on an +**understanding-oriented** approach. You'll get a +chance to read about the background of the project, +as well as reasoning about how it was implemented. + +> **Note:** Expand this section by considering the +> following points: + +- Give context and background on your library +- Explain why you created it +- Provide multiple examples and approaches of how + to work with it +- Help the reader make connections +- Avoid writing instructions or technical descriptions + here diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..993bcf2 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,17 @@ +site_name: Sensospot Tools Docs + +nav: + - Introduction: index.md + - Tutorials: tutorials.md + - How-To Guides: how-to-guides.md + - Reference: reference.md + - Explanation: explanation.md + +repo_url: https://github.com/example/repository/ + +theme: + name: readthedocs + highlightjs: true + +plugins: + - mkdocstrings diff --git a/pyproject.toml b/pyproject.toml index a1960bc..9476cc5 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -53,6 +53,11 @@ dev = [ "keyring", "pre-commit", ] +docs = [ + "mkdocs", + "mkdocstrings[python]", + "mkdocs-material", +] [tool.black] line-length = 79