vmware
Python VDK Interface Web Documentation
What is the feature request? What problem does it solve? Our Python interfaces are described in the classes of vdk API https://github.com/vmware/versatile-data-kit/blob/main/projects/vdk-core/src/vdk/api/ But that's not very easy to navigate and read by end-users. It's also non obvious. Proper documentation should be found in a web page something similar to
- https://docs.python-requests.org/en/latest/api/
- https://pandas.pydata.org/docs/reference/frame.html
- https://docs.pytest.org/en/latest/reference/reference.html
Only those under vdk.API or imported in vdk.api (e.g. vdk.core.context) needs to be documented.
Suggested solution pydoc or sphinx + github pages (e.g https://www.docslikecode.com/articles/github-pages-python-sphinx/)
vmware.github.io can be used as landing page
These are static HTML pages that are served by GitHub from the "gh-pages" branch in each repository.
Simply create a file "index.html" in that branch and it will be displayed on http://vmware.github.io/
https://github.com/vmware/lightwave/tree/gh-pages
https://github.com/vmware/photon/tree/gh-pages
Additional context
This is also needed to meet best practice of https://bestpractices.coreinfrastructure.org/en/projects/5363
The project MUST provide reference documentation that describes the external interface (both input and output) of the software produced by the project. [documentation_interface] The documentation of an external interface explains to an end-user or developer how to use it. This would include its application program interface (API) if the software has one. If it is a library, document the major classes/types and methods/functions that can be called. If it is a web application, define its URL interface (often its REST interface). If it is a command-line interface, document the parameters and options it supports. In many cases it's best if most of this documentation is automatically generated, so that this documentation stays synchronized with the software as it changes, but this isn't required. The project MAY use hypertext links to non-project material as documentation. Documentation MAY be automatically generated (where practical this is often the best way to do so). Documentation of a REST interface may be generated using Swagger/OpenAPI. Code interface documentation MAY be generated using tools such as JSDoc (JavaScript), ESDoc (JavaScript), pydoc (Python), devtools (R), pkgdown (R), and Doxygen (many). Merely having comments in the implementation code is not sufficient to satisfy this criterion; there needs to be an easy way to see the information without reading through all the source code. If the project does not produce software, choose "not applicable" (N/A).
It is arguable as our interfaces are generally separated in vdk.api. so maybe we fix the criteria narrowly. Still, UX would be better if we have Web page in any case.
