Description
We need to start to a general framework to produce the documentation of Pinocchio. Two documentations would be useful: one for the C++ API; a second one for the Python interface.
I open the discussion here about the C++ documentation. The best candidate for documentation is Doxygen. Then main issue is to hide the CRTP complexity in the documentation. Right now, I consider that the Doxygen HTML is not usable by novice.
I take a look at Eigen documentation.
http://eigen.tuxfamily.org/dox/index.html
The documentation is organized by "modules". See for example the modules "QR", "LLT", etc for the dense solvers of Eigen:
http://eigen.tuxfamily.org/dox/group__DenseLinearSolvers__Reference.html
In addition, the modules are wrapped in a tutorial-style chapter organization. Finally, the class are listed (while hiding internal classes).
I like the organization by modules. We could have the following modules:
- spatial
- multibody model
- joints
- algorithms
- python interface ===> maybe not to document
I think that it would also be important to accurately select which C++ objects, types, classes and namespaces we want to expose to the documentation. If we reason module by module, it should be pretty evident to chose which to hide.
The bad point is that I do not understand (yet) how the documentation of Eigen is generated. They used advance doxygen features that I do not fully catch.
From the exposition in the doc of the main classes organized by modules, we can complete the doc with presentation pages, tutorials, etc.