Browse Source

added mkdocks for documentation

A method to add and build documentation pages was added to
the project.
main
Holger Frey 2 years ago
parent
commit
9d5ade2bcd
  1. 3
      .gitignore
  2. 11
      Makefile
  3. 3
      README.md
  4. 18
      docs/explanation.md
  5. 6
      docs/how-to-guides.md
  6. 20
      docs/index.md
  7. 11
      docs/reference.md
  8. 17
      docs/tutorials.md
  9. 17
      mkdocs.yml
  10. 5
      pyproject.toml

3
.gitignore vendored

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

11
Makefile

@ -29,7 +29,7 @@ BROWSER := python -c "$$BROWSER_PYSCRIPT" @@ -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 @@ -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 @@ -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

3
README.md

@ -110,3 +110,6 @@ To install the development version of Sensospot Tools: @@ -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

18
docs/explanation.md

@ -0,0 +1,18 @@ @@ -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

6
docs/how-to-guides.md

@ -0,0 +1,6 @@ @@ -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.

20
docs/index.md

@ -0,0 +1,20 @@ @@ -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.

11
docs/reference.md

@ -0,0 +1,11 @@ @@ -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

17
docs/tutorials.md

@ -0,0 +1,17 @@ @@ -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

17
mkdocs.yml

@ -0,0 +1,17 @@ @@ -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

5
pyproject.toml

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

Loading…
Cancel
Save