pyro-ppl/pyro

Render code examples automatically with sphinx_gallery

Open

#2,670 opened on Oct 14, 2020

View on GitHub
 (5 comments) (4 reactions) (0 assignees)Python (981 forks)batch import
Examplesgood first issuehelp wantedwebsite

Repository metrics

Stars
 (8,211 stars)
PR merge metrics
 (Avg merge 10d 19h) (1 merged PR in 30d)

Description

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.

Contributor guide

Research direction
Familiarize yourself with sphinx gallery and its configuration. Look at how NumPyro has set up their examples in their repository (numpyro/examples). Then, explore the current tutorial structure in Pyro at tutorial/source/ and identify which .rst files need to be replaced. Plan the migration and test with a single example first.
Tech stack
python
Domain
documentation
Issue type
Feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
Half day
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
Active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
Clear
Prerequisites
GitPython
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
65