docs updates

[Aaron Markham <aa...@gmail.com>]

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

Re: docs updates

[Pedro Larroy <pe...@gmail.com>]

Hi Aaron.

I'm no design expert, but wouldn't smoothing out the boxes a bit
rounding the corners would make the design more pleasant?

As an old fart learning from Knuth books, I'm all pro having
documentation as close to the source as possible. Could you maybe put
two concrete examples so the documentation noobs like me can
understand a bit more what you mean?

Thanks.


On Fri, Apr 19, 2019 at 6:02 PM Aaron Markham <aa...@gmail.com> wrote:
>
> 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