mxnet-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Aaron Markham <aaron.s.mark...@gmail.com>
Subject direction for documentation across various APIs that share common doc source
Date Tue, 26 Feb 2019 01:20:22 GMT
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

Mime
View raw message