Generating examples automatically through custom code

[Fabre Lambeau]

Hi,

I'm new to Sphinx, and have not really started using it. I am thinking of doing so for one of my projects, but need to make sure fist that it can do what I want.

My python package is written in such a way as to allow people to add functionality to it via "plugins". Plugins are written in such a way that they can be automatically discovered at runtime (obviously), but also allow definition of examples. My package is therefore able to go through all plugins, and generate the examples. Currently I have this part of the module generate HTML pages through Jinja2 templates, which embed the output of those examples (as iframes, or images, of text samples).

I would like now to document the main part of the package (general intro, how-to guide, and API doc), but would like to then also be able to have those plugins and examples generated and added to the main documentation, as a separate section.

I looked through dozens of articles, tutorials and YT videos on Sphinx, but could so far not get that question answered.... Is is possible to run custom code as part of the sphinx documentation generation, with the aim of having part of the documentation (pages, part of pages, etc) created?

Hope the question makes sense...

[Eric Larson]

If you want to write Python examples and have them run and rendered in HTML this might work (It is used to generate examples pages for matplotlib, scikit-learn, etc.):

https://sphinx-gallery.github.io

If you want to write notebooks and have them rendered in HTML you could look at:

https://nbsphinx.readthedocs.io

Eric

--
You received this message because you are subscribed to the Google Groups "sphinx-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-users...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/fc6d0d6e-cec9-4c0e-b3ca-45d88974973en%40googlegroups.com.

[Jared Dillard]

The conf.py is a python file, so near the top of that you could run your custom python code that generates additional source files and puts them in the appropriate places in your source directory, then sphinx will build normally.

To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/CAGu2niWf8%2B7J4CNPR1NJR6V5%3D-Ezvtq39uuiF2ez_nsDt8rhKA%40mail.gmail.com.

[Fabre Lambeau]

So if I understand correctly, you suggest that I should have some python code generate RST files and push them to the source directory?  Are there any libs available to help with the generation of RST output?