Release 2.2.6.

Add zoom limits for 3D crystal view Update documentation and notebooks. Remove duplicate info from pyproject.toml. Change maintainer to favre@esrf.fr
diffpy · Mar 14, 2023 · de850d3 · de850d3
1 parent 0ae5d21
commit de850d3
Show file tree

Hide file tree

Showing 11 changed files with 5,372 additions and 18,392 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,9 +2,15 @@
 
 ## Version 2.2.6
 
+### Changes
+
+- Support for windows and python>=3.8
+- Added a zoom limit for 3D crystal views
+
 ### Fixes
 
-- fix for windows and python>=3.8
+- Correct error preventing pyobjcryst import for windows and python>=3.8
+  (https://github.com/diffpy/pyobjcryst/issues/33)
 - Fix for matplotlib >=3.7.0 when removing hkl labels
 
 ## Version 2.2.5

diff --git a/README.rst b/README.rst
@@ -10,7 +10,7 @@ pyobjcryst
 Python bindings to ObjCryst++, the Object-Oriented Crystallographic Library.
 
 The documentation for this release of pyobjcryst can be found on-line at
-http://diffpy.github.io/pyobjcryst.
+https://pyobjcryst.readthedocs.io/
 
 
 INSTALLATION
@@ -20,17 +20,26 @@ pyobjcryst is available for Python 3.7 (deprecated), and 3.8 to 3.11.
 Using conda (recommended)
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-We recommend to use `Anaconda Python <https://www.anaconda.com/download>`_
-as it allows to install all software dependencies together with
-pyobjcryst. For other Python distributions it is necessary to
-install the required software separately. 
+We recommend to use **conda** as it allows to install all software dependencies
+together with pyobjcryst, without too much compiling hastle.
 
-Using conda, we recommend installing pyobjcryst using the "conda-forge" channel ::
+Two distributions can be used:
+
+* `Anaconda Python <https://www.anaconda.com/download>`_, the historical
+  main conda-based distribution
+* `Mamba-forge <https://github.com/conda-forge/miniforge/releases>`_ , which
+  has the advantage off providing **mamba** in addition to conda, and is
+  *much faster* when resolving dependencies during installation. It also
+  uses by default the conda-forge repository, which is what almost all
+  users would want.
+
+Using conda, we you can install pyobjcryst using the "conda-forge" channel ::
 
    conda install -c conda-forge pyobjcryst
 
-Note: when updating, please make sure you are upgrading both
-libobjcryst and pyobjcryst packages.
+Alternatively using mamba ::
+
+   mamba install pyobjcryst
 
 You can also install from the "diffpy" channel - especially if you use
 pyobjcryst allong with the other diffpy tools for PDF calculations,
@@ -41,6 +50,20 @@ of packages for structure analysis ::
 
    conda install -c diffpy diffpy-cmi
 
+Complete new conda environment with optional GUI and jupyter dependencies
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Assuming you have installed `Mamba-forge <https://github.com/conda-forge/miniforge/releases>`_,
+you can directly create a new conda environment named `pyobjcryst` with all useful dependencies (including
+jupyter-lab, python 3.11..) using ::
+
+   mamba create -n pyobjcryst python=3.11 pyobjcryst matplotlib py3dmol jupyterlab ipympl multiprocess
+
+Then you can activate the environment and launch jupyter-lab using ::
+
+   conda activate pyobjcryst
+   jupyter-lab
+
 From source
 ^^^^^^^^^^^
 The requirements are:
@@ -97,17 +120,14 @@ displayed in a jupyter notebook:
   ``py3dmol`` and ``ipywidgets`` modules. See the notebook
   ``examples/cystal_3d_widget.ipynb``
 * a PowderPattern can be displayed (and live-updated) if
-  ``matplotlib`` (and optionally ``ipympl``) are installed. See the
+  ``matplotlib`` and ``ipympl`` are installed. See the
   notebook ``examples/cimetidine-structure-solution-powder.ipynb``
 
-In short, ``pip install jupyter matplotlib ipywidgets py3dmol``
-will give you all the required dependencies. Note that you can also
+In short, ``conda install jupyter matplotlib ipympl py3dmol``
+will give you all the required dependencies. You can also
 use this in jupyterlab.
 
-Note that ``jupyter``, ``ipywidgets``, ``matplotlib`` and ``ipympl`` can
-be installed using conda(-forge), but ``py3dmol`` should be installed using
-``pip``, as the conda version is obsolete.
-
+These packages can also be installed using ``pip`` if you do not use conda.
 
 DEVELOPMENT
 -----------

diff --git a/doc/manual/source/index.rst b/doc/manual/source/index.rst
@@ -1,3 +1,7 @@
+..
+  Note: in order for the notebooks to render correctly using widgets,
+  go to jupyter-lab settings and select 'Save Widget State Automatically'
+
 ####################################################
 pyobjcryst documentation
 ####################################################
@@ -14,8 +18,11 @@ Authors
 
 `pyobjcryst` was written as part of the DANSE_ open-source project by
 Christopher Farrow, Pavol Juhás, and Simon J.L. Billinge.
-The sources are now maintained as a part of the DiffPy-CMI complex
+The sources are maintained as a part of the DiffPy-CMI complex
 modeling initiative at the Brookhaven National Laboratory.
+The underlying library  `ObjCryst++ <https://github.com/vincefn/objcryst>`_
+was developed by V. Favre-Nicolin as part of the development of the
+`Fox <http://fox.vincefn.net>`_ software.
 
 Further developments including the ability to index and refine
 powder patterns, solve and display crystal structures, using the
@@ -34,19 +41,43 @@ Installation
 
 `pyobjcryst` and `libobjcryst` conda packages can be easily installed under
 Linux and macOS using channel `conda-forge` or `diffpy` channels,
-e.g.:
+e.g. ::
+
+   conda install -c conda-forge libobjcryst pyobjcryst
+
+or ::
 
-  * `conda install -c diffpy libobjcryst pyobjcryst`
-  * `conda install -c conda-forge libobjcryst pyobjcryst`
+   conda install -c diffpy libobjcryst pyobjcryst
+
+It is recommended to use the `conda-forge` channel which is updated more
+frequently than the `diffpy` one, unless you only use `pyobjcryst` through
+the DiffPy-CMI tools.
 
 See the `README <https://github.com/diffpy/pyobjcryst#requirements>`_
 file included with the distribution for more details.
 
+Complete conda environment with optional GUI and jupyter dependencies
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The **fastest way to use pyobjcryst** is to first install the
+`Mamba-forge <https://github.com/conda-forge/miniforge/releases>`_ distribution (which is
+faster than traditional conda), and then you can directly create a new conda environment
+named `pyobjcryst` with all useful dependencies (including jupyter-lab, python 3.11..) using ::
+
+   mamba create -n pyobjcryst python=3.11 pyobjcryst matplotlib py3dmol jupyterlab ipympl multiprocess
+
+(note: if you do not know `mamba`, it is a command equivalent to `conda` except *much* faster)
+
+Then activate the environment and launch jupyter-lab using ::
+
+   conda activate pyobjcryst
+   jupyter-lab
+
 ======================================
-Usage
+Usage & notebooks
 ======================================
 
-`pyobjcryst` can be used in different ways:
+`pyobjcryst` can be used
 
 * **as a backend library** to manage crystal structures description in an application
   like `DiffPy-CMI <https://www.diffpy.org/products/diffpycmi/index.html>`_
@@ -66,6 +97,11 @@ Usage
   * :doc:`Meta-structure solution using multi-processing <examples/structure-solution-multiprocessing>`
   * :doc:`Quantitative phase analysis (QPA) <examples/Quantitative-phase-analysis>`
 
+The **API documentation** can be found in :doc:`api/modules`.
+
+You can also read the
+`documentation of the underlying ObjCryst++ library <https://vincefn.net/ObjCryst/annotated.html>`_.
+
 ======================================
 Table of contents
 ======================================