Make pinocchio python binding documentation online

[hwyao]

Python documentation

While I am for the first time start using the python bindings of pinocchio, I just start from the cheatsheet, which is quite helpful. But after running dir for each class, there are still some methods not recorded in this cheatsheet.

By searching on google, what we can get (only considering documentations form authors) are Github pages, pinocchio doxygen mainly for C++, Pinocchio PyBind11 helpers (Maybe I miss something sorry but that's what I can get after getting around for with some common attempts). There are not too much extra information over the python interfaces apart from the cheatsheet.

So I check the source code and actually everything about binding is already here in files of include/pinocchio/bindings/python. (e.g. (e.g. SE3.Interpolate)). And it is already in docstring of the corresponding python classes. Running commands like help(pinocchio.SE3) would be helpful if we want to check it individually.

What I think better as a feature is just extract them out and make as a website and make it available somewhere, so that python classes and methods can be searched with google, and there are hyperlinks inside the websites, like the existing C++ documentation.

Feature Request

We can try to use tools like pydoc or pdoc to extract a website from it. All these commands are just based on the robotpkg installation.

pydoc

Like this (need some manual fixing). This is just some edit over the mikecharles's script.

#!/usr/bin/env python
import pydoc
import os, sys
import pkgutil

def list_submodules(list_name, package_name):
    for loader, module_name, is_pkg in pkgutil.walk_packages(package_name.__path__, package_name.__name__+'.'):
        list_name.append(module_name)
        module_name = __import__(module_name, fromlist='dummylist')
        if is_pkg:
            list_submodules(list_name, module_name)

if len(sys.argv) != 2:
    print('Usage: {} [PACKAGE-NAME]'.format(os.path.basename(__file__)))
    sys.exit(1)
else:
    package_name = sys.argv[1]

try:
    package = __import__(package_name)
except ImportError:
    print('Package {} not found...'.format(package_name))
    sys.exit(1)


all_modules = [package_name]
list_submodules(all_modules, package)
for module in all_modules:
    print(module)
    pydoc.writedoc(module)

# Run this script with the following command:
# python3 generate_doc_pin.py pinocchio
# To fix some missing files run the following commands:
# python3 -m pydoc -w pinocchio.pinocchio_pywrap.cholesky pinocchio.pinocchio_pywrap.liegroups pinocchio.pinocchio_pywrap.rpy pinocchio.pinocchio_pywrap.serialization

Preview:


(I like the color and the link of the classes inside, but the process of the generation is a bit weird. -w parameter makes the program stuck so I have to do it recursively on my own).

generated_pydoc.zip

pdoc

Or running this command:

python3 -m pdoc --html pinocchio
# have many warnings, does have time to see why

Preview:

(I like the structured layout here but the table of contents is too long).

generated_pdoc.zip

Into CI/CD process

Well…… it is still not the same quality as the doxygen files. But since the documentation here Main features of Pinocchio/Python bindings is still empty, maybe we can consider to deploy these automatic generated html somehow integrated or hyperlinked here for searching and clicking.

Hopefully we can discuss more things about this (and maybe play with some parameters and configurations to explore better documentation generation). :)

[jcarpent]

Thanks for the report.
Here is a tentative: https://gepettoweb.laas.fr/doc/stack-of-tasks/pinocchio/jnrh2023/template/algorithm.html

[jcarpent]

We will come back to better solutions soon. Very sorry for the lack of clear Python docs.

[hwyao]

Oh, you already have this here with Sphinx, that's great.

Seems that the searching of this site is a bit not optimized. Doing some SEO analysis over this site maybe?

By trying some search with google：

pinocchio computeFrameJacobian

Would miss this site.

pinocchio computeFrameJacobian site:https://gepettoweb.laas.fr/

This would hit the site at the 3rd place.

pinocchio computeFrameJacobian site:https://gepettoweb.laas.fr/doc/stack-of-tasks/pinocchio/jnrh2023/

This would finally hit the only site available.

p.s.

pinocchio computeFrameJacobian python
pinocchio computeFrameJacobian python site:https://gepettoweb.laas.fr/

Would miss this site. 🤣

[hwyao]

Since you are using read the docs, Maybe this is helpful: https://docs.readthedocs.io/en/stable/guides/technical-docs-seo-guide.html

Seems to be a lot of trivial details. Maybe not in the first priority list for this large open-source projects.

Anyway, this is a repo that helps me a lot. Thanks for the information here and thank you all for your wonderful code and contribution 👍 :)