Where do I put examples and refer them from /docs/source/?

[vstadnytskyi]

I have figured out that you can have examples in the docstring, by adding a line.

.. plot:: examples/numerical_bin_data.py
           :include-source:

This is a very nice way to create good documentation. However, it requires to run a script which creates a figure. I decided to put the script in the /examples/ folder. I put /examples/ into docs/source/examples/. However, It would be nice to have examples in the home directory. It will be easier to find and easier to refer to. Is there a way to put /examples/ in the home directory and refer to them from files down the tree?

Here is the link to documentation generated with a plot build in.

[mrakitin]

This is a good find! We are using the plot directive at https://blueskyproject.io/bluesky/plans.html, but without including the source from the files. I am not sure if sphinx can understand relative paths... @danielballan, have you encountered this use case?

On a similar topic: we exploited the cookbook feature of sphinx for the examples (e.g., http://nsls-ii.github.io/cookbook/index.html). The source of the examples can be found at https://github.com/NSLS-II/docs/tree/master/source/_cookbook. Can it serve as a replacement?

[danielballan]

Good question. Yes, sphinx understand relative paths, so you can locate your examples in the root (i.e. top-level) directory of the repository, or wherever you like.

See a working example, albiet with the literalinclude directive rather than plot, in here https://raw.githubusercontent.com/bluesky/event-model/master/docs/source/data-model.rst

(Ctrl+F for literalinclude.)

[danielballan]

P.S. Since @mrakitin brought up sphinx-gallery (the extension behind our "cookbook") --- it has been proposed to recommend this here in the cookiecutter. #36

I'm 50/50 on whether it's worth adding to this guide. I like sphinx-gallery, but I hesitate to expand the number of recommended tools to the point that it could overwhelm newcomers to the scipy ecosystem. However, if someone felt inspired to open a PR addressing it, I think I would merge it. :-)