Open Isengo1989 opened 5 days ago
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
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.
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).
I just updated #160 and moved most of the docs to Markdown format. You may have a look.
Looking good
Link to discussion and related issues
Proposed implementation