added mkdocks for documentation

A method to add and build documentation pages was added to
the project.

.gitignore

@@ -53,8 +53,9 @@ coverage.xml
 # Django stuff:
 *.log
 
-# Sphinx documentation
+# documentation
 docs/_build/
+site/
 
 # PyBuilder
 target/

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 {} +
@@ -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
 

README.md

@@ -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

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

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.

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.

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

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

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

pyproject.toml

@@ -53,6 +53,11 @@ dev = [
     "keyring",
     "pre-commit",
 ]
+docs = [
+    "mkdocs",
+    "mkdocstrings[python]",
+    "mkdocs-material",
+]
 
 [tool.black]
 line-length = 79