Major documentation update, including tutorials

vortex-exoplanet · Mar 24, 2022 · aa4af0e · aa4af0e
1 parent f3b41ee
commit aa4af0e
Show file tree

Hide file tree

Showing 27 changed files with 528 additions and 298 deletions.
diff --git a/README.rst b/README.rst
@@ -235,7 +235,7 @@ Attribution
 -----------
 Please cite `Gomez Gonzalez et al. (2017) <https://ui.adsabs.harvard.edu/abs/2017AJ....154....7G/abstract>`_ whenever 
 you publish data reduced with ``VIP`` . Astrophysics Source Code Library reference [ascl:1603.003].
-In addition, please cite the relevant publications for the algorithms you use (often mentioned in the documentation of VIP routines, e.g. `Marois et al. 2006 <https://ui.adsabs.harvard.edu/abs/2006ApJ...641..556M/abstract>`_ for median-ADI).
+In addition, please cite the relevant publication(s) for the algorithms you use within VIP (usually mentioned in the documentation, e.g. `Marois et al. 2006 <https://ui.adsabs.harvard.edu/abs/2006ApJ...641..556M/abstract>`_ for median-ADI).
 
 
 Note: The ``specfit`` module, previously part of VIP, has now been moved to a separate `GitHub repository <https://github.com/VChristiaens/special>`_.
diff --git a/docs/source/_static/logo.png b/docs/source/_static/logo.png
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -42,7 +42,8 @@
     'sphinx.ext.mathjax',
     'sphinx.ext.viewcode',
     'sphinx.ext.napoleon',
-    'nbsphinx'
+    'nbsphinx',
+    'sphinx_thebe'
     # 'sphinx.ext.githubpages',
 ]
 
@@ -138,16 +139,16 @@
 # a list of builtin themes.
 #
 #html_theme = 'classic'
-html_theme = 'sphinx_book_theme'
-#html_theme = 'sphinx_rtd_theme'
+#html_theme = 'sphinx_book_theme'
+html_theme = 'sphinx_rtd_theme'
 #html_theme = 'bizstyle'
 #html_theme = 'alabaster'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-#html_theme_options = {
