Fix and update model_details notebooks

[jessica-mitchell]

This PR moves the model_details notebooks up to top level of hierarchy in htmldoc and fixes issues with rendering of the LaTeX math.

To do this the notebooks were converted to a reStructured text file and output as pngs,
A download link for each notebook was added using a zip file. A direct download of a notebook is not obviously possible with reStructuredText- (if one uses the :download: role with a .ipynb file, the raw notebook code opens).

See for example: https://nest-test.readthedocs.io/en/fix-notebooks-docs/model_details/HillTononiModels.html

Note:
The model_details folder is currently not indexed and not discoverable through the table of contents. They are linked in the respective models/ documentation.

The only notebook not changed is the aeif_models_implementation.ipynb because it does not execute properly. See issue #2454 .

[heplesser]

@jessica-mitchell Thanks a lot for this PR! I see three issues with the current state of the PR

1. The figures render extremely small in both Safari and Firefox on macOS.
2. I would like to keep the notebooks as the primary documents, so that one can easily modify them if needed. RST-files and zip archives should then be automatically generated from the notebooks. Would this be feasible?
3. Also, adding zip archives and generated figures to Git risks clogging the repo with binary files as these files evolve. Can we avoid it and just "make" those files on our documentation server?

[jessica-mitchell]

@jessica-mitchell Thanks a lot for this PR! I see three issues with the current state of the PR

1. The figures render extremely small in both Safari and Firefox on macOS.

Sorry, this is because it is not up-to-date with master!

2. I would like to keep the notebooks as the primary documents, so that one can easily modify them if needed. RST-files and zip archives should then be automatically generated from the notebooks. Would this be feasible?

This is a fair point, but I had trouble getting the HTML rendered notebook to generate proper latex and the restructured text version worked easily. I will take another look to see how I can fix it using the notebook as source.

3. Also, adding zip archives and generated figures to Git risks clogging the repo with binary files as these files evolve. Can we avoid it and just "make" those files on our documentation server?

Making these files with sphinxgallery is possible, but it expects a python source. There are other ways I'm sure, which I can look into more.

[jessica-mitchell]

@heplesser I looked into this more and discovered that basically the broken equations were missing $$. This seems to resolve the HTML rendering without affecting the output in a notebook running in Jupyter lab. I also updated the mathjax js in the conf, which I dont think did anything but figured we should avoid using outdated versions.

[jessica-mitchell]

@heplesser I'm afraid there are some further issues after checking Read the docs rendering which do not seem straightforward

[med-ayssar]

In The neuron emits a single spike if we should a line break before the unordered list, otherwise; it won't be rendered as a list.
Same for Upon spike emission

[med-ayssar]

Side note, the space and position of the references at the bottom do not seem right.

Space problem in aeif_psc_delta_clopath.html

Position Problem in siegert_neuron.html

Why not simply use the horizontal representation for the references.

[jessica-mitchell]

Space problem in aeif_psc_delta_clopath.html

Can you be more specific? I see a broken link in the third reference ...

Position Problem in siegert_neuron.html

Again, I dont see a problem, can you provide more details or screen shot?

Why not simply use the horizontal representation for the references.

What do you mean by horizontal representation?

[med-ayssar]

I do not know if the problem of some settings I have in my local machine, but when building the docs, the references look like that:

They are vertical (going from top to bottom), and there is not enough space between columns. I tried building the docs with the current master and also this branch, and I have the same output.

[med-ayssar]

I just found another list that is not rendered correctly.

Missing new line before start of list at Line 250 and at Line 1233

$I_h$ is not always written in latex mode. (see Line 365, Line 911 and Line 1058)

$h_{\infty}$ and $m_{\infty}$ also are not in latex mode: Line 1061

[med-ayssar]

Otherwise, the rest looks good to me.

[jessica-mitchell]

They are vertical (going from top to bottom), and there is not enough space between columns. I tried building the docs with the current master and also this branch, and I have the same output.

Ah this problem, yes this is rendered properly on Read the docs so I didnt notice it, but you're right, in the local build, something strange happens. I have it on my to do list to look into.

[jessica-mitchell]

Fixes #2404

[heplesser]

@jessica-mitchell Looks good overall, just a few smaller comments.

[heplesser]

Looks good now except for formatting error and merge conflict.

[jessica-mitchell]

@med-ayssar Can you do a final review or approve if looks good? Thanks!

[med-ayssar]

Looks good!