Cleaning up Python docs

Development
,
1

I am looking into cleaning up various docs and documentation generation process. One of the things that’s quite unwieldy with our Python documentation generation stage is the fact that we generate documentation for all proxies. e.g. Sphere. It requires that ParaView is fully built before documentation is generated – which is crazy! Also causes the documentation generation time to bloat!

So the question is, if we remove these proxy docs would anyone miss them? Does anyone use them? Essentially, I am talking of getting rid of this and all proxies listed there.

2

Are docstrings set properly for the Python objects? If so, that’s at least one place that the information would still be accessible.

3

Yes. Indeed. help(sphere) would still continue to work.

4

I personally do not usually refer to the Python proxy documentation, but I am familiar with many of the properties on my most-used sources and filters, and know how to use help within Python to find out about properties and available methods. It seems like a nice thing to have, but the current documentation is broken in some places (see the docs for AMRFragmentIntegration, for example). So for now I would be okay with that documentation not being generated.

By the way, running help(Sphere) gives some weird combination of documentation for module.paraview.simple.CreateObject and the XML description of the Sphere source. It is not until you instantiate a Sphere object and call help on the instance that you can get full documentation from paraview.simple.Sphere:

s = Sphere()
help(s)

It would be good to see if we could get the full documentation for help(Sphere).

5

I’ve reported that here.

6

I use those docs and also refer my users to them, but maybe I should consider alternate docs.

7

@DennisConklin, ah okay. In that case, I think I’ll leave this as is for now. We need a better way of documenting all available proxies in the application, both of Python scripting and for the UI. I am going to investigate some more how we can do that more elegantly.

8

What tool extracts the documentation? Is it just from the .xml files or is it extracted from the generated Python bindings? Getting the dependencies of that step down would be nice. It would also allow for the nightly documentation to cover all proxies and not just those that are being built right now (which should remain the default).

9

it is extracted from Python bindings. I am indeed thinking along the lines of extracting from XML but it has its own issues.