Documenting Python Pinocchio about pinocchio HOT 11 OPEN

@jcarpent Great. I'll give it a shot, please let me know if I am doing it wrong. I looked at the Contribution Guidelines, but I'm sure I'll get it wrong.

Best.

from pinocchio.

By luck, I ended up on this, in the doxygen documentation: http://www.stack.nl/~dimitri/doxygen/manual/customize.html#xmlgenerator.
The last line says:

See the Breathe project for an example that uses doxygen XML output from Python to bridge it with the Sphinx document generator.

I have no idea if this is useful for you.

from pinocchio.

Another option is this: http://stackoverflow.com/questions/34896122/how-to-avoid-redundancy-between-c-and-boostpython-docs

It shouldn't be too hard to set up. It's mostly some CMake.

from pinocchio.

I think this last option is the best one, avoiding double descriptions of same objects or operators. Thanks a lot for this pointing.

from pinocchio.

I do not think that "how-to-avoid-redundancy-between-c-and-boostpython-docs" is that useful, at least yet. Right now, we mostly have a boost::python documentation, and we do not care so much about having the same Doxygen documentation (at least for the python module of Pinocchio).

We are indeed mostly interested in having a python-style HTML doc synthesized from the boost::python documents.

Or are you suggesting that we use Doxygen as the Python documentation, while keeping the boost::python comments?

from pinocchio.

Just to continue the discussion, one efficient way to get clear python doc from boost::python is the following options docstring_options local_docstring_options(true, true, false); as pointed by http://stackoverflow.com/questions/6114462/how-to-override-the-automatically-created-docstring-data-for-boostpython

from pinocchio.

Is there a place we can contribute to the documentation for pinocchio? There are still quite a few outdated bits in the main documentation that make for quite a headache for new users and I would love to be able to help. It's always easier to contribute to documentation as you are going through the process of learning because you have to install all the new packages etc etc.

from pinocchio.

In pinocchio/blob/master/doc/d-practical-exercises/2-invgeom.md :

robot.initDisplay(loadModel=True)

is deprecated, should be:

robot.initViewer(loadModel=True)

from pinocchio.

Thanks @drewhamiltonasdf for raising this issue.
Could you provide a fix for this?

from pinocchio.

Sure, what's the recommended way?

I tried forking the documentation to fix the broken LaTex formatting for title:

Using quaternions for an object

in rigid-bodies.md, but I couldn't figure out how to merge. Do I just fork and merge into main and wait for approval or is there a better way? I am a bit green around the ears when it comes to contributing to gitHub projects.

Not sure if it is irritating or helpful but I would love to contribute to the documentation as I am working my way through learning Pinnocchio...

from pinocchio.

Yes, please open a PR with a fix on the devel branch (which is the branch collecting ongoing developmentsà.
As you are not a maintainer of this repository, you cannot merge.
To enhance the quality of the project, we also proceed with PR reviews by the maintainers or other persons related to the projects.

@drewhamiltonasdf We do appreciate your contributions, notably in terms of documentation. It will for sure help others to understand and dive into Pinocchio. I'm looking forward to your fixes.

from pinocchio.