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
