Introducing documentation with Sphinx #526

muellerr · 2021-12-01T11:20:38+01:00

muellerr commented

2021-12-01 11:20:38 +01:00

Fixes #448

This PR introduces the generation of documentation based on
this excellent blog post: https://devblogs.microsoft.com/cppblog/clear-functional-c-documentation-with-sphinx-breathe-doxygen-cmake/

It combines the tools Sphinx, Doxygen and Breathe to generate good
looking HTML documentation conveniently which can be hosted easily.

The helper scripts were unified and there is now one helper.py script
which can be used to create, build and open both tests and documentation.
"./helper.py -h" can be used to get the different options.

This PR also contains some smaller fixes which were necessary for the docs
to build

There are two ways to create the documentation. Make sure to install breathe, sphinx and doxygen first. E.g. for Ubuntu:

python3 -m pip install breathe sphinx

sudo apt-get install doxygen

Manually

mkdir build-docs && cd build-docs
cmake -DFSFW_BUILD_DOCS=ON -DFSFW_OSAL=host ..
cmake --build . -j
firefox docs/sphinx/index.html

Using script

./scripts/helper.py docs -a

Fixes #448 This PR introduces the generation of documentation based on this excellent blog post: https://devblogs.microsoft.com/cppblog/clear-functional-c-documentation-with-sphinx-breathe-doxygen-cmake/ It combines the tools Sphinx, Doxygen and Breathe to generate good looking HTML documentation conveniently which can be hosted easily. The helper scripts were unified and there is now one helper.py script which can be used to create, build and open both tests and documentation. "./helper.py -h" can be used to get the different options. This PR also contains some smaller fixes which were necessary for the docs to build There are two ways to create the documentation. Make sure to install breathe, sphinx and doxygen first. E.g. for Ubuntu: ```sh python3 -m pip install breathe sphinx ``` ```sh sudo apt-get install doxygen ``` 1. Manually ```sh mkdir build-docs && cd build-docs cmake -DFSFW_BUILD_DOCS=ON -DFSFW_OSAL=host .. cmake --build . -j firefox docs/sphinx/index.html ``` 2. Using script ```sh ./scripts/helper.py docs -a ```

muellerr added 1 commit 2021-12-01 11:20:40 +01:00

c2bf09d506 Introducing documentation with Sphinx

This PR introduces the generation of documentation based on
this excellent blog post: https://devblogs.microsoft.com/cppblog/clear-functional-c-documentation-with-sphinx-breathe-doxygen-cmake/

It combines the tools Sphinx, Doxygen and Breathe to generate good
looking HTML documentation conveniently which can be hosted easily.

The helper scripts were unified and there is now one helper.py script
which can be used to create, build and open both tests and documentation.
"./helper.py -h" can be used to get the different options.

This PR also contains some smaller fixes which were necessary for the docs
to build

muellerr added this to the v3.0.0 milestone 2021-12-01 11:21:15 +01:00

muellerr added the

Documentation

feature

cosmetics

labels 2021-12-01 11:21:35 +01:00

muellerr requested review from gaisser 2021-12-01 11:21:42 +01:00

muellerr commented

2021-12-01 11:27:18 +01:00

The next step would be to think about where to host the documentation (readthedocs.io or self hosted?), and then cross-reference it. After doing that, the old markdown files can be deleted and the README.md can be shortened to only contains quick facts.

Also, some chapters should be extended

The next step would be to think about where to host the documentation (readthedocs.io or self hosted?), and then cross-reference it. After doing that, the old markdown files can be deleted and the README.md can be shortened to only contains quick facts. Also, some chapters should be extended

mohr commented

2021-12-03 13:02:05 +01:00

With a freshly checked out source tree on an Ubuntu 20.04.3 VM, I am getting the following error:

Running Sphinx v1.8.5
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 21 source files that are out of date
updating environment: 21 added, 0 changed, 0 removed
reading sources... [100%] pus                                                  
/home/mohr/git/fsfw/docs/api/devicehandler.rst:14: WARNING: Parsing of expression failed. Using fallback parser. Error was:
Invalid definition: Error in parenthesized expression-list, expected ',' or ')'. [error at 77]
  const ReturnValue_t DeviceHandlerIF::NO_REPLY_EXPECTED = MAKE_RETURN_CODE(0xA8)
  -----------------------------------------------------------------------------^

Sphinx error:
master file /home/mohr/git/fsfw/docs/contents.rst not found
make[2]: *** [docs/CMakeFiles/Sphinx.dir/build.make:83: docs/sphinx/index.html] Error 2
make[1]: *** [CMakeFiles/Makefile2:1412: docs/CMakeFiles/Sphinx.dir/all] Error 2
make: *** [Makefile:130: all] Error 2

Can you try to reproduce this?

With a freshly checked out source tree on an Ubuntu 20.04.3 VM, I am getting the following error: ``` Running Sphinx v1.8.5 building [mo]: targets for 0 po files that are out of date building [html]: targets for 21 source files that are out of date updating environment: 21 added, 0 changed, 0 removed reading sources... [100%] pus /home/mohr/git/fsfw/docs/api/devicehandler.rst:14: WARNING: Parsing of expression failed. Using fallback parser. Error was: Invalid definition: Error in parenthesized expression-list, expected ',' or ')'. [error at 77] const ReturnValue_t DeviceHandlerIF::NO_REPLY_EXPECTED = MAKE_RETURN_CODE(0xA8) -----------------------------------------------------------------------------^ Sphinx error: master file /home/mohr/git/fsfw/docs/contents.rst not found make[2]: *** [docs/CMakeFiles/Sphinx.dir/build.make:83: docs/sphinx/index.html] Error 2 make[1]: *** [CMakeFiles/Makefile2:1412: docs/CMakeFiles/Sphinx.dir/all] Error 2 make: *** [Makefile:130: all] Error 2 ``` Can you try to reproduce this?

muellerr commented

2021-12-03 13:18:37 +01:00

I'll try it out

muellerr commented

2021-12-03 14:39:21 +01:00

I can't reproduce this right now. I am using Sphinx v3.5.4 however. Can you update your Sphinx installation?

muellerr added 1 commit 2021-12-03 14:55:13 +01:00

df45f02c39

script fixes, odd behaviour

mohr commented

2021-12-03 15:14:11 +01:00

Was caused by an old sphinx version via apt, using pip works, and looks fabulous :)

mohr commented

2021-12-03 15:15:31 +01:00

one minor thing, if no build-docs folder exists, the helper.py exits with FileNotFoundError: [Errno 2] No such file or directory: 'build-docs'

one minor thing, if no `build-docs` folder exists, the helper.py exits with `FileNotFoundError: [Errno 2] No such file or directory: 'build-docs'`

muellerr commented

2021-12-03 15:44:21 +01:00

I had the same issues, was fixed in df45f02c39

I had the same issues, was fixed in https://egit.irs.uni-stuttgart.de/fsfw/fsfw/commit/df45f02c393bde14b232d1668f6004256615e68a

mohr commented

2021-12-03 16:00:38 +01:00

ah, missed that. Could you check that this is also fixed for tests? It seems not to me, but I am not sure if it is because my working directory is dirty.