Add specific docs for the GUI (#315)

* add copy buttons to the docs (with automatic ommission of standard prompt characters)

* add docs for using the anesthetic gui, especially for manually launching the gui

* version bump to 2.0.1

* Made a note to use %matplotlib interactive

* Corrected indent

* version bump

* version bump to 2.1.3

---------

Co-authored-by: Will Handley <wh260@cam.ac.uk>

README.rst

@@ -2,7 +2,7 @@
 anesthetic: nested sampling post-processing
 ===========================================
 :Authors: Will Handley and Lukas Hergt
-:Version: 2.1.2
+:Version: 2.1.3
 :Homepage: https://github.com/handley-lab/anesthetic
 :Documentation: http://anesthetic.readthedocs.io/
 

anesthetic/_version.py

@@ -1 +1 @@
-__version__ = '2.1.2'
+__version__ = '2.1.3'

docs/source/conf.py

@@ -57,6 +57,7 @@ def get_version(short=False):
     'sphinx.ext.viewcode',
     'sphinx.ext.githubpages',
     'sphinx.ext.imgconverter',
+    'sphinx_copybutton',
     'matplotlib.sphinxext.plot_directive',
     'numpydoc',
 ]
@@ -102,6 +103,12 @@ def get_version(short=False):
 # -- Options for autosectionlabel------------------------------------------
 autosectionlabel_prefix_document = True
 
+
+# -- Options for sphinx-copybutton ----------------------------------------
+copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "
+copybutton_prompt_is_regexp = True
+
+
 # -- Options for numpydoc -------------------------------------------------
 numpydoc_show_inherited_class_members = False
 numpydoc_show_class_members = False 

docs/source/gui.rst

@@ -0,0 +1,66 @@
+******************************
+Graphical User Interface (GUI)
+******************************
+
+For an interactive view of a nested sampling run, you can use the
+anesthetic GUI by running the follwing in your console:
+
+.. code:: console
+
+   $ anesthetic <nested/samples/file/root>
+
+Replace the ``<nested/samples/file/root>`` with the correct path and file root
+of your nested sampling run (e.g. try it out with the anesthetic example data
+in ``anesthetic/tests/example_data/pc``). This will launch a new window
+looking somewhat like this:
+
+.. image:: https://github.com/handley-lab/anesthetic/raw/master/images/anim_1.gif
+
+.. warning::
+    Note that the GUI only works out-of-the-box if your files follow a specific
+    structure, matching either the one from 
+    `PolyChord <https://github.com/PolyChord/PolyChordLite>`_,
+    `MultiNest <https://github.com/farhanferoz/MultiNest>`_, or from 
+    `UltraNest <https://github.com/JohannesBuchner/UltraNest>`_.
+
+.. note::
+    However, you can also manually feed in your data and launch the GUI as
+    demonstrated in the following example:
+
+    .. plot::
+
+        import numpy as np
+        import matplotlib.pyplot as plt
+        from anesthetic import NestedSamples
+
+        # Set up `data`, `logL`, and `logL_birth`
+        file_path = "../../tests/example_data/pc_dead-birth.txt"
+        file_data = np.loadtxt(file_path)
+        data, logL, logL_birth = np.split(file_data, [-2, -1], axis=1)
+
+        samples = NestedSamples(data=data, logL=logL, logL_birth=logL_birth)
+        samples.gui()
+        plt.show()
+
+    To make this example work with the anesthetic example data, place the above
+    code snippet into a python script (let's call it
+    ``my_anesthetic_gui_script.py``), make sure the file path correctly points
+    to the example data in the ``anesthetic/tests/`` folder, and launch it from
+    the command line:
+
+    .. code:: console
+
+       $ python my_anesthetic_gui_script.py
+
+    To modify the above example for your own case, you only need to change the
+    middle block to read in your data file(s) instead of the anesthetic example
+    data and pass on the ``data``, ``logL``, and ``logL_birth`` arrays, which
+    contain the parameter samples, their corresponding log-likelihood values, and
+    the log-likelihood values of their birth contours, respectively.
+
+.. note::
+    If you are using a jupyter notebook, you should use 
+    ``%matplotlib interactive`` magic command (or equivalent) to use the
+    interactive GUI.
+
+

docs/source/index.rst

@@ -9,6 +9,7 @@
    Reading and writing <reading_writing>
    Samples and statistics <samples>
    Plotting <plotting>
+   GUI <gui>
    anesthetic <modules>
 
 .. include:: ../../README.rst

pyproject.toml

@@ -58,7 +58,7 @@ classifiers = [
 "JOSS paper" = "https://joss.theoj.org/papers/10.21105/joss.01414"
 
 [project.optional-dependencies]
-docs = ["sphinx", "sphinx_rtd_theme", "numpydoc"]
+docs = ["sphinx", "sphinx_rtd_theme", "sphinx-copybutton", "numpydoc"]
 test = ["pytest", "pytest-cov", "flake8", "pydocstyle", "packaging", "pre-commit"]
 ultranest = ["h5py"]
 astropy = ["astropy"]