Unified docs for PySAP

[sfarrens]

Summary

• closes #173
• added documentation structure similar to that in ModOpt
  • including sphinx templates
• updated CD and added manual build action for checking the API docs
  • all plug-in api docs are built along with examples
• abstracted the definition of PySAP plug-ins
  • now defined in plugins.txt
  • removed from pysap/info.py
• removed plug-in examples
  • astro examples moved to pysap-astro/examples
• updated .gitignore
• added sphinx gallery for examples
  • added custom CSS to change styling
• updated PySAP docstrings to show the correct data types

Notes

• you can find example of the manual API docs build here (available for 2 weeks only)
• note that the Astro examples have run correctly and all objects link to the appropriate API documentation (including ModOpt)
  • in order for this to work (with the current set up) plug-in examples need to import the plug-in directly and not use the pysap.plugins (e.g. from astro import ... not from pysap.plugins.astro import ...)
  • we should discuss this before merging
• There is a lot of duplicated code in the standard CD and manual API docs actions
  • this can be refined in a future PR to reuse certain actions more efficiently

[codecov-commenter]

Codecov Report

Merging #174 (1235618) into develop (ae34ae4) will increase coverage by 0.03%. The diff coverage is 33.33%.

@@             Coverage Diff             @@
##           develop     #174      +/-   ##
===========================================
+ Coverage    61.88%   61.91%   +0.03%     
===========================================
  Files           30       31       +1     
  Lines         1658     1670      +12     
===========================================
+ Hits          1026     1034       +8     
- Misses         632      636       +4     

Flag	Coverage Δ
unittests	61.91% <33.33%> (+0.03%)	:arrow_up:

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

Impacted Files	Coverage Δ
pysap/base/loaders/mat.py	50.00% <ø> (ø)
pysap/base/observable.py	45.00% <ø> (ø)
pysap/base/transform.py	71.70% <ø> (ø)
pysap/base/utils.py	35.00% <ø> (ø)
pysap/configure.py	27.77% <ø> (ø)
pysap/data.py	69.11% <ø> (ø)
pysap/extensions/formating.py	19.63% <0.00%> (ø)
pysap/extensions/sparse2d.py	100.00% <ø> (ø)
pysap/extensions/tools.py	52.94% <ø> (ø)
pysap/extensions/transform.py	71.10% <ø> (ø)
... and 6 more

---

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 b66338f...1235618. Read the comment docs.

[paquiteau]

Hi, great work, the documentation looks awesome !

After a quick browsing I found a few minors details that could be improved:

• The look of the Download buttons for the examples could be tweaked to blend more in the aesthetic of the all documentation (that's just a bit of css tweaking for the div.sphx-glr-download a element: Before /After mockup (I used LightBlue as a background color)

• The See Also links does not work (example: mri.reconstructors.self_calibrating), but I might be due to the docstring not referencing the full path).
• Idem the link in docstrings for "np.ndarray" is not working , but I guess it should be numpy.ndarray ?

[sfarrens]

Hi @paquiteau, thanks for the feedback!

• Cool, I will have a look at playing with the colour options for these buttons. Thanks for the tip!
• I did not dig too deep into the MRI API docs, but I did notice a lot of aliases. This also causes some issues with the examples so we should probably look into it on the pysap-mri repo.
• Yes all of the np.ndarray need to be updated to numpy.ndarray. I already sorted this out for PySAP-Astro but all of the plug-in developers will need to check these things.

[paquiteau]

I guess the look and organization of the documentation is good enough to be merged now (and will unlock #179). If there are any docstrings improvement to be made, it can be deferred to future PRs.