Simplified docstring 2 markdown generation

[s-martin]

This PR tests different docstring converters. In the end it should override #26 (result PR #28) and MiczFlor#2159

tl;dr
No easy solution, not many options available

Currently tested are

lazydocs

• ⬆️ Creates a md file for each py file and an overview file
• ⛔Doesn't recognize the syntax used (e.g. :param)
• ⛔not actively maintained

Example: https://github.com/s-martin/RPi-Jukebox-RFID/blob/future3/pydoc-markdown/documentation/developers/docstring-lazydocs/docstring.md

pydoc-markdown

• ⬆️ Understands our syntax
• ⛔ One big markdown file
• ⛔ no easy customization

Example: https://github.com/s-martin/RPi-Jukebox-RFID/blob/future3/pydoc-markdown/documentation/developers/docstring-pydoc-markdown/docstring.md

Current Status
This script is used for testing both tools: https://github.com/s-martin/RPi-Jukebox-RFID/blob/future3/pydoc-markdown/run_docstring2markdown.sh

TODO:

• decide which tool to use
• integrate in pre commit hook

Reference:

• Old comparism: https://stackoverflow.com/questions/36237477/python-docstrings-to-github-readme-md
• Other tools (not maintained):
  • https://github.com/coldfix/doc2md
  • https://github.com/freeman-lab/myopts
• https://www.woolseyworkshop.com/2020/06/25/documenting-python-programs-with-doxygen/#Summary

[Groovylein]

How is the coverage of docstrings in our code?

An alternative I found is:
https://github.com/python-lsp/docstring-to-markdown

[s-martin]

How is the coverage of docstrings in our code?

Ok, I would say :)

An alternative I found is:
https://github.com/python-lsp/docstring-to-markdown

I have seen that, but so far I wanted to start with tools where I don't have to do the file handling anymore. But worth a look!

[s-martin]

Real PR done here MiczFlor#2181