Convert documentation to reStructuredText, build with Sphinx and host as HTML #448

New Issue

muellerr · 2021-07-22T10:55:28+02:00

muellerr commented

2021-07-22 10:55:28 +02:00

The current documentation of the FSFW is in Markdown, which has some drawbacks compared to documentation formats like Sphinx. Furthermore, there are some issues with doxygen, the biggest one that the documentation is not hosted/accessable via web interface and looks really old. The Doxygen documentation is currently not used (practically) as far as I know. But the format still has a lot of potential and doxygen is a proven tool.

This is a good article about that issue: https://devblogs.microsoft.com/cppblog/clear-functional-c-documentation-with-sphinx-breathe-doxygen-cmake/

I think it would be a good idea to convert the current documentation to resturctured text first and then host it on EGit. Then, the article above can be used as a guideline to convert the doxygen documentation to Sphinx, so the API documentation can be added as a chapter in the primary documentation. The article linked above also specifies another huge advantage of sphinx:

... embedding things like rationale, examples, notes, or swapping out auto-generated output for hand-written is not very well supported. In Sphinx however, the finer-grained control gives you the ability to write documentation which is truly geared towards getting people to learn and understand your library.

The documentation currently is also lacking an introduction chapter, which provides a guided introduction to build a simple multithreaded application using one periodic task and one fixed timeslot task as a simple way to get started with the FSFW (from scratch). This would be an excellent way to guide FSFW beginners in a motivating way.

The current documentation of the FSFW is in Markdown, which has some drawbacks compared to documentation formats like Sphinx. Furthermore, there are some issues with doxygen, the biggest one that the documentation is not hosted/accessable via web interface and looks really old. The Doxygen documentation is currently not used (practically) as far as I know. But the format still has a lot of potential and doxygen is a proven tool. This is a good article about that issue: https://devblogs.microsoft.com/cppblog/clear-functional-c-documentation-with-sphinx-breathe-doxygen-cmake/ I think it would be a good idea to convert the current documentation to resturctured text first and then host it on EGit. Then, the article above can be used as a guideline to convert the doxygen documentation to Sphinx, so the API documentation can be added as a chapter in the primary documentation. The article linked above also specifies another huge advantage of sphinx: > ... embedding things like rationale, examples, notes, or swapping out auto-generated output for hand-written is not very well supported. In Sphinx however, the finer-grained control gives you the ability to write documentation which is truly geared towards getting people to learn and understand your library. The documentation currently is also lacking an introduction chapter, which provides a guided introduction to build a simple multithreaded application using one periodic task and one fixed timeslot task as a simple way to get started with the FSFW (from scratch). This would be an excellent way to guide FSFW beginners in a motivating way.

muellerr added the

feature

Documentation

labels 2021-07-22 10:55:28 +02:00

muellerr referenced a pull request that will close this issue

2021-12-01 11:21:10 +01:00

Introducing documentation with Sphinx #526

gaisser closed this issue

2021-12-06 15:05:31 +01:00

Sign in to join this conversation.