Sverchok API documentation

[portnov]

At current state, we have in sverchok.utils a big collection of useful function and classes, that can be used to write scripted nodes, or addons extending Sverchok. Some of these functions are even documented in docstrings. But at the moment the user / developer who wants to write a (scripted) node doesn't even see which modules we have, until he opens source code.

So, the proposal is to generate API documentation using one of existing tools, and publish it at github.io, similar to what we have for user documentation. At the moment, docstrings are rare and not so good, but if we know that they are published we will probably enhance them over the time. And even simple list of modules, classes and methods is useful, imho.

I'm not sure, for what exactly parts of Sverchok should we generate documentation. Probably just for sverchok.utils.

Also, we can discuss if it is good to generate documentation for all top-level classes and methods, or maybe we want to hide something (that will require some fuss with documentation generation tools, but certainly doable).

I managed to generate such documentation for sverchok.utils and sverchok.ui subpackages. Please check it out: sverchok.zip

@zeffii @Durman ?

[Durman]

I don't think this will hurt anybody. )) But such documentation should not suggest that anything in Sverchok will not be unchanged between the releases. So you can use something from utils module but in a next release your script can be broken.

I mentioned here #4218 that it would be nice to describe at least structure of Sverchok modules. I think it's essential to include core, data_structure and node_tree modules (probably dependencies module as well). Also it would be nice to tidy up in the utils module (probably combine modules in subfolders).

What did you use for the generation by the way?

[portnov]

What did you use for the generation by the way?

pdoc3 package. See also #4689.

[portnov]

But such documentation should not suggest that anything in Sverchok will not be unchanged between the releases.

Agreed, in general. We can put a disclaimer either on the page from where we give link to documentation, or somewhere in docstrings.

Probably there are some parts that will not change and some which will change fast. We can figure it out later and mark some modules as "stable" and others as "not stable".

[portnov]

See http://nortikin.github.io/sverchok/Documentation .

[Durman]

Nice.

Is it possible to add main page in md format to join all links to API there? It would be just more convenient to edit it in master than edit html pages in the site branch.

[portnov]

pdoc3 generates HTML documentation. For now, I launch generation for specified list of modules (sverchok.data_structure, sverchok.node_tree, sverchok.core, sverchok.utils). We could instead run generation for sverchok root module, then it will generate an index page - about sverchok module, listing it's submodules. But then 1) we will need to manually skip generation for modules which we do not want to expose, and 2) we will need to somehow hide links from index page to submodules which we do not want to expose. Probably the simplest way is to generate index page "manually", from the same script which launches pdoc3. Or let's just add apidocs_index.md into master, and modify publishing workflow so that it would copy it to gh-pages branch.

[Durman]

Or we can make it simpler. We have section for developers in the user documentation. So we can add extra page for links to the API documentation from there.

[portnov]

Ah, yes, that is possible too.

[Durman]

Tested it out ) - http://nortikin.github.io/sverchok/apidocs/sverchok/node_tree.html