generate documentation for plugin models

[RichardHeenan]

Is there a way to generate documentation for plugin models, on the fly, from their .py files as with normal built in models ?

If say I edit a built-in model to make a custom plugin, I don't think there is an easy way to test that the new docs section actually works ( I normally just try it out as a built in model first!), or have I missed something????

[butlerpd]

There was some discussion of that, and I think, as usual, Paul K had some ideas, but I don't know whether a ticket was actually generated. If it were it would likely be in sasmodels. But I agree this is something we still need

[pkienzle]

Duplicates #706.

You can use the sascomp tool, for example:

pythonw sascomp ~/.sasview/plugin_models/core_multi_shell_Ves_b.py -help

This will show you the basic layout, which should be good enough for debugging restructured text markup problems. It won't have the same style sheets as normal docs, so it won't look right. It might render the math markup, but this depends on your toolkit (wx vs qt) and operating system.

As a developer you could drop the plugin into the model directory and rebuild the docs:

cd sasmodels/docs
make html

You will need the 'make' program for this to work, which might be available as an anaconda package.

[ python setup.py docs from sasview directory works, yes Richard normally tests new plugins by dropping them into the normal models directory ]

I modified doc/genmodel.py a bit so that it can take a plugin model .py file, turn it into a model.rst file and run sphinx on it. This is still a toy since it doesn't let end users click help from the gui and pop up the model docs they wrote and any errors in the markup (SasView/sasmodels#403).

[smk78]

The other thing to watch @RichardHeenan is that when you do have a model doc that displays nicely in Sphinx, if you then copy-and-paste that into the "description" section for the plugin on the Marketplace you will need to tinker with it...

[butlerpd]

That is an interesting point. If the docs build properly on the marketplace (i.e. render exactly as they would from our sphinx build) that would go most of the way of solving the problem. I guess that would be a ticket on the marketplace? to use our sphinx build infrastructure?