Improve stored execution statistics

[mmcky]

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 a execution 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 in html such as:

{ "results": 
    [   {"filename": "404", "runtime": "0:01.4", "num_errors": 0, "extension": "py", "language": "python3"}, 
        {"filename": "about_lectures", "runtime": "0:00.8", "num_errors": 0, "extension": "py", "language": "python3"}, 
        {"filename": "about_py", "runtime": "0:03.5", "num_errors": 0, "extension": "py", "language": "python3"},
        ...
        {"filename": "writing_good_code", "runtime": "0:03.5", "num_errors": 0, "extension": "py", "language": "python3"}
    ], 
"run_time": "16-08-2020 01:07:01"}

Describe alternatives you've considered

None I think jupyter-cache is a logical place for this to be done as an execution manager

Additional context

This is a feature request which will help migrate QuantEcon projects to use jupyter-book

[mmcky]

thanks @chrisjsewell -- its nice to have this supported in jupyter-cache.

• [ ] work on extracting data from env to build a json report that can be used for websites.

[AakashGfude]

@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?

[chrisjsewell]

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)

[chrisjsewell]

Also, it's very handy to have here for testing and development 😄

[mmcky]

@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.

[chrisjsewell]

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

[AakashGfude]

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.

[mmcky]

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?

[mmcky]

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?

[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)