[documentation] Processes docs

[denisri]

I see that there is a new sphinx doc in mia_processes, which is nice.
I would like to point out also that there is a documentation system in Capsul which allows to integrate into sphinx docs the doculentation of Capsul processes and pipelines, automatically generated, and which should avoid the needs to rewrite all docs manually in .rst files, which may (and currently happen to) differ from the process help (docstrings + traits descriptions).
The system is using Capsul sphinxext module.

I have written a litte demo for it in mia_processes, in the capsul_doc branch. The docs have to be rebuilt manually (make html from the docs/ directory) since I have not put the pre-build docs under git (I have left the former ones).

If this seems a good choice, then the docs currently in sphinx .rst files should be merged into the processes docstrings and traits helps, then can be removed. (I can help with that)
So tell me.

[servoz]

That sounds like a very good idea. Can we talk about it at the next meeting on March 16th?

[denisri]

OK.

[denisri]

The auto-build of docs is not working in travis-ci for the branch capsul_doc, because the build is starting from a clean new populse_mia which has no configuration files, and there are many places in the code which do not expect such a situation, and get stuck in endless loops. For instance in software_properties.py, it gets into such loop:

while "properties" not in os.listdir(config_path):
     config_path = os.path.dirname(config_path)

whereas the "properties" directory does not exist anywhere, thus the loop never ends. There are no safeguards.
This will need some cleanup until it works.

[denisri]

Ah OK I think the problem is due to my incomplete export of populse_mia: the properties directory actually exists. I'm fixint that.

[denisri]

OK the docs should build now in travis-ci on the capsul_doc branch. However it doesn't push to gh-pages because this is only done for the master branch.

[servoz]

I just changed the conditions for deployment in the travis.yml file in order to push to gh-pages for the capsul_doc branch.

[servoz]

ok, I think it might actually be possible to make a nice doc from the class docstrings and the descriptions in the traits. I still have one main problem that I haven't figured out how to solve (there are some minor problems I won't talk about here):
Let's take as an example the Coregister class in the mia_processes.preprocess.spm.spatial_preprocessing module. My idea was to put the html result of:

-------------

.. [#label] Syntax: mia_processes/nipype Coregister <=> SPM12 Coregister.

    Useful links:
    `SPM12 Coregister <https://www.fil.ion.ucl.ac.uk/spm/doc/manual.pdf#page=39>``,
    `nipype Coregister <https://nipype.readthedocs.io/en/latest/api/generated/nipype.interfaces.spm.preprocess.html#coregister>`

In the footer (see the handwritten document.)

By putting this part in the class docstring it does not come out as a footer (see the links to auto-generated docs from docstrings and traits descriptions)... Is there a work around ?

[servoz]

In fact, I'm afraid that with all the good will in the world, it's hard to look good in html and at the same time in info by moving the mouse over the bricks in mia, automatically ... In fact, apart from the footer problem of the previous post we can consider that it's possible to have a not too bad result in html but... I've just looked at the result when we pass the mouse on the bricks coregister with this new writing and the result is not so good (it's a raw string and of course not interpreted) ...

[denisri]

Yes that's true, I could not make footnotes either. I'm not sure it could be improved by modifying the capsul-sphinx ext module, I haven't looked at it yet.
In Mia, or actually in capsul PipelineDevelopperView, for now we show the raw "source" of the doc. We can also think modifying it to display the HTML doc it it has been built in a known location. Not completely sure what it would look like in a bullet tooltip, but we could try.

[servoz]

OK, maybe we shouldn't waste time on this right now?
Maybe the most important thing (in terms of invested time) right now is the creation of the raw text, and we can work on the form later?
As far as I'm concerned, the current master form (creation of the detailed doc by hand in .rst + link to it in the class docstring + minimalist description of the parameter at the instantiation of the traits) suits me fine. Indeed it allows you to have a nice doc that makes you want to (well ... Everyone's taste is different!!!) and a mini doc that is not detailed when you pass the mouse over a plug (useful for a quick reminder of a plug if we don't want to consult the whole documentation), as it is currently the case in master.
Anyway, the improvement you've implemented for the html creation (#4) is a great improvement. For the automatically creation of the docs from the docstrings and traits, we'll be able to find as usual a collegial decision when it will be really necessary (in my opinion, it's really necessary to succeed in proposing an attractive doc to our audience ... when it will really exist!).

[denisri]

I have worked a little bit on process docs in capsul PipelineDevelopperView. Showing the HTML docs in the process tooltips is possible, but the docs are too large to fit in a tooltip, and not convenient (tooltips disapear before you have an opportunity to read all of it, you cannot click on it to follow links, large tooltips hide all of the screen...) so I think it's not a good idea to display them that way. We have to stick with a short doc here (without much embedding, without parameters since they are already listed on process boxes). But it's possible to display the full docs in a HTML browser in a separate widget, which may or may not be incorporated in MIA's GUI main window.
PipelineDevelopperView allows it and now handles it. See populse/capsul@f752b14 and populse/capsul@05b0884.

[servoz]

Thanks !