+html_theme_options = {
     ### for alabaster theme
     # 'logo': 'logo.png',
     # 'logo_name': True,
@@ -167,18 +168,20 @@
 
     ### for bizstyle theme
     #'rightsidebar': True
-html_theme_options = {
-    'path_to_docs': 'docs/source',
-    'repository_url': 'https://github.com/vortex-exoplanets/VIP',
-    'repository_branch': 'main',
-    'launch_buttons': {
-        'binderhub_url': 'https://mybinder.org/v2/gh/vortex-exoplanet/VIP_extras/master',
-        'notebook_interface': 'jupyterlab',
-    },
-    'use_edit_page_button': True,
-    'use_issues_button': True,
-    'use_repository_button': True,
-    'use_download_button': True,
+
+    ### for sphinx_book theme
+    # 'path_to_docs': 'docs/source',
+    # 'repository_url': 'https://github.com/vortex-exoplanets/VIP',
+    # 'repository_branch': 'main',
+    # 'launch_buttons': {
+    #     'binderhub_url': 'https://mybinder.org/',#'v2/gh/vortex-exoplanet/VIP_extras/master',
+    #     'notebook_interface': 'jupyterlab',
+    #     "thebe": True,
+    # },
+    # 'use_edit_page_button': True,
+    # 'use_issues_button': True,
+    # 'use_repository_button': True,
+    # 'use_download_button': True,
     'logo_only': True,
 }
 
@@ -197,7 +200,7 @@
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
 #
-html_logo = '_static/logo.jpg'
+html_logo = '_static/logo.png'
 
 # The name of an image file (relative to this directory) to use as a favicon of
 # the docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32

diff --git a/docs/source/faq.rst b/docs/source/faq.rst
@@ -1,7 +1,10 @@
+Frequently asked questions
+--------------------------
 
-FAQ
----
-First things first. Please make sure you have the latest version of ``VIP``.
+Check out the FAQ if you encounter problems when installing or running ``VIP``
+for the first time.
+
+Before skimming this list, please make sure you have the latest version of ``VIP``.
 Please go and check the repository now. Alternatively, you can run:
 
 .. code-block:: bash

diff --git a/docs/source/gen_index.rst b/docs/source/gen_index.rst
@@ -0,0 +1,4 @@
+Index
+-----
+* :ref:`genindex`
+* :ref:`modindex`
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -7,44 +7,48 @@
    :align: center
    :width: 400px
 
-.. toctree::
-   :maxdepth: 3
-   :caption: Getting started
-
-Introduction
+What is VIP?
 ------------
-
-``VIP`` is a python package for angular, reference star and spectral
-differential imaging for exoplanet and disk high-contrast imaging. ``VIP`` is
-compatible with Python 3.7, 3.8 and 3.9 (Python 2 compatibility dropped with ``VIP`` 0.9.9).
-
-.. image:: https://github.com/carlgogo/carlgogo.github.io/blob/master/assets/images/vip.png?raw=true
-    :alt: Mosaic of S/N maps
+``VIP`` stands for Vortex Image Processing. 
+It is a python package for high-contrast imaging of exoplanets and circumstellar disks. 
+``VIP`` is compatible with Python 3.7, 3.8 and 3.9 (Python 2 compatibility dropped with ``VIP`` 0.9.9).
 
 The goal of ``VIP`` is to integrate open-source, efficient, easy-to-use and
 well-documented implementations of high-contrast image processing algorithms to
 the interested scientific community. The main repository of ``VIP`` resides on
 `GitHub <https://github.com/vortex-exoplanet/VIP>`_, the standard for scientific
 open source code distribution, using Git as a version control system.
 
-``VIP`` started as the effort of `Carlos Alberto Gomez Gonzalez <https://carlgogo.github.io/>`_,
+The project started as the effort of `Carlos Alberto Gomez Gonzalez <https://carlgogo.github.io/>`_,
 a former PhD student of the `VORTEX team <http://www.vortex.ulg.ac.be/>`_
-(ULiege, Belgium). ``VIP``'s development has been led by Dr. Gomez with contributions
+(ULiege, Belgium). ``VIP``'s development has first been led by Dr. Gomez with contributions
 made by collaborators from several teams (take a look at the 
 `contributors tab <https://github.com/vortex-exoplanet/VIP/graphs/contributors>`_ on
-``VIP``'s GitHub repository). It is now maintained by Dr. Valentin Christiaens.
+``VIP``'s GitHub repository). It is now maintained and developed by Dr. Valentin Christiaens.
 Most of ``VIP``'s functionalities are mature but
 it doesn't mean it's free from bugs. The code is continuously evolving and
 therefore feedback/contributions are greatly appreciated. If you want to report
 a bug or suggest a functionality please create an issue on GitHub. Pull
 requests are very welcomed!
 
-.. include:: trimmed_readme.rst
+.. image:: https://github.com/carlgogo/carlgogo.github.io/blob/master/assets/images/vip.png?raw=true
+    :alt: Mosaic of S/N maps
 
 .. toctree::
    :maxdepth: 2
+   :caption: Getting started
+   :hidden:
+
+   trimmed_readme_1
+   trimmed_readme_2
+   trimmed_readme_3
+
+.. toctree::
+   :maxdepth: 3
    :caption: Tutorials
+   :hidden:
 
+   tuto_link
    tutorials/01_quickstart.ipynb
    tutorials/02_preproc.ipynb
    tutorials/03_psfsub.ipynb
@@ -55,54 +59,19 @@ requests are very welcomed!
    tutorials/08_datasets_as_objects.ipynb
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 2
    :caption: About
+   :hidden:
 
-Frequently asked questions
---------------------------
-Check out the FAQ if you encounter problems when installing or running ``VIP``
-for the first time.
-
-.. include:: faq.rst
-
-.. include:: about.rst
+   trimmed_readme_5
+   trimmed_readme_4
+   faq
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 2
    :caption: Package content
-
-On the links below you can find the subpackages structure and access the
-docstrings (internal documentation) of each one of ``VIP``'s functions.
-
-``VIP`` implements basic image processing functionalities such as image
-registration, rotation, shift, rescaling, pixel temporal and spatial
-subsampling. On top of that several pre-processing functions are available
-such as recentering and bad frame removal.
-
-For Angular differential imaging (ADI) data several point spread function
-subtraction techniques are available: pairwise frame differencing, median
-subtraction, least-squares combination, NMF and PCA based algorithms. PCA
-methods are implemented in different flavours. Also PCA can process RDI and
-multiple channel SDI (IFS) data. ``VIP`` contains an implementation of the Local
-Low-rank plus Sparse plus Gaussian-noise decomposition (LLSG, Gomez Gonzalez et
-al. 2016).
-
-Functions for signal-to-noise ratio (S/N) estimation and S/N map generation are
-included, as well as injection of fake companions in 3D and 4D cubes. Flux and
-position of point-like sources are estimated using the Negative Fake Companion
-technique. ``VIP`` also implements algorithm throughput and contrast-curve
-generation routines.
-
-.. toctree::
-   :maxdepth: 3
+   :hidden:
 
    vip_hci
-
-
-API
----
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   gen_index
 
diff --git a/docs/source/package_structure.rst b/docs/source/package_structure.rst
@@ -0,0 +1,23 @@
+Structure
+---------
+On the links below you can find the subpackages structure and access the
+docstrings (internal documentation) of each one of ``VIP``'s functions.
+
+``VIP`` implements basic image processing functionalities such as image
+registration, rotation, shift, rescaling, pixel temporal and spatial
+subsampling. On top of that several pre-processing functions are available
+such as recentering and bad frame removal.
+
+For Angular differential imaging (ADI) data several point spread function
+subtraction techniques are available: pairwise frame differencing, median
+subtraction, least-squares combination, NMF and PCA based algorithms. PCA
+methods are implemented in different flavours. Also PCA can process RDI and
+multiple channel SDI (IFS) data. ``VIP`` contains an implementation of the Local
+Low-rank plus Sparse plus Gaussian-noise decomposition (LLSG, Gomez Gonzalez et
+al. 2016).
+
+Functions for signal-to-noise ratio (S/N) estimation and S/N map generation are
+included, as well as injection of fake companions in 3D and 4D cubes. Flux and
+position of point-like sources are estimated using the Negative Fake Companion
+technique. ``VIP`` also implements algorithm throughput and contrast-curve
+generation routines.
diff --git a/docs/source/trimmed_readme_1.rst b/docs/source/trimmed_readme_1.rst
@@ -0,0 +1,7 @@
+TL;DR setup guide
+-----------------
+.. code-block:: bash
+
+    $ pip install vip_hci
+
+
diff --git a/docs/source/trimmed_readme.rst → docs/source/trimmed_readme_2.rst b/docs/source/trimmed_readme.rst → docs/source/trimmed_readme_2.rst
@@ -1,10 +1,3 @@
-TL;DR setup guide
------------------
-.. code-block:: bash
-
-    $ pip install vip_hci
-
-
 Installation and dependencies
 -----------------------------
 The benefits of using a Python package manager (distribution), such as
@@ -127,14 +120,3 @@ If everything went fine with the installation, you will see a welcome message.
 Now you can start finding exoplanets!
 
 
-Image conventions
------------------
-
-By default, VIP routines are compatible with either even- or odd-dimension input frames. For VIP routines that require the star to be centered in the input images (e.g. post-processing routines involving (de)rotation or scaling), the code will assume that it is placed on (zero-based indexing):
-
-- size/2-0.5 for odd-size input images; 
-- size/2 for even-size input images;
-
-i.e. exactly on a pixel in either cases. The VIP recentering routines will place the star centroid at one of these locations accordingly.
-
-
diff --git a/docs/source/trimmed_readme_3.rst b/docs/source/trimmed_readme_3.rst
@@ -0,0 +1,11 @@
+Image conventions
+-----------------
+
+By default, VIP routines are compatible with either even- or odd-dimension input frames. For VIP routines that require the star to be centered in the input images (e.g. post-processing routines involving (de)rotation or scaling), the code will assume that it is placed on (zero-based indexing):
+
+- size/2-0.5 for odd-size input images; 
+- size/2 for even-size input images;
+
+i.e. exactly on a pixel in either cases. The VIP recentering routines will place the star centroid at one of these locations accordingly.
+
+
diff --git a/docs/source/trimmed_readme_4.rst b/docs/source/trimmed_readme_4.rst
@@ -0,0 +1,7 @@
+Mailing list
+------------
+Please subscribe to our `mailing list <http://lists.astro.caltech.edu:88/mailman/listinfo/vip>`_
+if you want to be informed of ``VIP``'s latest developments (new versions
+and/or updates).
+
+
diff --git a/docs/source/about.rst → docs/source/trimmed_readme_5.rst b/docs/source/about.rst → docs/source/trimmed_readme_5.rst
@@ -1,10 +1,3 @@
-Mailing list
-------------
-Please subscribe to our `mailing list <http://lists.astro.caltech.edu:88/mailman/listinfo/vip>`_
-if you want to be informed of ``VIP``'s latest developments (new versions
-and/or updates).
-
-
 Attribution
 -----------
 Please cite `Gomez Gonzalez et al. (2017) <https://ui.adsabs.harvard.edu/abs/2017AJ....154....7G/abstract>`_ whenever 

diff --git a/docs/source/tuto_link.rst b/docs/source/tuto_link.rst
@@ -0,0 +1,12 @@
+Running the tutorials
+---------------------
+
+Tutorials, in the form of Jupyter notebooks, showcasing ``VIP``'s usage and 
+other resources can be visualised within this documentation.
+In order to execute them, you can either download/clone the 
+``VIP-extras`` `repository <https://github.com/vortex-exoplanet/VIP_extras>`_, and open each tutorial locally with jupyter notebook. 
+Alternatively, you can execute these tutorials on 
+`Binder <https://mybinder.org/v2/gh/vortex-exoplanet/VIP_extras/master>`_. 
+
+If you are new to the Jupyter notebook application check out the `beginner's guide
+<https://jupyter-notebook-beginner-guide.readthedocs.io/en/latest/what_is_jupyter.html>`_.
diff --git a/docs/source/tutorials/01_quickstart.ipynb b/docs/source/tutorials/01_quickstart.ipynb