Release/1.0.0rc3 (#234).

aiidalab · Sep 15, 2021 · eddeb9a · eddeb9a
2 parents d99ba86 + 66132cd
commit eddeb9a
Show file tree

Hide file tree

Showing 30 changed files with 237 additions and 145 deletions.
diff --git a/README.md b/README.md
@@ -1,29 +1,19 @@
 [![Documentation Status](https://readthedocs.org/projects/aiidalab-widgets-base/badge/?version=latest)](https://aiidalab-widgets-base.readthedocs.io/en/latest/?badge=latest)
 
-# Base widgets for AiiDAlab
+# AiiDAlab Widgets
 
-## Installation
+[AiiDAlab](https://materialscloud.org/aiidalab) applications typically involve some of following steps:
 
-Install the `aiidalab_widgets_base` python package via:
-```
-pip install aiidalab-widgets-base
-```
+ * Prepare the input for a calculation (e.g. an atomic structure).
+ * Select computational resources and submit a calculation to AiiDA.
+ * Monitor a running calculation.
+ * Find and analyze the results of a calculation.
 
-Install the corresponding `aiidalab-widgets-base` AiiDAlab application
-via the app manager as usual.
-
-### Optional dependencies
-
-* The `SmilesWidget` widget requires the [OpenBabel](http://openbabel.org/) library.
+The AiiDAlab widgets help with these common tasks.
 
 ## Documentation
-The documentation can be found on the [following web page](https://aiidalab-widgets-base.readthedocs.io).
-
-## Usage
 
-Using the widgets usually just involves importing and displaying them.
-For demos, have a look at the jupyter notebooks (`.ipynb` extension) in
-this folder.
+Hosted on [aiidalab-widgets-base.readthedocs.io](https://aiidalab-widgets-base.readthedocs.io).
 
 ## License
 

diff --git a/aiidalab_widgets_base/__init__.py b/aiidalab_widgets_base/__init__.py
@@ -79,4 +79,4 @@
     "viewer",
 ]
 
-__version__ = "1.0.0rc2"
+__version__ = "1.0.0rc3"
diff --git a/aiidalab_widgets_base/data/__init__.py b/aiidalab_widgets_base/data/__init__.py
@@ -5,8 +5,8 @@
 
 # The first atom is anchoring, so the new bond will be connecting it
 # The direction of the new bond is (-1, -1, -1).
-LIGANDS = {
-    "Select ligand": 0,
+FUNCTIONAL_GROUPS = {
+    "Select functional group": 0,
     "Methyl -CH3": [
         ("C", 0, 0, 0),
         ("H", 0.23962342, -0.47699124, 0.78585262),
@@ -27,14 +27,14 @@
 }
 
 
-class LigandSelectorWidget(ipw.Dropdown):
-    """Class to select ligands that are returned as `Atoms` object"""
+class FunctionalGroupSelectorWidget(ipw.Dropdown):
+    """Class to select functional groups that are returned as `Atoms` object"""
 
-    def __init__(self, value=0, description="Select ligand", **kwargs):
+    def __init__(self, value=0, description="Select functional group", **kwargs):
         self.style = {"description_width": "initial"}
         self.layout = {"width": "initial"}
         super().__init__(
-            value=value, description=description, options=LIGANDS, **kwargs
+            value=value, description=description, options=FUNCTIONAL_GROUPS, **kwargs
         )
 
     def rotate(self, align_to=(0, 0, 1), remove_anchor=False):
@@ -70,3 +70,7 @@ def anchoring_atom(self):
         if self.value == 0:
             return None
         return self.value[0][0]
+
+
+# LigandSelectorWidget is deprecated
+LigandSelectorWidget = FunctionalGroupSelectorWidget
diff --git a/aiidalab_widgets_base/structures.py b/aiidalab_widgets_base/structures.py
@@ -355,7 +355,7 @@ def __init__(self, title="", description="Upload Structure"):
             description=description, multiple=False, layout={"width": "initial"}
         )
         supported_formats = ipw.HTML(
-            """<a href="https://wiki.fysik.dtu.dk/ase/_modules/ase/io/formats.html" target="_blank">
+            """<a href="https://wiki.fysik.dtu.dk/ase/ase/io/io.html#ase.io.write" target="_blank">
         Supported structure formats
         </a>"""
         )

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -6,8 +6,9 @@
 import subprocess
 import sys
 import time
+from pathlib import Path
 
-# Load the dummy profile to make sure the docs build suucceed even if the current
+# Load the dummy profile to make sure the docs build succeed even if the current
 # default profile of the AiiDA installation is not configured.
 from aiida.manage.configuration import load_documentation_profile
 
@@ -33,8 +34,11 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.viewcode",
     "sphinxcontrib.contentui",
+    "myst_nb",
 ]
 
+jupyter_execute_notebooks = "off"
+
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3.7", None),
 }
@@ -95,18 +99,34 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = []
 
+html_theme = "pydata_sphinx_theme"
+
+# -- Modifications for Readthedocs ----------------------------------------
+
+
+def symlink_example_notebooks(source_dir: Path):
+    """Symlink example Jupyter notebooks.
+
+    Symlinks example jupyter notebooks so that they can be
+    included into the documentation.
+    """
+    notebooks_dir = source_dir.parent.parent / "notebooks"
+    target_dir = source_dir / "widget-list" / "notebooks"
+    if not target_dir.exists():
+        target_dir.symlink_to(notebooks_dir, target_is_directory=True)
+
 
 def run_apidoc(_):
     """Runs sphinx-apidoc when building the documentation.
     Needs to be done in conf.py in order to include the APIdoc in the
     build on readthedocs.
     See also https://github.com/rtfd/readthedocs.org/issues/1139
     """
-    source_dir = os.path.abspath(os.path.dirname(__file__))
-    apidoc_dir = os.path.join(source_dir, "apidoc")
-    package_dir = os.path.join(
-        source_dir, os.pardir, os.pardir, "aiidalab_widgets_base"
-    )
+    source_dir = Path(__file__).resolve().parent
+    apidoc_dir = source_dir / "apidoc"
+    package_dir = source_dir.parent.parent / "aiidalab_widgets_base"
+
+    symlink_example_notebooks(source_dir)
 
     # In #1139, they suggest the route below, but this ended up
     # calling sphinx-build, not sphinx-apidoc

diff --git a/docs/source/contribute/index.rst b/docs/source/contribute/index.rst
@@ -1,10 +1,10 @@
-*****************
-Contribute to AWB
-*****************
+************
+Contributing
+************
 
-If would like to contiribute to the project you can do it in multiple ways:
+Contributions to the AiiDAlab widgets are highly welcome and can take different forms:
 
-* `Create issues <https://github.com/aiidalab/aiidalab-widgets-base/issues/new>`_ in case you found a bug or you need a feature that is not yet implemented.
-* Contribute new widgets.
-* Help us with fixing the `existing issues <https://github.com/aiidalab/aiidalab-widgets-base/issues>`_.
-* Extend the documentation.
+* Contribute a widget you created that would be of general interest to AiiDAlab users.
+* `Report bugs <https://github.com/aiidalab/aiidalab-widgets-base/issues>`_.
+* `Feature requests <https://github.com/aiidalab/aiidalab-widgets-base/issues>`_.
+* Help us improve the documentation of widgets.
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -1,30 +1,26 @@
-#################################################
-Welcome to AiiDAlab Widgets Base's documentation!
-#################################################
+##############################################
+Welcome to the AiiDAlab Widgets documentation!
+##############################################
 
+`AiiDAlab <https://materialscloud.org/aiidalab>`_ applications typically involve some of following steps:
 
-AiiDAlab Widgets Base (AWB) is a set of handy widgets that are used in AiiDAlab to create applications.
+* Prepare the input for a calculation (e.g. an atomic structure).
+* Select computational resources and submit a calculation to AiiDA.
+* Monitor a running calculation.
+* Find and analyze the results of a calculation.
+
+The AiiDAlab widgets help with these common tasks.
 
 .. toctree::
    :maxdepth: 2
 
-   AWB introduction <introduction/index>
-   Contribute to AWB <contribute/index>
-   List of widgets <widget-list/index>
-   API documentation <apidoc/aiidalab_widgets_base>
-
-
-``aiidalab-widgets-base`` package is released under the MIT license.
+   installation
+   widget-list/index
+   contribute/index
 
+   API documentation <apidoc/aiidalab_widgets_base>
 
 
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-
 ***********
 How to cite
 ***********
@@ -38,3 +34,12 @@ Acknowledgements
 ****************
 
 This work is supported by the `MARVEL National Centre for Competency in Research <http://nccr-marvel.ch>`__	funded by the `Swiss National Science Foundation <http://www.snf.ch/en>`__, as well as by the `MaX European Centre of Excellence <http://www.max-centre.eu/>`__ funded by the Horizon 2020 EINFRA-5 program, Grant No. 676598.
+
+
+******************
+Indices and tables
+******************
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/docs/source/installation.rst b/docs/source/installation.rst
@@ -0,0 +1,33 @@
+************
+Installation
+************
+
+The AiiDAlab widgets are already pre-installed in the AiiDAlab environment.
+
+This includes:
+
+ * the ``aiidalab-widgets-base`` Python package that contains the widgets (``from aiidalab_widgets_base import ...``)
+ * the "AiiDAlab Widgets" app that contains Jupyter notebooks illustrating how to use the widgets
+
+Installation outside the AiiDAlab
+=================================
+
+Install the Python package from PyPI:
+
+.. code-block:: bash
+
+    pip install aiidalab-widgets-base
+
+Developers may want to clone the git repository containing the app and the notebooks and install the Python package in editable mode:
+
+.. code-block:: bash
+
+    git clone https://github.com/aiidalab/aiidalab-widgets-base.git
+    cd aiidalab-widgets-base
+    pip install -e .
+
+
+Optional dependencies
+---------------------
+
+The `SmilesWidget` widget requires the `OpenBabel <http://openbabel.org/>`_ library.
diff --git a/docs/source/introduction/index.rst b/docs/source/introduction/index.rst
diff --git a/docs/source/widget-list/codes.rst b/docs/source/widget-list/codes.rst
diff --git a/docs/source/widget-list/computers.rst b/docs/source/widget-list/computers.rst
diff --git a/docs/source/widget-list/databases.rst b/docs/source/widget-list/databases.rst
diff --git a/docs/source/widget-list/export.rst b/docs/source/widget-list/export.rst
diff --git a/docs/source/widget-list/index.rst b/docs/source/widget-list/index.rst
@@ -2,15 +2,23 @@
 List of widgets
 ***************
 
-Here we collect the information about all the widgets available in AWB and provide a simple example of how to use them.
+This is a collection of Jupyter notebooks that illustrate how to use the widgets available from this library.
+
+In AiiDAlab, these notebooks can be found in the ``notebooks`` directory of the "AiiDAlab Widgets" app.
+See also the `corresponding git repository <https://github.com/aiidalab/aiidalab-widgets-base>`_.
 
 .. toctree::
-    :maxdepth: 1
+    :titlesonly:
+    :glob:
 
-    Codes <codes>
-    Computers <computers>
-    External databases <databases>
-    Export AiiDA DB <export>
-    Nodes <nodes>
-    Processes <processes>
-    Structures <structures>
+    notebooks/aiida_datatypes_viewers
+    notebooks/codes_computers
+    notebooks/setup_computer
+    notebooks/setup_code
+    notebooks/process
+    notebooks/process_list
+    notebooks/structures
+    notebooks/structures_multi
+    notebooks/wizard_apps
+    notebooks/eln_configure
+    notebooks/eln_import
diff --git a/docs/source/widget-list/nodes.rst b/docs/source/widget-list/nodes.rst
diff --git a/docs/source/widget-list/processes.rst b/docs/source/widget-list/processes.rst
diff --git a/docs/source/widget-list/structures.rst b/docs/source/widget-list/structures.rst
diff --git a/aiida_datatypes_viewers.ipynb → notebooks/aiida_datatypes_viewers.ipynb b/aiida_datatypes_viewers.ipynb → notebooks/aiida_datatypes_viewers.ipynb
@@ -1,5 +1,12 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Displaying AiiDA data types"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -166,7 +173,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -180,7 +187,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.6.8"
+   "version": "3.9.7"
   }
  },
  "nbformat": 4,