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