[Documentation] Readme should be ready for the master realease

[liesrock]

Hi @torydebra, thanks a lot for the documentation in the current readme of devel branch.

Can you check my modification and extend the part that are currently missing?

[torydebra]

TODO LIST

• ~doc for schunk that now can be launch as other hands with generic launch files.~
• ~remeber to put passive joint only for not mimic joint. This for how I solved #36~
• ~example of send action via topic (no gui) as in the actul github wiki~

[torydebra]

@liesrock, see this issue, should not be better to write directly in the github wiki? The readme begins to be a bit long.

[liesrock]

Good point! Can we try what suggested by @alaurenzi i.e. readthedoc ?(https://readthedocs.org/)

The outcome is way better compared to the standard github wiki.

Let me know if you find issues with it.

[torydebra]

Right, even better Where should I put the code of documentation? New repository?

[liesrock]

Since I do not have experience with it, I would use @alaurenzi approach:

https://github.com/ADVRHumanoids/xbot2_wip/commit/947f809ac73d08d49a0bfcad4bb9070f0e46e740

https://github.com/ADVRHumanoids/xbot2_wip/tree/master/docs

[alaurenzi]

Hi all, in the xbot2_wip repo the sphynx documentation is generated inside a local build folder, but is not yet being published to github pages. The missing step is to have the build products pushed to the gh_pages branch. A fully working example can be found here if you have read permissions, with also doxygen integration for source code documentation.

I have also followed this guide to kind of automatize the push to gh_pages step.

[alaurenzi]

I forgot to mention that the result can be freely browsed here. All pages provide the possibility to see the underlying source code (see top right)

[liesrock]

browsed here

Tutto bellissimo!

I believe this is the right way to go!

[torydebra]

I see the readthedoc theme everywhere, and it is really good, so I vote for it ! Thanks @alaurenzi for the links, I am following them.

I have created another branch for this, spynxDoc. I will keep you updated here

[torydebra]

I have a first version of the docs, written updating the readme of this repo and of the other related repository. I can visualize it when I build.

I do not understand exaclty how to push it for travis:

I have also followed this guide to kind of automatize the push to gh_pages step.

In this link it seems that it creates another repository with a gh-pages branch. Here we have the gh-pages branch in this repository (which I am also scared to mess it up). So It is not so clear for me how to proceed

[alaurenzi]

Yes it's a trick, there are for sure other ways. It uses this folder hierarchy

myrepo/ (master)  <-- this is the repo I want to document
myrepo-docs/html/ (gh-pages)  <-- this is again the same repo, but checked out at gh_pages

Then from myrepo/doc you issue make html which generates the static site at myrepo-docs/html. At this point, from myrepo-docs/html you commit and push everything.

[torydebra]

Thanks @alaurenzi, I will try

[torydebra]

Great update!

We are using travis, so instead following @alaurenzi, we can automatize the process. I managed to push on gh-pages the sphynx document I wrote: https://advrhumanoids.github.io/ROSEndEffector/index.html

Now, the problem is how to make coexist sphynx docs and doxygen docs. In fact at the previous link there was the doxygen API. I am currently looking a way to have 2 "github.io" or a single one with both documentations. If you know anything about that, suggestions are welcome!

A fully working example can be found here if you have read permissions, with also doxygen integration for source code documentation.

You says that you have also doxy integration, but it is visible online somewhere? (like the spynx doc on github.io)

[alaurenzi]

Have a look here Basically you don't see the doxygen-generated static site, but you can include the doxygen documentation in the spynx site

This is possible thanks to a sphynx module called "breathe", you should find some material online if interested. For sure it is also possible to generate a link to the original doxygen site..

[torydebra]

I manage to add doxygen in sphinx on a my local branch.

By the way, I would like to keep separated the api doc (doxy) and the sphinx doc. So, what I would do is have two github pages: one for doxygen one for readthedocs. We can have this simply creating another repo with only sphinx doc (I suppose).

So we will have a thing like moveit, for example: http://docs.ros.org/kinetic/api/moveit_tutorials/html/doc/robot_model_and_robot_state/robot_model_and_robot_state_tutorial.html with links (like RobotModel) to the doxygen documentation.

[liesrock]

@torydebra I checked the sphynxDoc branch and I was able to generate locally the documentation with readthedocs theme, that's super pretty!

If you need any help to integrate something in our travis flow let me know here.

[torydebra]

I have already integrated it in travis. Now if you push that branch, the doxygen api on github pages is ovewritten with the sphinx documentation. So now the problem is how to make them (sphinx and api doxy) coexist: maybe a new repo for sphinx doc so we can use 2 github pages?

[liesrock]

What about Breath ?

[torydebra]

I checked and tried breath, it permits to have dox doc integrated in sphinx. So there is the "readthedocs theme" that I think is not so suitable to document ALL the functions (as we were discussing last day in chat).

[liesrock]

Ok, let's try with the new repo for Sphinx if we want to keep both. Let me know if I can test something to support you.

We should have a main travis to handle both the documentations.

[torydebra]

I created another repo and filled with docs things from sphinxdoc branch https://github.com/ADVRHumanoids/ROSEndEffectorDocs

It seems I have some trouble to activate this repo on travis. Maybe I can't because I am not the owner of ADVR Humanoids?

@liesrock can you try?

[liesrock]

Yes you are right, I just activated it!

[torydebra]

Still troubles with travis, it says "no builds for this repository" https://travis-ci.com/github/ADVRHumanoids/ROSEndEffectorDocs May this be caused by some limit to the travis subscription that we have (or have not)?

By the way, why travis is necessary for the docs repo? It is possible that using travis is a bit waste for a docs only repository. Without using it, I uploaded source and build folder to github, and things work well. Some info are on that readme. I am not sure this is the right way to go (expecially the folders hyeararchy), so modifications can obviosly happen.

As soon you say ok, we can make ROSEndEffectorDocs public.

The doc page is here https://advrhumanoids.github.io/ROSEndEffectorDocs/ The repo is here https://github.com/ADVRHumanoids/ROSEndEffectorDocs

[liesrock]

The docs repo should be public: is it like this?

[liesrock]

I just read the complete message: yes the repo should be public to have travis.org working. Plus everytime we are going to add documentation this will be published automatically by travis.

[torydebra]

Thanks! I solved putting the docs repo public. Now the online page is https://advrhumanoids.github.io/ROSEndEffectorDocs/

[liesrock]

Super Nice! Please close the issue when you think you are done with the documentation. I will check everything once again before merging on master.

[torydebra]

I think we have a sufficient docs now. I added a page about "how to use" the code, that is the most difficult page to follow (and to write). It explores the universalfindaction.cpp. I would like to know if it is ok for you link.

You already said that the rest is ok, but for other problems we should open issues directly in the docs repo, so I close here

[liesrock]

To me looks clear and nice, I will contribute on it in the next future! We have the chance to ask HRI2 group to use the documentation and give us feedback: they are going to be our beta tester for the framework and also for the documentation!

[torydebra]

Thanks! Yes having feedbacks from someone who has never use it is "super nice".

Also another question: What we should do with the readmes and wiki of this now? (also the readme of other repository)

[liesrock]

@torydebra can we cleanup the readme and the wiki to have only the readthedocs documentation ?

[torydebra]

Indeed that was my question. What we should keep in the readme? I will change the other repo readmes accordingly

[liesrock]

Ok, sorry I miss it: I will take care of this!

[torydebra]

Ok, if you change this repo readme, I will change the other ones to have a similar "style"

[torydebra]

I reopened so we do not forget of this

[liesrock]

Done in devel!

[torydebra]

Sorry Luca, I reopen so I remember to change the readme of all the other repos

[torydebra]

Ok, if you change this repo readme, I will change the other ones to have a similar "style"

Done in the various "devel" branches