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. 15
      Makefile
  3. 5
      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/

15
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 {} +
@ -54,7 +57,7 @@ lint: ## reformat with black and check style with flake8 @@ -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 @@ -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 @@ -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

5
README.md

@ -92,7 +92,7 @@ The function will raise a KeyError if any of the provided column names @@ -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: @@ -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