How do you keep documentation so nice?

[Tony Yu]

Hi Adam!

On Mon, Dec 8, 2014 at 5:40 PM, Adam Hughes <hughesadam87 at gmail.com> wrote:

> I really am impressed by this plt2rst.py module for autogenerating example
> documentation!
>
> I've been trying to implement it just to test it out and think I have it
> setup right in terms of placement in my docs directory, I made an example
> plot_test.py file in examples, but I'm confused on how to actually use the
> plt2rst.py module.  Consider this line from that file:
>
>     def setup(app):
>         app.connect('builder-inited', generate_example_galleries)
>
>         app.add_config_value('plot2rst_paths',
>                          ('../examples', 'auto_examples'), True
>
> When/how is this ever called?  The examples themselves don't use these
> directives; so when is this found?
>

This plotting code is partially my fault, so I'll try to explain based on
memory. I should say, though, that I adapted this code from an older
version in the `scikit-image` docs, which took it from `scikit-learn`
(which may have taken it from nipy or some other project). That is to say,
I don't completely understand all the things. ;)

This particular `setup(app)` function is run as part of the Sphinx
infrastructure (see http://sphinx-doc.org/extdev/tutorial.html).


> When I build in my make file, no auto_examples.html file is ever created
> in my build directory.  So I'm thinking I'm not using this correctly.  Is
> there another step besides just doing make build?
>

There's a bit of documentation written up here:

https://github.com/tonysyu/mpltools/blob/master/doc/source/getting_started.rst#plot2rst-sphinx-extension

One possible hang-up is that examples are expected to start with `plot_`
and an `index.rst` file is required in gallery directories.

I haven't looked at this in a while, but if you have any more questions, I
can try to dig into the code a bit to try to remember what's going on.

Cheers!
-Tony
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scikit-image/attachments/20141208/8efaf99f/attachment.html>