search

spatialaudio / nbsphinx

:ledger: Sphinx source parser for Jupyter notebooks
https://nbsphinx.readthedocs.io/
MIT License
451 stars 130 forks source link

Feature idea: Url references for each cell #576

Open kolibril13 opened 3 years ago

kolibril13 commented 3 years ago

I just wrote some tutorials with nbsphinx, and thought that it would be really great, if every single cell could be navigated to via url. Currently, I only saw an option for references for markdown titles: https://flyingframes.readthedocs.io/en/v0.7.0-beta/ch2.html#get-positions This is great, but when a notebook contains a lot of cells, it would be really convenient to reference to a certain cell e.g. by https://flyingframes.readthedocs.io/en/v0.7.0-beta/ch2.html#cell24

mgeier commented 3 years ago

The problem with this would be that it is very likely that those links become outdated (because of cell insertions and deletions).

Also, what number would you use? The "execution count" or the internal (0-based) cell number. In general, they don't coincide. It might be confusing to have a link containing a number that's different from the number displayed on the page.

Does nbconvert do that? If not, has this suggestion been considered over there?

kolibril13 commented 3 years ago

I think the main purpose of this feature is to share code references from certain versions of the docs. And yes, on the readthedocs build form the main branch these might get outdated, however for specific release versions of the docs, the links won't break. In my opinion, the execution count would be the way to go here.

Does nbconvert do that? If not, has this suggestion been considered over there?

I've never worked with that, so I have no idea.