docs!: switch to sphinx-book-theme #209
Conversation
|
Been meaning to do this. Thanks for the push towards this - done.
Actually just discovered nbQA because it's author just starred this repo 😮 - looks great big supporter of this
Will look at this more thoroughly tomorrow. and again deep thanks for all the wonderful work |
|
Check out this pull request on See visual diffs & provide feedback on Jupyter Notebooks. Powered by ReviewNB |
😆 incidentally I discovered |
This substitutest the original nbsphinx_prolog
This allows moving the examples directory
This is required to get the Binder thebe links working. Some other major changes: * gifmaker.py has been removed. Instead, gifs and apngs are included as a markdown cell. This also nice, because you can see the gifs while working on the notebooks in Jupyter. * Input cells with "gif" metadata now have a tag "remove-output", so that the subsequent Markdown cell with gif looks like the cell output when generating using jupyter_execute_notebooks. * Sphinx-autobuild can now also trigger on changes to the examples notebooks (had to be excluded before because of copied files from the gifmaker)
These two tracked files are annoying to git, because they are overwritten each time the notebooks are run
It's now possible to run the notebooks and generate cell outputs by setting the EXECUTE_NB variable (to anything) or using tox -e docnb
Document names determine the URLs. It's best to keep these short and usually URLs are all lower-case.
For margin and toggle directives
Otherwise the main content ends up being weirdly small See: https://github.com/executablebooks/sphinx-book-theme/blob/547cc95674623345124d9bbea9e15e5b5fa34d0e/docs/conf.py#L62 https://sphinx-panels.readthedocs.io/en/latest/index.html?highlight=panels_add_bootstrap_css#sphinx-configuration
for more information, see https://pre-commit.ci
This has been an uhhhh extremely permissive definition of tomorrow :( Sorry about that, looking now!
I guess this may be down to personal preference but I don't love this. I did this because I wanted the docs to be different as presented in the docs vs when used interactively. So for example in https://mybinder.org/v2/gh/redeboer/mpl-interactions/sphinx-book-theme?urlpath=lab/tree/docs/examples/ when you run the cells you end up with the GIF and the actual interactive output. Overall it's just a small nit though and this is great so I'm going to go ahead and merge - thank you again! As an aside I think the ultimate solution to interactive docs here is not to muck around with recording and embedding gifs but to have the whole docs be interactive using: jupyterlite (wasm powered full python kernel) which may be achievable via https://jupyterlite.readthedocs.io/en/latest/deploying.html?highlight=sphinx but that's probably a project for another day. |
Hahaha no worries 😅
Thanks for writing out your thoughts here! I also need some easier way to have this interactivity directly available in the browser, so I'd also be interested in something like jupyterlite. But for now, as you say, it is indeed more a matter of preference of how to get these gifs in the docs. I think in terms of maintenance it is a bit clearer if the gifs are explicitly added through the markdown rather than the (less accessible) cell metadata and further logic that is implemented in the |
|
Some relevant issues: jupyter-book/thebe#412 |
Documentation is now built with the sphinx-book-theme. Main reason is that it works much better for Jupyter notebooks, particular in combination with sphinx-thebe. That solves the
nbsphinx_prologissue mentioned in #208.Have a look at the preview here
Some related changes:
examplesfolder had to be moved todocs, because the launch buttons then lead you directly to the correct notebook on Binder.