We have recently worked on functionality in our web site to generate documentation from source in a few ways that we hope will improve the quality as well as simplify maintenance. We have already written a bit about the log and param documentation in the crazyflie-firmware repository, but we now also added and API reference in the python library as well as generating a list of publications related to the Crazyflie.
The Log and Param documentation
Earlier this year we worked on generating documentation for Log and Params from doxygen comments. We will not dig deeper into this here, but you can read more about it in this blog post. The latest version is available on our web in the repository documentation for the crazyflie-firmware: logs and params
An API reference for our Python library
The Crazyflie Python library is what you might use to create programs that interact with the Crazyflie, for instance to manage small swarms. For a while we have had introductory documentation, and step-by-step guides to show you how to perform, what we think are, common tasks.
However along the way we have also added comments and examples to our code. And this, combined with the way we have structured the library actually enables us to automagically generate reference API documentation. That is, something that shows you everything that is possible to do with the library, all modules and classes, all methods and constants that the library offers.
After some recent work this is now happening and the documentation will now get generated each time we deploy our website!
The API reference documentation can be found in the repository documentation for the library. Please check it out! And be picky, complain where the documentation is lacking! Or if the formatting seems weird! We are trying to get the hang of this and we need you to push us!
Managing publications
Some years ago we started to add publication that are related to the Crazyflie to our Research page, we hope that it might be inspiring to read about all the awesome things that the Crazyflie is used for.
Until now it has been a simple list in markdown but with an increasing number of publications it has become harder and harder to maintain it, finally we have put the work into generating the list from a BibTeX (.bib) file instead. One advantage of the new solution is that BibTeX is a well known format to the research community with lots of tools around to manage BibTeX files while another improvement is that the list will be formatted in a consistent manner (which was not always the case earlier).
If you want to add a publication to the page, simply update the .bib file with your data and create a pull request with the changes. We will merge when appropriate and the publication will become visible on the web after the next deploy, usually within a few days.
Behind the scenes
The code for generating documentation from source tends to spread out over multiple repositories and creates some complexity with a multitude of tools for different languages. It should not be necessary to understand the details and we hope the system will be easy to use for contributors to the code base.
Any questions or comments are welcome.
Happy coding!
For the publications, would it be possible to support keywords and (optionally) filter by them on the webpage? E.g., a user can select “all” to see the current list, or “motion planning” to see all papers related to motion planning etc. (multiple keywords per paper are possible). I am happy to help with the categories, as I have done that grouping anyways for the Crazyswarm talk during the BAM days. In the *.bib file this is just a comma-separated keywords list for each entry.
Good point! Filtering would be nice and we also looked at it, unfortunately it required a bit too much work do be done this time. Maybe we will do it at some point in the future?
Categories could be added anyway if you want to put the time into it. Displaying them in the list would be pretty easy and it would be a good preparation for future filtering.