Create markdown docs from docstring in py files

[s-martin]

• use pydoc-markdown to create markdown docs from docstrings in py files; generated docs can be found here: https://github.com/s-martin/RPi-Jukebox-RFID/blob/future3/pydoc-markdown/documentation/developers/docstring/README.md
• added to precommit hook to run, when py files are changed.
• changes for markdown formatting, e.g.
  • links
  • Code samples
  • Indentation
  • etc.

Pro/con evaluation of different tools can be found here s-martin#31

Replaces #2159

[s-martin]

Found a problem we need to address, see NiklasRosenstein/pydoc-markdown#308

[s-martin]

Found a problem we need to address, see NiklasRosenstein/pydoc-markdown#308

Enforcing the docstring style to sphinx did help for the code sample formatting problem.

[s-martin]

Fixes also #1771

[s-martin]

Could be merged, any comments?

[AlvinSchiller]

Should :class: be rendered? Or be a link?

compare change in rfid/reader/init.py #55
https://github.com/s-martin/RPi-Jukebox-RFID/blob/63ecd190ea7303a7c643b79615f07b34a2f81a4e/src/jukebox/components/rfid/reader/__init__.py#L55

[s-martin]

Not all occurrences of :class: are currently converted to # syntax

[AlvinSchiller]

Do we need an action that checks for changed but uncommited docs? As the precommit hook must be activated manually and could be forgotten (like flake8).

The action could run "./run_docgeneration.sh" and fail the build if there a outgoing changes?

[s-martin]

Do we need an action that checks for changed but uncommited docs? As the precommit hook must be activated manually and could be forgotten (like flake8).

The action could run "./run_docgeneration.sh" and fail the build if there a outgoing changes?

I would suggest the following:

• keep the current pre commit hook, so devs can already check their changes
• in addition add a GitHub Action in case someone didn't activate pre commit hooks (similar to flake8 behavior)

My question would be, should I extend the Python action or add another one? What do you think?

Discussion about action OR hook was already in #2159

[AlvinSchiller]

Extending the current action would be fine for me.

Would you also add flake8-docstrings like mentioned in #2159?

[s-martin]

I would add flake8-docstrings in a separate PR. Right now there are many warnings, which would fix in this separate PR.

[s-martin]

Added a check in the action. Needs more testing, though.

[s-martin]

The action does not work as expected, therefore I will add the integration into the Python action in a separate PR later.

Otherwise it could be merged from my point of view.