search

rochefort-lab / fissa

A Python toolbox for Fast Image Signal Separation Analysis, designed for Calcium Imaging data.
GNU General Public License v3.0
30 stars 28 forks source link

DOC: Incorporate notebooks into Sphinx docs using nbsphinx #273

Closed scottclowe closed 2 years ago

scottclowe commented 2 years ago

This PR integrates the notebooks into the Sphinx-generated documentation pages that appear on readthedocs. To do this, we convert the .ipynb files into rST documentation using nbsphinx.

The original notebooks are left as they were, but with a few minor modifications so that the markdown gets converted into rST correctly.

The documentation files all have to be in the docs folder for them to be built. For the basic and CNMF notebooks I have added a symlink in docs/examples/ which points to the .ipynb file in examples/, and also for the exampleData and cNMFdata.mat dependencies.

Because the SIMA and Suite2p notebooks have challenging dependencies, we can't run these from scratch when building the documentation. Instead, we include notebooks which already have all their outputs in place within docs/examples/. The default behaviour of nbsphinx is to execute notebooks which don't contain any outputs already, so these are left unchanged and don't trigger an error when sphinx fails to run them. In order to stop nbstripout from removing these outputs, I have set the notebook metadata to contain "keep_output": true. It was not possible to stop nbstripout from removing cell execution counts just for these two notebooks though, so I've disabled it from striping this out from every notebook (which is not ideal).

I was not able to get ammaraskar/sphinx-action working with the pandoc dependency of nbsphinx, and have dropped the docs workflow. The documentation is complied in the tests workflow, and the notebooks are still converted to HTML outputs by the gh-pages workflow.

review-notebook-app[bot] commented 2 years ago

Check out this pull request on  ReviewNB

See visual diffs & provide feedback on Jupyter Notebooks.

Powered by ReviewNB

codecov[bot] commented 2 years ago

Codecov Report

Merging #273 (e709eb9) into master (6b3b320) will increase coverage by 0.01%. The diff coverage is n/a.

@@            Coverage Diff             @@
##           master     #273      +/-   ##
==========================================
+ Coverage   94.29%   94.30%   +0.01%     
==========================================
  Files           8        8              
  Lines        1209     1212       +3     
  Branches      310      311       +1     
==========================================
+ Hits         1140     1143       +3     
  Misses         35       35              
  Partials       34       34
Flag Coverage Δ
nbsmoke 60.31% <ø> (+0.09%) :arrow_up:
unittests 93.97% <ø> (+0.01%) :arrow_up:

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files Coverage Δ
fissa/neuropil.py 95.38% <0.00%> (+0.22%) :arrow_up:

Continue to review full report at Codecov.

Legend - Click here to learn more Δ = absolute <relative> (impact), ø = not affected, ? = missing data Powered by Codecov. Last update 6b3b320...e709eb9. Read the comment docs.