Hey Aaron and  Anton,

One of MXNet's strengths over other frameworks is the plethora of language
bindings so having language specific examples is of importance. Perhaps
indicating that an example is Python code by using a "#python" header on
the example would make it clear.  Of course, for the important APIs,
docstrings for the most popular languages would be desired. Additionally,
making the holes clear would make it easier for users to contribute
documentation for their favorite languages.


On Mon, Mar 4, 2019 at 8:34 AM Anton Chernov <mecher...@gmail.com> wrote:

> 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 <aaron.s.mark...@gmail.com>:
> > 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
> >

Reply via email to