Clean doc

[kitchoi]

No actual code modified. Only for documentations (for users/developers)

[itziakos]

can you please update the documentation with the new classes (e.g. https://raw.githubusercontent.com/simphony/simphony-mayavi/clean-doc/doc/source/api/plugin.rst).

It also looks that there are some build issues since I cannot see the modules in readthedocs http://simphony-mayavi.readthedocs.org/en/master/api/plugin.html

[kitchoi]

Now that the only actual code modification is in TabbedPanelCollection. Added documentation in simphony_mayavi.plugins module I believe ReadTheDoc is now happy: http://simphony-mayavi.readthedocs.org/en/clean-doc/

[itziakos]

Thanks @kitchoi,

if you have time, can you fix the docstrings of the functions? It looks that they are not very consistent

For example:

• When an argument needs to be an instance of a class it is common to put the class after : instead of Instance. (e.g. http://simphony-mayavi.readthedocs.org/en/clean-doc/api/core.html#simphony_mayavi.core.cuba_data.CubaData.empty)
• There are some places where optional arguments are given as , optional while other mention in the description that they have a default value.
• It is not good to have the constructor parameters of a class both in the class and __init__ docstrings. It is better to have them in __init__ only. (see problem in file:///C:/Users/itziakos/Projects/simphony-mayavi/doc/build/html/api/plugins.html#simphony_mayavi.plugins.run_and_animate.RunAndAnimate)
• Please do not use : <value> in the body of an argument description. It looks that it confuses the rendering (see problem in http://simphony-mayavi.readthedocs.org/en/clean-doc/api/plugin.html#simphony_mayavi.plugin.EngineManagerStandalone.animate)

[itziakos]

It looks that add engine source to mayavi is missing https://github.com/simphony/simphony-mayavi/blob/clean-doc/simphony_mayavi/plugins/add_engine_source_to_mayavi.py

[kitchoi]

Thanks a lot @itziakos for reviewing this. Instance <--- Done Indeed there are inconsistencies regarding Instance. My bad for starting with bad descriptions but more recent docstrings should be correct. I have hunted down the old and bad ones. Optional/default <---?? (edit: resolved, see below) I am not sure I was able to find where this happens. Do you mean there are occasions where an optional argument is not specified as ", optional"? descriptions in both init and class <-- Done Agree. Thanks for pointing this out. <value> <---?? Not sure I understand what you mean. For long I thought the html_style chosen could not handle the Numpy docstring style. I just found out that's because the napoleon extension is required in the conf.py. Not sure if that's the ill rendering you're referring to. If not, can you explain further please? add_engine_source_to_mayavi <-- wait for a code cleaning PR Indeed. As I revisited this part of the code I wanted to clean it up a bit. I think I will do that code cleaning first (and make a separate) and then come back to this doc cleaning PR.

Thanks again!

[kitchoi]

I just found out that's because the napoleon extension is required in the conf.py.

Please let me add that I have also added the napoleon extension in one of the new commits

[kitchoi]

value <---?? Not sure I understand what you mean. For long I thought the html_style chosen could not handle the Numpy docstring style. I just found out that's because the napoleon extension is required in the conf.py. Not sure if that's the ill rendering you're referring to. If not, can you explain further please?

Ah I spotted that now!

[kitchoi]

wait, no. the problem I spotted is a new problem with the napoleon extension. So no, I still am not sure I understood your comment about <value> and ill rendering.

[kitchoi]

Optional/default <---?? I am not sure I was able to find where this happens. Do you mean there are occasions where an optional argument is not specified as ", optional"?

I found a few places where optional arguments are not marked as ", optional". I believe they should be marked as Numpy docstring style suggested. "default" in the description is optional. https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt

[itziakos]

wait, no. the problem I spotted is a new problem with the napoleon extension. So no, I still am not sure I understood your comment about and ill rendering.

Please do not use the napoleon extension. It should not be activated it conflicts with the sectiondoc extension.

[itziakos]

Optional/default <---?? I am not sure I was able to find where this happens. Do you mean there are occasions where an optional argument is not specified as ", optional"?

I found a few places where optional arguments are not marked as ", optional". I believe they should > be marked as Numpy docstring style suggested. "default" in the description is optional. https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt

Yes, my comment was about the fact in some cases there is an , optional added to the type description and some times it is not.

[kitchoi]

• [x] attributes and general examples in class docstring, parameters for constructor in init
• [x] no napoleon
• [x] free of ", optional" (deviate from numpy docstring but this is not essential)
• [x] fixed default : value

Ready for review again! Thanks @itziakos for your patience.

[kitchoi]

also added add_engine_source_to_mayavi2 in the pluigns module doc page. Some minor cleanup in the code will follow in a separate PR.

[itziakos]

:+1: