-
-
Notifications
You must be signed in to change notification settings - Fork 347
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
Render examples using Sphinx-gallery #1621
Conversation
b9d6c54
to
1c47765
Compare
Codecov Report
@@ Coverage Diff @@
## main #1621 +/- ##
==========================================
- Coverage 72.72% 72.71% -0.01%
==========================================
Files 370 370
Lines 56287 56286 -1
Branches 20369 20369
==========================================
- Hits 40932 40931 -1
Misses 12358 12358
Partials 2997 2997
📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more |
9ec9f2e
to
795325b
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@speth … this is terrific. While I believe that your PR over at sphinx-gallery
is making good progress, I have a couple of minor nitpicks (most are lines that touch or are adjacent to pre-existing conditions).
It may make sense to wait what happens with the contribution to the upstream library?
Yes, we can wait to merge this in case there are any API changes requested upstream. I don't think I want to wait for the next release of |
795325b
to
2b902f9
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
As I didn't want to pip install from GitHub repos, I downloaded the artifacts from GH Actions: things look overall great.
The only thing I noticed are mislabeled download buttons (Fortran is not Python and definitely doesn't know Jupyter 😃 ; C++/C/Matlab have the same issue ... not sure whether this needs to be fixed here or upstream):
I also noticed some "FortranFixed" reference that I am not sure about
The "download all" buttons and corresponding zip files are something I still need to fix upstream. For the individual examples, the name is the one used by Pygments (first column here), which uses "Fortran" for F90-style "free format" and "FortranFixed" for the older fixed-width format. I think it's a pretty minor wart. |
Thanks for doing this Ray! I'm happy we'll be able to link to API docs from the examples, and that you've got all the examples building. Once this goes in, I'll rework the ongoing sphinx migration to use this instead of my bespoke solution. |
Thanks for the upstream fix - I retriggered GH actions, and things are taken care of 🎉
Thanks for the explanation. It indeed is a minor wart. |
2b902f9
to
62d35be
Compare
🥳 ... |
This includes just the Python "kinetics" examples to start
Sphinx-gallery creates new .rst files alongside existing manually maintained documentation, and runs the samples in-place, generating their output files in the source tree. Moving this all to the build directory lets us keep the repo clean.
This was causing problems with re-importing cantera.with_units.units while running the samples as part of the sphinx-gallery build
This sidebar usually only had a "get page source" link, which isn't very useful for autogenerated pages.
Introduce a monkey patch to avoid executing specific examples that won't run under sphinx-gallery.
62d35be
to
d317d27
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks, @speth for this substantial addition!
Changes proposed in this pull request
sphinx-gallery
to render the examples.sphinx-tags
to parse the example keywords and create index pages for each tagsphinx-gallery
andsphinx-tags
Notes:
sphinx-gallery
can't run the other language examples (at least for the time being), those galleries are full of the default image.sphinx-gallery
is pretty awesome.sphinx-gallery
that includes a pending PR to introduce the ability to parse examples in languages other than Python.sphinx-tags
that includes a few fixes I introduced. This extension is very small (a single file) so we could just vendor it if we're going to introduce significant customizations.If applicable, fill in the issue number this pull request is fixing
If applicable, provide an example illustrating new features this pull request is introducing
The page for a Python example:
Part of an index page:
Checklist
scons build
&scons test
) and unit tests address code coverage