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:
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
```
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
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
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?
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.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
gaisser
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:
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
With a freshly checked out source tree on an Ubuntu 20.04.3 VM, I am getting the following error:
Can you try to reproduce this?
I'll try it out
I can't reproduce this right now. I am using Sphinx v3.5.4 however. Can you update your Sphinx installation?
Was caused by an old sphinx version via apt, using pip works, and looks fabulous :)
one minor thing, if no
build-docsfolder exists, the helper.py exits withFileNotFoundError: [Errno 2] No such file or directory: 'build-docs'I had the same issues, was fixed in
df45f02c39ah, 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.
Also, we should adapt the Readme(s ?) on the new unified helper script.
WIP: Introducing documentation with Sphinxto WIP: Introducing documentation with SphinxTested doc and test