Documentation cleanup

README.md

@@ -43,7 +43,25 @@ issue](https://github.com/lab-cosmo/chemiscope/issues/new) with your question;
 or send an email to the developers (you can find these emails on the lab
 webpage: https://www.epfl.ch/labs/cosmo/people/)
 
-## Getting and running the code
+## Getting the python package and using chemiscope in Jupyter notebooks
+
+Using chemiscope in a Jupyter notebook should be as easy as
+````bash
+pip install chemiscope
+```
+This also allows to generate chemiscope JSON files that can be viewed on
+http://chemiscope.org
+
+If you need to build and install a development version, you should 
+have all the npm stack installed, and then just run
+
+```bash
+git clone https://github.com/lab-cosmo/chemiscope
+cd chemiscope
+pip install .
+```
+
+## Getting and running the web app locally
 
 ```bash
 git clone https://github.com/lab-cosmo/chemiscope

app/index.html

@@ -220,7 +220,7 @@ <h5 class="modal-title">Load and save data</h5>
                         <h5>Dataset</h5>
                         <p>
                             Using <a href="https://chemiscope.org">chemiscope.org</a>, you are able to visualize your own data, stored in a JSON file.
-                            Please see the <a href="https://chemiscope.org/docs/tutorial.html#input-file-format-for-chemiscope">documentation</a> for
+                            Please see the <a href="https://chemiscope.org/docs/manual">documentation</a> for
                             a complete description of the JSON format; as well as tools that can help you generate such files.
                         </p>
 

docs/src/index.rst

@@ -38,11 +38,15 @@ back to the `chemiscope`_ homepage is the preferred form of acknowledgement.
 
 What's in this documentation?
 -----------------------------
+.. toctree::
+    :hidden:
+
+    Chemiscope visualizer <self>
 
 .. toctree::
     :maxdepth: 2
-
-    tutorial/index
+    
+    manual/index
     embedding
 
 

docs/src/manual/index.rst

@@ -0,0 +1,27 @@
+User manual
+===========
+
+This manual presents an overview of how to interact with the chemiscope viewer
+in its "standard" implementation - including the web tool and the jupyter widget. 
+It does not discuss in detail how to build a low-dimensional representation of 
+a chemical dataset - chemiscope is just a viewer, and there are many tools available
+to perform this kind of analyses. 
+
+This section starts introducing the concept of structural and physical properties, 
+before describing how to use the different panels in the standard visualization. 
+It continues by presenting how you can generate a chemiscope input file to load on
+https://chemiscope.org, as well as within a standalone HTML viewer which does
+not require internet connectivity. Finally, we present the chemiscope jupyter
+extension, which can be used to explore a dataset directly inside a jupyter notebook.
+
+.. _chemiscope: https://chemiscope.org
+
+.. toctree::
+    :maxdepth: 2
+
+    properties
+    panels
+    input
+    input-reference
+    sharing
+    jupyter

docs/src/tutorial/input.rst → docs/src/manual/input.rst

@@ -27,19 +27,18 @@ module. Install the package with ``pip install chemiscope``, and use
 own script to generate the JSON file.
 
 If all the properties you want to include into chemiscope are already stored in
-a file `ase`_ can read, the ``chemiscope`` python package also install a
+a file `ase`_ can read, the ``chemiscope`` python package also installs a
 `chemiscope-input <chemiscope-input-cli_>`_ command line script.
 
 Note that chemiscope does not compute structural representations or
-dimensionality reduction, and you need to do this yourself or use another
-package such as ASAP.
-
-``ASAP``
-^^^^^^^^
-
+dimensionality reduction, and the command line interface works iff
+there are mappable quantities in the file. You can generate such representations
+or reductions with packages such as `ASAP`_ or
+`scikit-matter`_.
 The `ASAP`_ structural analysis package is another tool that can directly
 generate an output in chemiscope format.
 
+
 ``chemiscope`` functions reference
 ----------------------------------
 
@@ -65,6 +64,7 @@ generate an output in chemiscope format.
 
 .. _ase: https://wiki.fysik.dtu.dk/ase/index.html
 .. _ASAP: https://github.com/BingqingCheng/ASAP
+.. _scikit-matter: https://scikit-matter.readthedocs.io/en/latest/
 
 
 .. _chemiscope-input-cli:

docs/src/manual/jupyter.rst

@@ -0,0 +1,15 @@
+Jupyter notebooks
+=================
+
+Chemiscope can be used as a widget in Jupyter notebooks, that should work in both Jupyter classic and JupyterLab. 
+The widget can be created in `default` mode (showing both a structure and a map panel), or used to display only
+structures or only proeprties. 
+
+Once created, it is possible to interact with the widget using a traitlet interface, modeled after 
+`Jupyter widgets <http://ipywidgets.readthedocs.io>`_.
+
+Creating a chemiscope widget
+----------------------------
+
+.. autofunction:: chemiscope.show
+.. autofunction:: chemiscope.show_input

docs/src/tutorial/panels.rst → docs/src/manual/panels.rst

@@ -23,10 +23,13 @@ the left of the dataset title.
 
 The structure panel is a 3D molecular viewer based on `3Dmol.js`_. The settings are
 accessible through the hamburger menu (☰) on the right of the viewer. The
-settings are grouped into **representation** (how is the molecule rendered);
-**supercell** (how many copies of the unit cell to display); **environments**
-(how atom-centered environments are displayed); **camera** (reset the camera in
-along one of the given axis); and **trajectory** (playback related settings).
+settings are grouped into
+
+- **representation** - how is the molecule rendered
+- **supercell** - how many copies of the unit cell to display
+- **environments** - how atom-centered environments are displayed
+- **camera** - reset the camera in along one of the given axis
+- **trajectory** - playback related settings
 
 .. figure:: ../img/structure.png
     :width: 80 %
@@ -37,7 +40,7 @@ Finally, the environments information panel features sliders and text input to
 allow for an easy selection of the environment of interest. The play button on
 the left of the sliders activates the trajectory playback, looping over the
 structures in the datasets or the atoms in a structure. By clicking on the
-labels at the top (*structure XXX* and*atom XXX*), one can hide or show the
+labels at the top (*structure XXX* and *atom XXX*), one can hide or show the
 full property tables. These tables show all properties in the dataset for the
 currently selected environment.
 

docs/src/tutorial/properties.rst → docs/src/manual/properties.rst

@@ -26,8 +26,8 @@ as possible, yet concise. Examples of such representations are for instance
 symmetry functions <Behler-Parrinello>`_. These representations are usually
 high-dimensional vectors, hard to visualize and interpret. For this reason, one
 usually applies a dimensionality reduction algorithm, such as `PCA`_, `sketch-map`_,
-*etc.*   The interpretation of the resulting  will differ depending on both the
-descriptor used to represent the structures or environments and the
+`PCovR`_, *etc.*   The interpretation of the resulting  will differ depending on
+both the descriptor used to represent the structures or environments and the
 dimensionality reduction algorithm applied.
 
 Chemiscope simplifies visualizing the correlations between structural
@@ -53,3 +53,4 @@ and other associated properties associated (such as energy, density, ...) as
 .. _Behler-Parrinello: https://doi.org/10.1103/physrevlett.98.146401
 .. _PCA: https://en.wikipedia.org/wiki/Principal_component_analysis
 .. _sketch-map: https://doi.org/10.1073/pnas.1108486108
+.. _PCovR: https://doi.org/10.1088/2632-2153/aba9ef

python/chemiscope/jupyter.py

@@ -112,7 +112,7 @@ def show_input(path, mode="default"):
 
     :param str mode: widget mode, either ``default``, ``structure`` or ``map``.
 
-        .. code-block:: python
+    .. code-block:: python
 
         import chemiscope