Integration with sphinx-gallery (#341)

Uses `chemiscope.sphinx` functionalities to generate output for `chemiscope.show` calls in a sphinx-gallery example. Co-authored-by: Michele Ceriotti <[email protected]>
lab-cosmo · Jun 13, 2024 · a1ea5e6 · a1ea5e6
1 parent 623edf9
commit a1ea5e6
Show file tree

Hide file tree

Showing 35 changed files with 530 additions and 286 deletions.
diff --git a/README.md b/README.md
@@ -89,6 +89,13 @@ npm run build
 See [app/] or the [documentation](https://chemiscope.org/docs/embedding.html)
 for a examples of how to create a webpage using chemiscope.
 
+## sphinx and sphinx-gallery integration
+
+Chemiscope provides also extensions for `sphinx` and `sphinx-gallery` to 
+include chemiscope viewers within the documentation of a Python package. 
+See the [documentation](https://chemiscope.org/docs/python/sphinx.html)
+for a discussion of the setup and a few examples. 
+
 ## License and contributions
 
 If you are interested in contributing to chemiscope, please have a look at our

diff --git a/docs/.gitignore b/docs/.gitignore
@@ -1 +1,4 @@
 build/
+
+src/examples/
+src/sg_execution_times.rst
diff --git a/docs/_templates/sidebar-toc.html b/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) }}
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,7 +1,10 @@
 sphinx>=4
 sphinx-bootstrap-theme
 sphinx-argparse-cli
+sphinx-gallery
 
 # required to be able to import chemiscope in the doc
 numpy
 ipywidgets
+matplotlib
+ase==3.22.1
diff --git a/docs/src/conf.py b/docs/src/conf.py
@@ -3,6 +3,7 @@
 import sphinx_bootstrap_theme
 
 import chemiscope
+from chemiscope.sphinx import ChemiscopeScraper
 
 ROOT = os.path.abspath(os.path.join("..", ".."))
 
@@ -22,10 +23,16 @@
 # ones.
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
     "sphinx_argparse_cli",
+    "sphinx_gallery.gen_gallery",
     "chemiscope.sphinx",
 ]
 
+intersphinx_mapping = {
+    "sphinx_gallery": ("https://sphinx-gallery.github.io/stable/", None),
+}
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
@@ -34,6 +41,14 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
+examples_dirs = os.path.join(ROOT, "python", "examples")
+sphinx_gallery_conf = {
+    "examples_dirs": examples_dirs,
+    "gallery_dirs": "examples",
+    "filename_pattern": ".*",
+    "within_subsection_order": "FileNameSortKey",
+    "image_scrapers": ("matplotlib", ChemiscopeScraper()),
+}
 
 # -- Options for HTML output -------------------------------------------------
 

diff --git a/docs/src/examples.rst b/docs/src/examples.rst
diff --git a/docs/src/img/example_base.png b/docs/src/img/example_base.png
diff --git a/docs/src/img/example_colors.png b/docs/src/img/example_colors.png
diff --git a/docs/src/img/example_md.png b/docs/src/img/example_md.png
diff --git a/docs/src/img/example_pca.png b/docs/src/img/example_pca.png
diff --git a/docs/src/img/example_shapes.png b/docs/src/img/example_shapes.png
diff --git a/docs/src/index.rst b/docs/src/index.rst
@@ -8,7 +8,8 @@ and molecules and help researchers to find structure-properties correlations
 inside such databases. The screenshot below shows an example of such database
 being visualized with chemiscope. The :ref:`first part of this documentation <user-manual>`
 describes the default interface of chemiscope and how to use it with your own database,
-both using the stand-alone viewer or the :ref:`jupyter widget <jupyter>`.
+both using the stand-alone viewer or through the :ref:`python module <python-module>`
+and/or the :ref:`jupyter widget <jupyter>`.
 
 .. figure:: img/screenshot.png
     :align: center
@@ -18,14 +19,17 @@ both using the stand-alone viewer or the :ref:`jupyter widget <jupyter>`.
 
 Chemiscope is built around re-usable components, that can be arranged in
 different manners to create visualization adapted to different kinds of data. The
-:ref:`second part of this documentation <dev-manual>` explains how to build the 
+:ref:`second part of this documentation <dev-manual>` explains how to build the
 code and use it in your own website to create new interfaces.
 
-Citing chemiscope
------------------
+
+Getting and citing chemiscope
+-----------------------------
 
 Chemiscope is distributed under an open-source license, and you are welcome to
 use it and incorporate it into your own research and software projects.
+You can get the source from the
+`github repository <https://github.com/lab-cosmo/chemiscope>`_.
 If you find it useful, we would appreciate a citation to the chemiscope
 `paper`_:
 
@@ -37,21 +41,17 @@ If you incorporate chemiscope components into a software project, a link
 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/index
+    manual/index
+    python/index
     embedding
-    chemiscope-sphinx
 
 
 .. _chemiscope: https://chemiscope.org

diff --git a/docs/src/manual/index.rst b/docs/src/manual/index.rst
@@ -13,8 +13,10 @@ This section starts introducing the concept of structural and physical propertie
 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.
+not require internet connectivity. 
+See the :ref:`Python module documentation <python-module>`  
+for how to interact with chemiscope in a script, or to explore a dataset directly 
+inside a jupyter notebook.
 
 .. _chemiscope: https://chemiscope.org
 
@@ -24,6 +26,4 @@ extension, which can be used to explore a dataset directly inside a jupyter note
     properties
     panels
     input
-    python
-    jupyter
     sharing
diff --git a/docs/src/manual/python.rst b/docs/src/manual/python.rst
diff --git a/docs/src/python/cli.rst b/docs/src/python/cli.rst
@@ -0,0 +1,11 @@
+.. _chemiscope-input-cli:
+
+Command line interface
+-----------------------
+
+.. sphinx_argparse_cli::
+   :module: chemiscope.main
+   :func: _chemiscope_input_parser
+   :prog: chemiscope-input
+   :title:
+   :group_title_prefix:
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		{{ toctree(maxdepth=2\|toint, collapse=False, includehidden=theme_globaltoc_includehidden\|tobool) }}
		{{ toctree(maxdepth=2\|toint, collapse=True, includehidden=True) }}