Docs restructuring, link to the examples

docs/_templates/sidebar-toc.html

@@ -1 +1 @@
-{{ toctree(maxdepth=2|toint, collapse=False, includehidden=theme_globaltoc_includehidden|tobool) }}
+{{ toctree(maxdepth=2|toint, collapse=True, includehidden=True) }}

docs/src/conf.py

@@ -46,7 +46,7 @@
     "examples_dirs": os.path.join(ROOT, "python", "examples"),
     "gallery_dirs": "examples",
     "filename_pattern": ".*",
-    "within_subsection_order": "ExampleTitleSortKey",
+    "within_subsection_order": "FileNameSortKey",
 }
 
 # -- Options for HTML output -------------------------------------------------

docs/src/examples.rst

@@ -10,6 +10,14 @@ consist in short Python scripts that demonstrate how to make a chemiscope
 viewer file that uses some particular features (e.g. atom coloring or shape
 visualization). 
 
+.. toctree::
+
+    examples/base
+    examples/structure_map
+    examples/trajectory    
+    examples/colors
+    examples/shapes    
+
 .. raw:: html
 
     <h2>Basic usage</h2>

docs/src/index.rst

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

docs/src/manual/index.rst

@@ -24,7 +24,4 @@ extension, which can be used to explore a dataset directly inside a jupyter note
     properties
     panels
     input
-    python
-    jupyter
     sharing
-    gallery

docs/src/python/cli.rst

@@ -0,0 +1,9 @@
+Command line interface
+-----------------------
+
+.. sphinx_argparse_cli::
+   :module: chemiscope.main
+   :func: _chemiscope_input_parser
+   :prog: chemiscope-input
+   :title:
+   :group_title_prefix:

docs/src/python/index.rst

@@ -0,0 +1,23 @@
+.. _python-module:
+
+Python module
+=============
+
+The `chemiscope` package provides utilities to prepare JSON input files, 
+and to visualize them in a :ref:`jupyter environment <jupyter>`.
+The package also provides a small set of utility functions to convert `ase`_
+structure data, and a command-line command to convert structure files to
+a JSON input. 
+
+.. toctree::
+    :maxdepth: 2
+
+    installation
+    cli
+    reference
+    jupyter
+    gallery
+
+
+.. _ase: https://wiki.fysik.dtu.dk/ase/index.html
+

docs/src/python/installation.rst

@@ -0,0 +1,20 @@
+Installation
+------------
+
+The latest release of the `chemiscope` Python package can be installed from 
+the Python package index, using 
+
+.. code-block::
+
+    pip install chemiscope
+    
+To install a development version, one should instead clone the
+`github repository <https://github.com/lab-cosmo/chemiscope>`_,
+make sure that all the dependencies (including those needed to compile 
+the typescript library) are present and then run 
+
+.. code-block::
+
+    pip install .
+    
+in the main folder. 

docs/src/python/reference.rst

@@ -0,0 +1,28 @@
+.. _reference:
+
+``chemiscope`` functions reference
+----------------------------------
+
+.. autofunction:: chemiscope.write_input
+
+.. autofunction:: chemiscope.create_input
+
+.. autofunction:: chemiscope.quick_settings
+
+.. autofunction:: chemiscope.extract_properties
+
+.. autofunction:: chemiscope.composition_properties
+
+.. autofunction:: chemiscope.all_atomic_environments
+
+.. autofunction:: chemiscope.librascal_atomic_environments
+
+.. autofunction:: chemiscope.ellipsoid_from_tensor
+
+.. autofunction:: chemiscope.arrow_from_vector
+
+.. autofunction:: chemiscope.ase_vectors_to_arrows
+
+.. autofunction:: chemiscope.ase_tensors_to_ellipsoids
+
+.. _chemiscope-input-cli:

python/examples/base.py

@@ -15,15 +15,16 @@
 import chemiscope
 
 # %%
+#
 # Load structures from an extended xyz file
 
 frames = ase.io.read("data/showcase.xyz", ":")
 
 # %%
-# Write a chemiscope input file.
+#
+# Uses a chemiscope widget to visualize structures and properties
 
-chemiscope.write_input(
-    path="showcase.json.gz",
+cs = chemiscope.show(
     frames=frames,
     # quickly extract properties from the ASE frames. nb: if you're doing this for
     # sharing, don't forget to also include metadata such as units and description
@@ -37,8 +38,10 @@
         x="ccsd_pol[1]", y="ccsd_pol[2]", color="dipole_ccsd[1]"
     ),
 )
+cs
 
 # %%
-# Use `chemiscope.show` to view directly in a Jupyter environment
+#
+# Save as a file that can be viewed at chemiscope.org
 
-chemiscope.show(frames, properties=chemiscope.extract_properties(frames))
+cs.save("showcase.json.gz")

python/examples/colors.py

@@ -18,20 +18,20 @@
 
 # %%
 #
-# loads a dataset of structures containing polarizability and dipole data
+# Load a dataset of structures containing polarizability and dipole data
 
 frames = ase.io.read("data/alpha-mu.xyz", ":")
 
 # %%
 #
-# compute some scalar quantities to display as atom coloring
+# Compute some scalar quantities to display as atom coloring
 
 polarizability = []
 alpha_eigenvalues = []
 anisotropy = []
 
 for frame in frames:
-    # center in the box
+    # center molecule in the box
     frame.positions += frame.cell.diagonal() * 0.5
     for axx, ayy, azz, axy, axz, ayz in zip(
         frame.arrays["axx"],
@@ -53,17 +53,17 @@
 
 # %%
 #
-# now we just write the chemiscope input file
+# Now we just display the chemiscope (if running in a notebook)
 
 cs = chemiscope.show(
     frames=frames,
-    # properties can be extracted from the ASE.Atoms frames
+    # properties can also be extracted from the ASE.Atoms frames
     properties={
         "polarizability": np.vstack(polarizability),
         "anisotropy": np.vstack(anisotropy),
         "alpha_eigenvalues": np.vstack(alpha_eigenvalues),
     },
-    # the write_input function also allows defining the default visualization settings
+    # it is also possible to define the default visualization settings
     settings={
         "map": {
             "x": {"property": "alpha_eigenvalues[1]"},
@@ -78,15 +78,14 @@
         ],
     },
     # the properties we want to visualise are atomic properties - in order to view them
-    # in the map panel, we must indicate that all atoms are environment centers
+    # in the map panel, we must indicate the list of environments (all atoms, in this case)
     environments=chemiscope.all_atomic_environments(frames),
 )
 cs
 
 
 # %%
-# 
-# also saves as a file
+#
+# Save as a file that can be viewed at chemiscope.org
 
 cs.save("colors-example.json.gz")
-