Skip to content

Render code examples automatically with sphinx_gallery #2670

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
eb8680 opened this issue Oct 14, 2020 · 3 comments
Open

Render code examples automatically with sphinx_gallery #2670

eb8680 opened this issue Oct 14, 2020 · 3 comments
Labels
Examples good first issue help wanted Issues suitable for, and inviting external contributions website
Milestone

Comments

@eb8680
Copy link
Member

eb8680 commented Oct 14, 2020

Currently our non-notebook examples are manually included in the examples webpage via custom .rst files in tutorial/source/. As the number of examples increases, it would be better to follow NumPyro's approach and generate HTML pages automatically with sphinx_gallery. This would make examples easier to find and read, improve the design of the tutorial page, and declutter our tutorial folder on GitHub. Many of the examples also contain extensive docstrings and comments that sphinx_gallery could automatically render in HTML.

More ambitiously, we might even aim to use sphinx_gallery to include tutorials in ReadTheDocs, simplifying our release process and removing the lag between new tutorials being added on GitHub and becoming visible on the examples web page.

@eb8680 eb8680 added help wanted Issues suitable for, and inviting external contributions website Examples good first issue labels Oct 14, 2020
@eb8680 eb8680 added this to the 2.0 release milestone Oct 14, 2020
@fehiepsi
Copy link
Member

More ambitiously, we might even aim to use sphinx_gallery to include tutorials in ReadTheDocs, simplifying our release process and removing the lag between new tutorials being added on GitHub and becoming visible on the examples web page.

This is what I wanted for a long time!

@eb8680
Copy link
Member Author

eb8680 commented Nov 5, 2020

This worked really well in NumPyro, so hopefully we can just copy the sphinx_gallery boilerplate from there and set up similar redirects to keep links alive.

@fritzo
Copy link
Member

fritzo commented Jan 4, 2021

As motivation, I forgot to manually update tutorials during Pyro's 1.5.1 release, so users like @lucapinello experienced errors. Indeed it would be nice to automate this and eliminate possibility of human error.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Examples good first issue help wanted Issues suitable for, and inviting external contributions website
Projects
None yet
Development

No branches or pull requests

3 participants