Introducing documentation with Sphinx #526

Merged
gaisser merged 3 commits from mueller/sphinx-docs into development 2021-12-06 15:05:30 +01:00
Owner

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
  1. Manually
mkdir build-docs && cd build-docs
cmake -DFSFW_BUILD_DOCS=ON -DFSFW_OSAL=host ..
cmake --build . -j
firefox docs/sphinx/index.html
  1. 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
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
Author
Owner

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
Owner

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?
Author
Owner

I'll try it out

I'll try it out
Author
Owner

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

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
Owner

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

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

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'`
Author
Owner

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
Owner

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.

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.
Owner

Also, we should adapt the Readme(s ?) on the new unified helper script.

Also, we should adapt the Readme(s ?) on the new unified helper script.
muellerr added 1 commit 2021-12-06 14:46:56 +01:00
gaisser changed title from Introducing documentation with Sphinx to WIP: Introducing documentation with Sphinx 2021-12-06 15:04:21 +01:00
gaisser changed title from WIP: Introducing documentation with Sphinx to WIP: Introducing documentation with Sphinx 2021-12-06 15:04:21 +01:00
gaisser changed title from WIP: Introducing documentation with Sphinx to Introducing documentation with Sphinx 2021-12-06 15:04:27 +01:00
gaisser approved these changes 2021-12-06 15:05:22 +01:00
gaisser left a comment
Owner

Tested doc and test

Tested doc and test
gaisser merged commit 32ba4301e4 into development 2021-12-06 15:05:30 +01:00
gaisser deleted branch mueller/sphinx-docs 2021-12-06 15:05:36 +01:00
gaisser was assigned by mohr 2021-12-06 15:05:39 +01:00
Sign in to join this conversation.
No description provided.