Hi Aaron, Here is an idea: The main documentation is the one in .cc files. In theory the language bindings should just override some stuff from it, like examples. If I understand correctly there is a sphinx script that generates the documentation. If run it first for core src folder and then from a language binding folder it could use the -f, --force flag [1] to override the needed parts. That would allow to provide a 'default' version of the documentation, that could be adjusted where needed.
Best Anton [1] http://www.sphinx-doc.org/en/stable/man/sphinx-apidoc.html#sphinx-apidoc-manual-page вт, 26 февр. 2019 г. в 02:20, Aaron Markham <[email protected]>: > Hi everyone, > A recent issue and pending PR has brought a thorny docs situation to > my attention again and I'd like to hear from the community on how to > proceed. > We currently get some of the docs for the Python API pulled out of .cc > files. Other APIs also get docs from there, or pull the Python docs to > autogenerate their docs. This presents some problems: > 1. (Some of) The code examples provided don't run when you copy and > paste them. [1] > 2. The code examples that show up in other APIs won't work as the code > is Python and for (many/complicated) statements the syntax can be > wrong. > > When I try out something new and go for the hello world example or > browse around I do expect the docs' code examples to work. If they > don't, well, that's a bad sign and I move on to another project. I'd > like for new users to have a great experience no matter what language > they use. > > One fix is to go ahead a be "Python 1st" and make sure the code > executes. This route is proposed in a PR for some NDArray operators. > [2] As I mention in the PR comments, this has the drawback of being > very specific to Python and the psuedo-code, for what its worth, > showing up in Scala docs (for example) will be much more obviously out > of place. If I were an Scala person, I'd probably find this > irritating. The same goes for R. > > So... what should we do? Here are some ideas: > a) I thought about providing different examples in the .cc code, one > for each language and then making sure those are parsed out properly > when the APIs are generating their docs. I'm not sure how feasible > this is. > b) I thought that it would be nice if each operator had a wrapper for > each language API, and this is where the example payload resides. > Maybe docstrings go here too or the common docstrings just bubble up > from the cc file. The benefit is that changes for a specific language > remain in those packages and don't touch the shared core files. > c) Another route is to keep the examples in the .cc files pseudo-code, > but then also make sure each language has real examples in their docs. > Then, any code block that's in the docs now that won't execute should > be changed to a preformatted text block so people don't confuse it > with functional code. > > I really don't like any of these options as they each sound like ton > of work and difficult to maintain. Are there any projects that solve > this problem in some elegant and efficient way? > > Cheers, > Aaron > > [1] https://github.com/apache/incubator-mxnet/issues/14232 > [2] https://github.com/apache/incubator-mxnet/pull/14243 >
