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 docs updates
Date Sat, 20 Apr 2019 01:02:29 GMT
Hello everyone!
I've been pecking away at adding content to the beta site. Take a look
and let me know what you think. Right now, I'm focused 100% on the
content and the organization thereof.

One feature I thought would be great for the API docs would be to
cross-reference usage of a particular function with an example or
tutorial. As I researched approaches I found sphinx-gallery [2]
already supports this.

When trying to apply this to some examples we have I ran across an
issue [3] that many examples don't run out of the box. This prevents
sphinx-gallery from doing its magic.

My question to you all is: what you think of having .py files as a
primary source of example usage and to generate notebooks and web
pages from those. This is as opposed to .md files that get converted
to notebooks and then html. GluonCV's site uses this and it seems to
work pretty well for generating the tutorial web pages from the .py
files. The implication is fixing many examples to run when executed by
Sphinx. The remainder would have to be excluded and wouldn't be a
source of example usage in the docs.

Cheers,
Aaron

[1] https://beta.mxnet.io/
[2] https://sphinx-gallery.github.io/configuration.html#auto-documenting-your-api-with-links-to-examples
[3] https://github.com/apache/incubator-mxnet/issues/5717

Mime
View raw message