Open mmcky opened 4 years ago
thanks @chrisjsewell -- its nice to have this supported in jupyter-cache
.
env
to build a json report that can be used for websites. @chrisjsewell the {nb-exec-table}
https://myst-nb--236.org.readthedocs.build/en/236/use/execute.html#execution-statistics looks nice. But, this whole feature of showing statistics looks more like a design/page feature to me than functionality to be written in a directive. I feel like it should be part of sphinx-book-theme
where we explicitly can have common styles for its elements with other elements of the theme. And more flexibility to change its style and easier to edit. For example, having the ability to easily add images or other components like in quantecon
https://python-programming.quantecon.org/status.html for the status symbol.
What do you think?
Well you can do whatever you want with the data 😄, nb-exec-table
is just a reference implementation, but you can just write your own extension to represent it as you wish.
I feel like it should be part of sphinx-book-theme
I don't see it, it is already using the CSS styling for tables that comes from sphinx-book-theme. Or its very easy to just add a CSS class to the created table element, then add additional CSS to style it as you want. What extra does it give you to add it to sphinx-book-theme?
The example in https://python-programming.quantecon.org/status.html, is really no different to the table I create, just with some different CSS and the badges which can be easily added in https://github.com/executablebooks/MyST-NB/blob/c3251a4d93b677f1e67c8ccb3e6d454b93df4c9f/myst_nb/exec_table.py#L90 (or any other elements)
Also, it's very handy to have here for testing and development 😄
@chrisjsewell if one uses nb-exec-table
to generate a status table on a page such as status.md
(which is cool btw -- as a directive can be placed anywhere). What would be the recommended way to support something like status badges
on the header of each individual page that links back to the overall status
page that has the info. That badge
would likely need to be in the theme
template right to be applied across built content
files?
I think @AakashGfude comment re: theme support was motivated by the combination of status
page and status badges
that are spread over all the content pages.
If you want a status badge in a header then yes that may need to have some implementation in sphinx-book-theme. It just might be tricky to figure out how to do that in a way that does not break modularity. I'll leave you to figure that out 😄
But I like the badge links to the individual pages; that wouldn't be too hard to do, using something like https://sphinx-panels.readthedocs.io/en/latest/#link-badges
Thanks, @chrisjsewell for the explanation. True it will be handy for testing and development. I guess what I wanted to mostly point out was the separation of concerns. MyST-NB looks to me more like a repo with functionalities of parsing, rendering, and processing data.
The status I think what I assumed would be a page in itself in a final documentation website. Instead of part of a page. The directive structure is pretty handy, but should we have the directive implementation moved to sphinx-book-theme
? Just trying to get a clearer idea on this. I guess I am thinking more of in a web dev fashion where there is a clear separation between functionality and styling/structure.
As @mmcky pointed out in his last comment, one advantage would be that other parts of the theme using the same images or assets can then be changed from one location only.
It just might be tricky to figure out how to do that in a way that does not break modularity.
Agree -- modularity of config
in the theme layer is something that will be tricky. I guess the simple way is to include optional if-then html support
based on the presence of some config option such as html_enable_status_badge
but perhaps a plugin
approach may be a nicer way to go (saying this from the perspective of very little knowledge of plugins
and html
)
thanks for the link: https://sphinx-panels.readthedocs.io/en/latest/#link-badges link. I guess one option would be to add a badge
via the equivalent of rst_prolog but that may make it really hard to place them in headers etc. Could a theme latch on to a badge with name status_badge
and move it into header if included in the html
?
should we have the directive implementation moved to
sphinx-book-theme
My 2c on this is the directive
is a pretty general tool -- whose output can be styled by sphinx-book-theme
? I guess you could also consider myst_nb
to be the coordinator between jupyter-cache
and jupyter-book
so having the directive in myst_nb
enables the link between these software tools. The alternative is we could have it in its own extension
repo but using it without myst_nb
coordinating the role of jupyter_cache
may be difficult. Is that right @chrisjsewell?
Yes, you can't use it without myst-nb, because among other things (a) auto
execution doesn't use the cache and (b) jupyter-cache won't tell you which notebooks are part of the sphinx documentation.
The data creation, is very much tied to myst-nb (but its visualisation is not).
But anyway, as I say, I think the functionality is all there now to access this data, and nb-exec-table
provides a good demonstration of that from which to build.
So I will leave it up to you to try coming up with an implementation of what you would like to have for quantecon, then we can discuss further 😄
(also remember that people using MyST-NB don't necessarily want to use sphinx-book-theme)
Edit: This has been largely solved in #236, but some iterations can be made on exactly what is stored, including extracting data from the notebook.
Is your feature request related to a problem? Please describe.
Add the option to output a
json
file that could be used to support aexecution
status page on websites such as this quantecon project page.Describe the solution you'd like
output
json
formatted file that can be used as a data source to build status tables inhtml
such as:Describe alternatives you've considered
None I think
jupyter-cache
is a logical place for this to be done as anexecution
managerAdditional context
This is a feature request which will help migrate QuantEcon projects to use
jupyter-book