[ENH]: Docs solution

[Isengo1989]

Link to discussion and related issues

https://github.com/Akkudoktor-EOS/EOS/commit/59dcf8c45930470313173e4133cbc168352a6ed6#diff-f064ccb7314efec60cde4c767245788835c1ed8ab43e883d263614e503faa9c3R2

Proposed implementation

Regarding the commit mentioned above. Is there a reason that rst was choosen over md files?

MD files are more common and can be easily hosted via Github Pages, fully integrated and free. Since the project is still fresh, I would recommend that as the docs integration. I can assist here, since it is my bread and butter.

[b0661]

Sphinx and RST is much more powerfull (e.g. automatic API documentation generation) than pure MD. Documentation can be easily exported to Read The Docs for free.

MD files are more common

Like always, depends where you are looking to. Emhass - a comparable project -- uses Sphinx. Some of the open source projects I worked with are using Sphinx and RST.

Anyway I enabled MD in Sphinx. Feel free to write documentation in MD.

To have a look onto what you've done just - from #160 - use:

make read-docs

[Isengo1989]

Sphinx and RST is much more powerfull (e.g. automatic API documentation generation) than pure MD. Documentation can be easily exported to Read The Docs for free.

MD files are more common

Like always, depends where you are looking to. Emhass - a comparable project -- uses Sphinx. Some of the open source projects I worked with are using Sphinx and RST.

Anyway I enabled MD in Sphinx. Feel free to write documentation in MD.

To have a look onto what you've done just - from #160 - use:

make read-docs

I am mainly asking since the project has not been published yet, it sounds like complexity to me ("and will hopefully someday land on"). The question is also if the project needs the powerfulness since Swagger OA schema was already discussed.

Happy to check another way of documenting in github, just making sure it is not overkill / has it's project related benefits / start a discussion.

[Lasall]

I'm also a fan of md/asciidoc documentation because of its builtin integration into Github. The server API generation of Sphynx is not that great (problem with referenced types) and with swagger.io and external url support we don´t have to create anything separately (see here). For the developer documentation (Python implementation) Spynx documentation probably works well.

There are some GitHub workflows that support publishing Sphynx to Github Pages and also to ReadTheDocs which we probably should set up at some point (whichever is easier because we don´t really need to worry about versioning of the developer information).

[b0661]

I just updated #160 and moved most of the docs to Markdown format. You may have a look.

[Isengo1989]

Looking good