From 1c37abf0fc641bf418be1cf7ff016dd4ad737e03 Mon Sep 17 00:00:00 2001
From: Simon Billinge
Date: Mon, 17 Feb 2025 18:08:37 -0500
Subject: [PATCH 01/46] update to latest pdfgui and remove diffpy-dev from
community
---
community.rst | 32 +++++++++++-------------------
products/pdfgui.rst | 48 ++++++++++++++++-----------------------------
2 files changed, 28 insertions(+), 52 deletions(-)
diff --git a/community.rst b/community.rst
index a1aed703..bd30d323 100644
--- a/community.rst
+++ b/community.rst
@@ -2,30 +2,20 @@ Community
=========
To ensure a bright future for the DiffPy project it is essential to build a strong community
-of users and contributing developers. There are several Google groups for support and
-development of DiffPy and related applications.
+of users and contributing developers. News about updates and new releases will be made at the
+`diffpy-users `__ Google group,
+as well as it being a place to ask questions
+and find answers about using all diffpy programs.
+When you sign up,
+please leave a short message about why you are requesting to join as we have had spam accounts requesting access
+and so we want to know you are a legitimate user.
-- `diffpy-users `_ Help on usage of DiffPy-CMI,
- PDFgetX3, PDFgetN3, PDFgetS3,
- PDFgui, and other DiffPy components. This group is a knowledge base for PDFgui
- user tips, tricks and troubleshooting. Feel free to search for answers or ask your question here.
+.. raw:: html
- .. raw:: html
+
-
-
-- `diffpy-dev `_ For bug reports, feature requests, and discussions about development
- and changes of DiffPy-CMI, PDFgetX3, PDFgetN3, PDFgetS3,
- PDFgui, and other DiffPy components. Materials scientists, chemists
- physicists, engineers - please contribute by telling us your needs or sharing your suggestions here.
-
- .. raw:: html
-
-
You can also share your comments, suggestions, praise or complaints by sending email to
`Simon J. L. Billinge `_.
diff --git a/products/pdfgui.rst b/products/pdfgui.rst
index 7547ffee..c320f245 100644
--- a/products/pdfgui.rst
+++ b/products/pdfgui.rst
@@ -14,13 +14,6 @@ capable of full-profile fitting of the atomic pair distribution function (PDF)
derived from x-ray or neutron diffraction data
and comes with built in graphical and structure visualization capabilities.
-PDFgui is also included in :doc:`xPDFsuite `,
-a powerful end-to-end software for X-ray PDF analysis.
-xPDFsuite is designed for flexible,
-high throughput PDF analyses and contains many features for interrogating, comparing and
-modeling data as well as simply doing data reduction.
-
-
.. figure:: ../images/PDFgui_screenshot_small.png
:align: center
@@ -31,7 +24,7 @@ Installation
============
By downloading and using this software you are agreeing to the
-conditions specified in the :doc:`software license `.
+conditions specified in the `software license `__.
PDFgui is distributed as a software package for
`Anaconda Python `__. PDFgui is available
@@ -43,48 +36,41 @@ As a prerequisite for PDFgui installation, download and install
or Anaconda Python (https://www.anaconda.com/download).
PDFgui is available from the "conda-forge" channel of Anaconda packages.
-To do so open a *Terminal* window or *Anaconda Command Prompt* and use
+
+To install it, first open a *Terminal* window or *Anaconda Command Prompt* and use
the :program:`conda` command as follows ::
- conda create --name=pdfgui2 python=3.9
- conda activate pdfgui2
- conda install -c conda-forge diffpy.pdfgui
+ conda create --name=pdfgui_env --channel conda-forge diffpy.pdfgui
-PDFgui can be then started from a *Terminal* window or *Anaconda Command Prompt* by typing ::
+To use PDFgui you then have to activate this conda environment and type pdfgui. ::
+ conda activate pdfgui_env
pdfgui
-The PDFgui window will appear automatically. An alternative method on Windows is to start
+After a brief pause he PDFgui window will appear automatically. An alternative method on Windows is to start
PDFgui through the *Diffpy* start menu.
.. note::
- To start PDFgui from a Terminal make sure *pdfgui2* is
+ To start PDFgui from a Terminal make sure *pdfgui_env* is
the active Anaconda environment::
- conda activate pdfgui2
+ conda activate pdfgui_env
- Alternatively you can add the following line to your shell startup
+ Alternatively, on bash terminals you can add the following line to your shell startup
file :file:`.bashrc` to define an alias which will work in
any Anaconda environment ::
- alias pdfgui="/path/to/pdfgui2/bin/pdfgui"
+ alias pdfgui="/path/to/pdfgui_env/bin/pdfgui"
where ``/path/to`` needs to be adjusted according to the output of
``which pdfgui`` command.
-
-PDFgui updates
-==============
-
-The Anaconda package system makes it easy to prepare and distribute
-software updates and bugfixes. To update to the latest version of
-PDFgui use ::
-
- conda update -c conda-forge diffpy.pdfgui
-
-To use a bleeding edge development version, visit the project source
-repository at https://github.com/diffpy/diffpy.pdfgui and consult
-its README file.
+Please consider joining the `diffpy-users `__ Google group.
+News about updates and new releases will be made there, as well as it being a place to ask questions
+and find answers about using all diffpy programs.
+When you sign up,
+please leave a short message about why you are requesting to join as we have had spam accounts requesting access
+and so we want to know you are a legitimate user.
Other versions
From e6722cf4a9bb86356746e51e261afa26d97387f8 Mon Sep 17 00:00:00 2001
From: Simon Billinge
Date: Tue, 18 Feb 2025 08:20:19 -0500
Subject: [PATCH 02/46] fixed he typo and added arm64 instructions to
pdfgui.rst
---
products/pdfgui.rst | 54 ++++++++++++++++++++++++++++++++++++++-------
1 file changed, 46 insertions(+), 8 deletions(-)
diff --git a/products/pdfgui.rst b/products/pdfgui.rst
index c320f245..02110afe 100644
--- a/products/pdfgui.rst
+++ b/products/pdfgui.rst
@@ -37,18 +37,56 @@ or Anaconda Python (https://www.anaconda.com/download).
PDFgui is available from the "conda-forge" channel of Anaconda packages.
-To install it, first open a *Terminal* window or *Anaconda Command Prompt* and use
-the :program:`conda` command as follows ::
+There are currently two different sets of instructions o install it depending on your platform.
+If you want to install it on Windows, Linux, or a non-arm64 Mac OSX (i.e., if at the time of writing
+your Mac does not have an M1 or M2 chip) use the first set, otherwise the second set of instructions
- conda create --name=pdfgui_env --channel conda-forge diffpy.pdfgui
+Windows, macOS (non-Arm64), Linux
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-To use PDFgui you then have to activate this conda environment and type pdfgui. ::
+Add the "conda-forge" channel by running the following command in a terminal: ::
- conda activate pdfgui_env
- pdfgui
+ conda config --add channels conda-forge
-After a brief pause he PDFgui window will appear automatically. An alternative method on Windows is to start
-PDFgui through the *Diffpy* start menu.
+Create a new environment named ``diffpy.pdfgui_env`` (or any name of your choice) and
+install ``diffpy.pdfgui``: ::
+
+ conda create -n diffpy.pdfgui_env diffpy.pdfgui
+
+Activate the environment: ::
+
+ conda activate diffpy.pdfgui_env
+
+Confirm that the installation was successful: ::
+
+ python -c "import diffpy.pdfgui; print(diffpy.pdfgui.__version__)"
+
+macOS (Arm64)
+~~~~~~~~~~~~~
+
+Create a new conda environment ``diffpy.pdfgui_env``: ::
+
+ conda config --add channels conda-forge
+ conda create -n diffpy.pdfgui_env python=3.13
+
+Activate the environment: ::
+
+ conda activate diffpy.pdfgui_env
+
+It is necessary to get versions of pdffit2 built for Mac from Python package index (Pypi). To install
+pdffit2 from Pypi using ``pip`` to download and install the latest version from `Python Package Index `_: ::
+
+ conda install wxpython diffpy.utils matplotlib-base pycifrw
+ pip install diffpy.pdffit2
+
+Finally, we want to install PDFgui from conda-forge: ::
+
+ conda install diffpy.pdfgui --no-deps
+
+
+
+Running pdfgui:
+===============
.. note::
To start PDFgui from a Terminal make sure *pdfgui_env* is
From 996e9cfe403c969e2b1dffdac0666fef00805a10 Mon Sep 17 00:00:00 2001
From: Simon Billinge
Date: Tue, 18 Feb 2025 08:35:41 -0500
Subject: [PATCH 03/46] tweak the readme instructions after Connor
---
README.md | 157 ++++++++++++++++++++++++++++++++++--------------------
1 file changed, 99 insertions(+), 58 deletions(-)
diff --git a/README.md b/README.md
index 930f2425..0a9c7c0c 100644
--- a/README.md
+++ b/README.md
@@ -10,11 +10,10 @@ Sphinx sources for the [diffpy.org][site] web page.
- [Adding Citations](#adding-citations)
- [Adding Publications that Describe a DiffPy Project (the "Reference" Section)](#reference-section-1)
- [Adding Other Publications (the "Publication Using DiffPy-CMI" Section)](#reference-section-2)
-- [Publishing New Version of Existing Project](#new-version)
-- [Publishing New Project](#publishing-new-project)
+- [New Version of Existing Project](#new-version)
+- [New Project](#publishing-new-project)
- [Publishing Changes](#publishing-changes)
- [Testing Changes](#testing-changes)
- - [Contributors (Submitting Changes)](#submitting-changes)
- [Maintainers (Publishing Changes)](#publishing-changes)
@@ -26,18 +25,69 @@ This repository contains 3 branches:
2. [`master`][master] sources compiled to HTML format that are published via GitHub pages
3. [`archive`][archive] converted subversion repository for the old diffpy.org sources
-Please, see the [Wiki](https://github.com/diffpy/diffpy.github.io/wiki) for more
-information and tips about this project.
+The basic logic is we edit on the source branch and follow instructions below to build the
+sources. The built sources, in the form of html files, are then copied to the master branch
+which is what GitHub pages is configured to render.
+
+# Publishing New Version of an Existing Project
+
+For releasing an updated version of a project, first generate the release for the project and
+make sure it is successfully deployed at Pypi and conda-forge.
+
+If you would like to see Connor's commented out comments about how to link pdf versions of
+documentation manuals please see the raw source code of this readme. However, we are moving
+away from having separately built manuals.
+
+
+With the [`source` branch][source] checed out, edit the landing page of your project] (e.g.,
+`products/pdfgetx.rst` for PDFgetx3) to document and provide the updated version of your project.
+
+Once the preceding steps are complete, see
+the instructions of the [Publishing Changes](#submitting-changes) section for publishing these changes.
# Where to Make Changes
-## Adding Citations
+Here is a brief map of where in the sources to make updates when different things happen
+
+## A new paper has appeared describing a diffpy product
### Adding Publications that Describe a DiffPy Project (the "Reference" Section)
-When adding a new publication to the list of [references used within the website](https://www.diffpy.org/publications.html), add the citation text of the publication to the documentation *only once* as a named snippet in [abbreviations.txt](https://github.com/diffpy/diffpy.github.io/blob/source/abbreviations.txt#L286). For example:
+When adding a new publication to the list of [references used within the website](https://www.diffpy.org/publications.html), add the
+citation text of the publication to the documentation *only once* as a named snippet in
+[abbreviations.txt](https://github.com/diffpy/diffpy.github.io/blob/source/abbreviations.txt#L286). For example:
```
.. |citeJuhasJac18| replace::
P. Juhás, J. N. Louwen, L. van Eijck, E. T. C. Vogt, S. J. L. Billinge,
@@ -47,18 +97,33 @@ When adding a new publication to the list of [references used within the website
*J. Appl. Crystallogr.*, **51**, 1492--1497 (2018)
|downloadJuhasJac18|
```
-Here, `|citeJuhasJac18|` is the name that can be used elsewhere in the documentation and the Sphinx documentation generator will replace all instances of this tag with the indented text following the `replace::` directive.
+Here, `|citeJuhasJac18|` is the name that can be used elsewhere in the documentation and
+the Sphinx documentation generator will replace all instances of this tag with the indented
+text following the `replace::` directive.
-**Important:** After defining the publication's tag as described above, make sure to add the publication to the list of publications maintained in [publications.rst](https://github.com/diffpy/diffpy.github.io/blob/source/publications.rst). Make sure that you add the reference to the proper section and do so in descending reverse chronological order (i.e., the newest citations should appear at the top of their respective sections).
+**Important:** After defining the publication's tag as described above, make sure to add the
+publication to the list of publications maintained in [publications.rst](https://github.com/diffpy/diffpy.github.io/blob/source/publications.rst). Make sure that
+you add the reference to the proper section and do so in descending reverse chronological order
+(i.e., the newest citations should appear at the top of their respective sections).
-*Note:* In this example, the citation is for a publication which describes a product of the DiffPy-CMI project (namely, PDFgetN3). For publications which describe a component of DiffPy-CMI, we provide a link to download the publication directly from the [diffpy.org][site] website. Here, the link is provided via the `|downloadJuhasJac18|` tag which is the identifier for another snippet within [abbreviations.txt](https://github.com/diffpy/diffpy.github.io/blob/source/abbreviations.txt#L294) following the definition of `|citeJuhasJac18|`, seen here as:
+*Note:* In this example, the citation is for a publication
+which describes a product of the DiffPy-CMI project (namely, PDFgetN3). For publications which
+describe a component of DiffPy-CMI, we provide a link to download the publication directly from
+the [diffpy.org][site] website. Here, the link is provided via the `|downloadJuhasJac18|` tag
+which is the identifier for another snippet within [abbreviations.txt](https://github.com/diffpy/diffpy.github.io/blob/source/abbreviations.txt#L294) following the definition
+of `|citeJuhasJac18|`, seen here as:
```
.. |downloadJuhasJac18| image:: /images/pdficon_small.png
:target: /doc/pdfgetx/Juhas-jac-2018.pdf
```
-Furthermore, note that since the initial use of `|downloadJuhasJac18|` occurs within the indented text of the definition of `|citeJuhasJac18|`, the link to `|downloadJuhasJac18|` will appear everywhere `|citeJuhasJac18|` does.
+Furthermore, note that since the initial use of `|downloadJuhasJac18|` occurs within the indented text
+of the definition of `|citeJuhasJac18|`, the link to `|downloadJuhasJac18|` will appear
+everywhere `|citeJuhasJac18|` does.
-Lastly, make sure that the linked publication has been included within this project's files, placed in an appropriate directory (typically, the parent directory of the project that the paper relates to). In the above example, the publication covers the PDFgetN3 feature of the `pdfgetx` package, thus it is placed within `pdfgetx`'s documentation directory and referenced accordingly with the line
+Lastly, make sure that the linked publication has been included within this project's files, placed in
+an appropriate directory (typically, the parent directory of the project that the paper relates to). In
+the above example, the publication covers the PDFgetN3 feature of the `pdfgetx` package, thus it is
+placed within `pdfgetx`'s documentation directory and referenced accordingly with the line
```
:target: /doc/pdfgetx/Juhas-jac-2018.pdf
```
@@ -67,80 +132,56 @@ Lastly, make sure that the linked publication has been included within this proj
### Adding Other Publications (the "Publication Using DiffPy-CMI" Section)
-Adding references to publications that do not describe the release/use of a product within the DiffPy-CMI project (e.g., papers which use some component of DiffPy-CMI), we simply provide the usual citation text (with appropriate DOI link). To add a citation of this type, refer to the information in [Reference Section](#reference-section-1), but disregard everything starting at, and following, the [Note](#reference-section-note).
-
-
-
-# Publishing New Version of Existing Project
-
-For releasing an updated version of a project, first follow the release procedure outlined in the [group wiki](https://gitlab.thebillingegroup.com/resources/group-wiki/-/wikis/Finalizing-a-Project's-(Re)-Release) for packaging and deploying your project.
-
-In what follows, [pdfgetx v2.1.1](https://github.com/diffpy/diffpy.pdfgetx/releases/tag/v2.1.1) was chosen to show example commands for the steps outlined.
-
-After following the steps necessary for releasing your project, grab the set of documentation that will be provided with the deliverable upon user's request (typically, this would be something like the files hosted by GitHub on the GitHub releases page). Create a new directory for the updated version's documentation to live in
-```
-diffpy.github.io (source)$ mkdir static_root/doc/pdfgetx/2.1.1
-```
-Copy the updated documentation to this directory
-```
-diffpy.github.io (source)$ tar --directory=static_root/doc/pdfgetx/2.1.1/ \
- --strip-components=4 \
- -vxzf ~/Downloads/diffpy.pdfgetx-2.1.1.tar.gz \
- diffpy.pdfgetx-2.1.1/doc/manual/_build/PDFgetXNS3_manual.pdf
-
-diffpy.github.io (source)$ tar --directory=static_root/doc/pdfgetx/2.1.1/ \
- --strip-components=5 \
- --exclude=objects.inv \
- --exclude=.buildinfo \
- -vxzf ~/Downloads/diffpy.pdfgetx-2.1.1.tar.gz \
- diffpy.pdfgetx-2.1.1/doc/manual/_build/html/
-
-diffpy.github.io (source)$ cp ~/Downloads/pdfgetxn3-examples.zip \
- static_root/doc/pdfgetx/2.1.1/
-```
-Make sure to include all relevant files (e.g., `PDFgetXNS3_manual.pdf` and `pdfgetxn3-examples.zip`), exclude any files we don't want to provide to the user (e.g., `objects.inv` and `.buildinfo` from `diffpy.pdfgetx-2.1.1.tar.gz`)
-
-Finally, edit the [landing page of your project](https://github.com/diffpy/diffpy.github.io/blob/source/products/pdfgetx.rst) (in the [`source` branch][source]) to properly document and provide the updated version of your project. Once the preceding steps are complete, see the instructions of the [Publishing Changes](#submitting-changes) section for publishing these changes.
+Adding references to publications that do not describe the release/use of a product within the DiffPy-CMI
+project (e.g., papers which use some component of DiffPy-CMI), we simply provide the usual citation text (with
+appropriate DOI link). To add a citation of this type, refer to the information in [Reference Section](#reference-section-1), but
+disregard everything starting at, and following, the [Note](#reference-section-note).
# Publishing New Project
-For adding a new project to the website, see one of the existing projects (e.g., [pdfgetx](https://www.diffpy.org/products/pdfgetx.html)) as reference.
+For adding a new project to the website, see one of the existing projects (e.g., [pdfgetx](https://www.diffpy.org/products/pdfgetx.html)) as a reference.
-You will need to create a directory for the project to live in within (e.g., [/static_root/doc/pdfgetx](https://github.com/diffpy/diffpy.github.io/tree/source/static_root/doc/pdfgetx)), then write a landing page for the project (e.g., [/products/pdfgetx.rst](https://github.com/diffpy/diffpy.github.io/blob/source/products/pdfgetx.rst)) which will provide any necessary information or files needed for a user to use the project. Once this is complete, see [Publishing New Version of Existing Project](#new-version) for steps on publishing the project.
+You will need to create a directory for the project to live in within (e.g., [/static_root/doc/pdfgetx](https://github.com/diffpy/diffpy.github.io/tree/source/static_root/doc/pdfgetx)), then
+write a landing page for the project (e.g., [/products/pdfgetx.rst](https://github.com/diffpy/diffpy.github.io/blob/source/products/pdfgetx.rst)) which will provide any necessary information
+or files needed for a user to use the project. Once this is complete, see
+[Publishing New Version of Existing Project](#new-version) for steps on publishing the project.
# Publishing Changes
-In order to test and/or publish changes, activate a conda environment that has a working installation of Sphinx (or make sure you have the necessary packages installed at a system level). If unsure how to achieve this, see the [Install Sphinx](https://gitlab.thebillingegroup.com/resources/group-wiki/-/wikis/Finalizing-a-Project's-(Re)-Release#install-sphinx) section of the projecct release wiki.
+In order to test and/or publish changes, activate a conda environment that has a working installation of Sphinx
## Testing Changes
-Make sure you have an active installation of Sphinx as per [Publishing Changes](#publishing-changes), run the set of Sphinx validation command(s) to check that the static files that Sphinx will create to be served on the website are written properly:
+With your sphinx containing env activated, run the set of Sphinx validation command(s) to check that the static
+files that Sphinx will create to be served on the website are written properly:
```
diffpy.github.io (source)$ make linkcheck SPHINXOPTS="-W"
```
-*NOTE:* the `"-W"` flag forces warnings to be treated as errors. If you believe there is a falsely reported warning that should be ignored that is preventing the test from passing, rerun the above command with the `SPHINXOPTS="-W"` portion omitted.
+*NOTE:* the `"-W"` flag forces warnings to be treated as errors. If you believe there is a falsely reported
+warning that should be ignored that is preventing the test from passing, rerun the above command with the
+`SPHINXOPTS="-W"` portion omitted. Note that on Windows this seemed to generate a number of warnings
+not seen on linux and which didn't indicate anything broken.
Additionally, one can visually/user-experience validate that the changes are what is expected by running:
```
diffpy.github.io (source)$ make html
```
-Then opening `/_build/html/index.html` which will open a local instance of the website with the proposed changes in place.
-
-
-## Contributors (Submitting Changes)
-
-In order to update the contents of [diffpy.org][site], create a new branch off of [`source`][source] in your local fork of this repo and make whatever changes you need to. Once the desired edits are complete, follow the steps outlined in [Testing Changes](#testing-changes) to verify the site won't break as a result of these changes. Finally, after verifying that the changes won't break things, push your changes to your fork and open a pull-request to submit the changes back into this repo.
+Then opening `/_build/html/index.html` which will open a local instance of the website with the proposed changes
+in place.
## Maintainers (Publishing Changes)
-First, follow the steps outlines in [Testing Changes](#testing-changes) to verify that the changes won't mess things up (too bad). Note that these tests, as they currently exist, are not extensive and it's quite possible that something indeed may appear incorrectly on the website (hence the manual review portion). After reviewing the changes, have Sphinx generate the static files to be hosted on the website:
+First, follow the steps outlines in [Testing Changes](#testing-changes). Note that these tests, as they currently exist, are
+not extensive and it's quite possible that something indeed may appear incorrectly on the website (hence the manual
+review portion). After reviewing the changes, have Sphinx generate the static files to be hosted on the website:
```
diffpy.github.io (source)$ make html
```
+Note: this could not be run by successfully by simon on Git Bash. It can presumably be run from WSL?
Prepare the changes to be published:
```
diffpy.github.io (source)$ make publish-prepare
From 44ec84557ba28da1b81cd290d4ac2ccf43ff57a4 Mon Sep 17 00:00:00 2001
From: Simon Billinge
Date: Tue, 18 Feb 2025 11:36:01 -0500
Subject: [PATCH 04/46] fixing typos in pdfgui.rst
---
products/pdfgui.rst | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/products/pdfgui.rst b/products/pdfgui.rst
index 02110afe..eeab64d2 100644
--- a/products/pdfgui.rst
+++ b/products/pdfgui.rst
@@ -37,7 +37,7 @@ or Anaconda Python (https://www.anaconda.com/download).
PDFgui is available from the "conda-forge" channel of Anaconda packages.
-There are currently two different sets of instructions o install it depending on your platform.
+There are currently two different sets of instructions to install it depending on your platform.
If you want to install it on Windows, Linux, or a non-arm64 Mac OSX (i.e., if at the time of writing
your Mac does not have an M1 or M2 chip) use the first set, otherwise the second set of instructions
@@ -73,13 +73,13 @@ Activate the environment: ::
conda activate diffpy.pdfgui_env
-It is necessary to get versions of pdffit2 built for Mac from Python package index (Pypi). To install
-pdffit2 from Pypi using ``pip`` to download and install the latest version from `Python Package Index `_: ::
+It is necessary to get versions of pdffit2 built for Mac from Python package index (Pypi). First we will install all
+the dependencies from conda-forge and then the pdffit2 itself from Pypi using the following commands: ::
conda install wxpython diffpy.utils matplotlib-base pycifrw
pip install diffpy.pdffit2
-Finally, we want to install PDFgui from conda-forge: ::
+Finally, we want to install PDFgui, again from conda-forge: ::
conda install diffpy.pdfgui --no-deps
From 71877c62c6e622e0efc51617894d94082b8919ea Mon Sep 17 00:00:00 2001
From: Simon Billinge
Date: Tue, 18 Feb 2025 12:44:58 -0500
Subject: [PATCH 05/46] changed order of documentation and older versions in
pdfgui.rst
---
products/pdfgui.rst | 48 ++++++++++++++++++++++-----------------------
1 file changed, 24 insertions(+), 24 deletions(-)
diff --git a/products/pdfgui.rst b/products/pdfgui.rst
index eeab64d2..db3367af 100644
--- a/products/pdfgui.rst
+++ b/products/pdfgui.rst
@@ -111,8 +111,30 @@ please leave a short message about why you are requesting to join as we have had
and so we want to know you are a legitimate user.
-Other versions
-==============
+Documentation and help
+======================
+
+* The user manual is available in `HTML <../doc/pdfgui/index.html>`__
+ and `PDF <../doc/pdfgui/pdfgui.pdf>`__ formats.
+
+* Search "PDFgui" on YouTube for some video tutorials on how to use
+ PDFgui.
+
+* For in-depth help in using PDFgui to solve scientific problems please
+ see the book "Atomic Pair Distribution Function Analysis: A primer" by
+ Simon Billinge, Kirsten Jensen, and past and present Billinge group members,
+ published by Oxford University Press. Data for the worked examples can
+ be found here: https://github.com/Billingegroup/pdfttp_data
+
+* Tutorial files are available from
+ `pdfgui-tutorial.zip <../doc/pdfgui/pdfgui-tutorial.zip>`__.
+
+* Please, join the :doc:`community forum <../community>` for tips, tricks, and feedback.
+
+
+Legacy versions
+===============
+
v1.1.2 is the last python 2 version of PDFgui. It is no longer supported,
but may be needed to open python 2 generated `.ddp` project files. It can
be installed in a python2 anaconda environment using the commands::
@@ -150,28 +172,6 @@ Name Date Size Description
MD5 check sums for these installer files are available
`here `__.
-
-Documentation and help
-======================
-
-* The user manual is available in `HTML <../doc/pdfgui/index.html>`__
- and `PDF <../doc/pdfgui/pdfgui.pdf>`__ formats.
-
-* Search "PDFgui" on YouTube for some video tutorials on how to use
- PDFgui.
-
-* For in-depth help in using PDFgui to solve scientific problems please
- see the book "Atomic Pair Distribution Function Analysis: A primer" by
- Simon Billinge, Kirsten Jensen, and past and present Billinge group members,
- published by Oxford University Press. Data for the worked examples can
- be found here: https://github.com/Billingegroup/pdfttp_data
-
-* Tutorial files are available from
- `pdfgui-tutorial.zip <../doc/pdfgui/pdfgui-tutorial.zip>`__.
-
-* Please, join the :doc:`community forum <../community>` for tips, tricks, and feedback.
-
-
.. toctree::
:hidden:
From fefea69ad590e3b4f93f371eec8c7953ca00746b Mon Sep 17 00:00:00 2001
From: Sparks29032
Date: Sun, 23 Feb 2025 10:37:32 -0500
Subject: [PATCH 06/46] Added reference to cite if using this software.
---
products/pdfgui.rst | 15 ++++++++++++++-
1 file changed, 14 insertions(+), 1 deletion(-)
diff --git a/products/pdfgui.rst b/products/pdfgui.rst
index db3367af..71659e01 100644
--- a/products/pdfgui.rst
+++ b/products/pdfgui.rst
@@ -20,6 +20,19 @@ and comes with built in graphical and structure visualization capabilities.
Screen-shot of PDFgui during a refinement of multiple data-sets
+Reference
+=========
+
+If you use this program for a scientific research that leads to publication,
+we ask that you acknowledge use of the program by citing the following paper
+in your publication:
+
+ C L Farrow, P Juhas, J W Liu, D Bryndin, E S Božin,
+ J Bloch, Th Proffen and S J L Billinge, `PDFfit2 and PDFgui:
+ computer programs for studying nanostructure in crystals `_,
+ J. Phys.: Condens. Matter 19 (2007) 335219.
+
+
Installation
============
@@ -81,7 +94,7 @@ the dependencies from conda-forge and then the pdffit2 itself from Pypi using th
Finally, we want to install PDFgui, again from conda-forge: ::
- conda install diffpy.pdfgui --no-deps
+ pip install diffpy.pdfgui
From e532e6bfeb9b7f0d378cd113bf057052b8915b76 Mon Sep 17 00:00:00 2001
From: Caden Myers
Date: Tue, 16 Sep 2025 15:59:09 -0400
Subject: [PATCH 07/46] docs: update installation instructions
---
products/diffpycmi/index.rst | 186 ++++++++++++++++++++++++++---------
1 file changed, 138 insertions(+), 48 deletions(-)
diff --git a/products/diffpycmi/index.rst b/products/diffpycmi/index.rst
index 4134436a..70f6a4d4 100644
--- a/products/diffpycmi/index.rst
+++ b/products/diffpycmi/index.rst
@@ -1,26 +1,19 @@
##########
-DiffPy-CMI
+DiffPy.CMI
##########
-DiffPy-CMI is our complex modeling framework. It is a highly flexible
-library of Python modules for robust modeling of nanostructures in
-crystals, nanomaterials, and amorphous materials.
-
-The software provides functionality for storage and manipulation of
-structure data and calculation of structure-based quantities, such as
-PDF, SAS, bond valence sums, atom overlaps, bond lengths, and
-coordinations. Most importantly the DiffPy-CMI package contains a
-fitting framework for combining multiple experimental inputs in a single
-optimization problem.
-
-This is an early release of code that is under intense development, with
-support for installation on Unix, Linux, and Macintosh machines. The
-scope and documentation of the project will evolve rapidly, but we want
-to make the code available at the earliest possible date. Please make
-use of the software and provide feedback and suggestions for
-improvement, but please be patient and check back frequently for
-updates.
+Diffpy.cmi is designed as an extensible complex modeling infrastructure.
+Users and developers can readily integrate novel data types and constraints
+into custom workflows. While widely used for advanced analysis of structural
+data, the framework is general and can be applied to any problem where model
+parameters are refined to fit calculated quantities to data.
+Diffpy.cmi is a community-driven project that supports Unix, Linux, macOS,
+and Windows platforms. It is designed to be used in Python scripts enabling
+flexible scripting and automation for advanced and reproducible workflows.
+Users are encouraged to leverage the software for their modeling needs and
+to contribute feedback, use cases, and extensions through the project
+community.
.. figure:: ../../images/diffpycmi_screenshot.png
@@ -30,38 +23,135 @@ updates.
Installation
============
+To install ``diffpy.cmi``, create a new conda environment or activate an existing environment and install the package from the conda-forge channel.
+
+.. code-block:: bash
+
+ conda create -n diffpy.cmi-env
+ conda install -c conda-forge diffpy.cmi
+ conda activate diffpy.cmi-env
+
+To confirm that the installation was successful, type
+
+.. code-block:: bash
+
+ cmi --version
+
+The output should print the latest version.
+
+If the above does not work, you can use ``pip`` to download and install the latest release from
+`Python Package Index `_.
+To install using ``pip`` into your ``diffpy.cmi_env`` environment, type
+
+.. code-block:: bash
+
+ pip install diffpy.cmi
+
+Pack and Profile Installation
+-----------------------------
+
+Use the `cmi` command-line interface to install and manage modular optional dependencies, known as `packs`,
+and to configure or execute user-defined workflows that combine multiple packs with optional post-installation steps,
+known as `profiles`. To use `cmi`, you can run the following example commands:
+
+Show available commands and options with,
+
+.. code-block:: bash
+
+ cmi -h
+
+List installed and available packs and profiles,
+
+.. code-block:: bash
+
+ cmi pack list
+ cmi profile list
+
+Show details of a specific pack or profile,
+
+.. code-block:: bash
+
+ cmi pack show
+ cmi profile show
+
+Install a pack or profile (by name or path),
+
+.. code-block:: bash
-Use of this software is subject to the conditions in
-software :doc:`LICENSE `.
+ cmi install
+ cmi install
+ cmi install
-As of version 3.0 DiffPy-CMI is available for Linux and
-Mac as a collection of packages for Anaconda Python. As
-a first step download and install **Anaconda for Python 3.7**
-from |anaconda-download|.
+.. admonition:: Example installation
-.. note::
- DiffPy-CMI is available from the "diffpy" channel of Anaconda packages. It requires Python 3.5 or later or 2.7. It is recommended to install it in a separate Anaconda environment, for example *py37* or other preferred python versions.
- Make sure that *py37* environment is activated when working with DiffPy-CMI. ::
+ For example, to install the pack for PDF modeling, type,
- conda create --name=py37 python=3.7
- conda activate py37
+ .. code-block:: bash
-Once Anaconda is ready, DiffPy-CMI can be installed from the "diffpy"
-channel of Anaconda packages as follows ::
+ cmi install pdf
- conda config --add channels diffpy
- conda install diffpy-cmi
+ To check to see if the pack was installed, type,
-The software distribution over Anaconda makes it easy to publish
-frequent software updates. To update your installation later use ::
+ .. code-block:: bash
- conda update diffpy-cmi
+ cmi pack list
-If you don't want to use Anaconda you can
-:doc:`install DiffPy-CMI from sources `. Note that
-this method takes more time and requires more experience
-with the operating system.
+ The output should look something like this,
+ .. code-block:: bash
+
+ Installed:
+ - core
+ - pdf
+ Available to install:
+ - plotting
+ - tests
+ - docs
+
+
+Download examples
+-----------------
+
+To list and copy example scripts and data to your working directory, type,
+
+.. code-block:: bash
+
+ cmi example list
+ cmi example copy
+
+.. admonition:: Example
+
+ For example, to see the example scripts for PDF fitting, type,
+
+ .. code-block:: bash
+
+ cmi example list
+
+ The output should look something like this,
+
+ .. code-block:: bash
+
+ ch03NiModelling
+ ch05Fit2Phase
+ ch06RefineCrystalStructureGen
+ ch07StructuralPhaseTransitions
+ ch08NPRefinement
+ ch11ClusterXYZ
+
+ To copy the example for bulk Ni PDF fitting, type,
+
+ .. code-block:: bash
+
+ cmi example copy ch03NiModelling
+
+ This will copy the example directory ``ch03NiModelling`` to your current working directory. Within this directory exists
+ the scripts and data to fit the bulk Ni PDF.
+
+ You can then run the fitting script with,
+
+ .. code-block:: bash
+
+ python ch03NiModelling/solutions/diffpy-cmi/fitBulkNi.py
What next?
==========
@@ -78,11 +168,11 @@ What next?
Tutorials
=========
-* ADD2019_ school and conference --
- https://github.com/diffpy/add2019-diffpy-cmi
-
-.. _ADD2019: https://workshops.ill.fr/event/133/page/32-home
+* Worked examples and experimental data from the book are freely available at our
+ `GitHub repository `_.
+* ADD2019 school and conference --
+ https://github.com/diffpy/add2019-diffpy-cmi
Documentation
=============
@@ -101,8 +191,8 @@ at the links below.
* |doc-libdiffpy|_ -- C++ library for calculation of PDF and other real-space
quantities
-See :ref:`DiffPy-CMI contents ` for a complete list
-of open-source libraries that are included in DiffPy-CMI and
+See :ref:`DiffPy.CMI contents ` for a complete list
+of open-source libraries that are included in DiffPy.CMI and
their respective project pages.
@@ -110,7 +200,7 @@ Reference
=========
If you use this software in a research work which leads to publication,
-we ask you to acknowledge the use of DiffPy-CMI by citing the following
+we ask you to acknowledge the use of DiffPy.CMI by citing the following
paper:
* |citeJuhasAca15|
From 140c0504c34d17b2cd1d6a0018349b53aff58099 Mon Sep 17 00:00:00 2001
From: Caden Myers
Date: Tue, 16 Sep 2025 15:59:18 -0400
Subject: [PATCH 08/46] move diffpy-cmi to diffpy.cmi
---
README.md | 12 ++++++------
_templates/menu01.html | 2 +-
abbreviations.txt | 2 +-
products/diffpycmi/LICENSE.txt | 6 +++---
products/diffpycmi/cmi_exchange.rst | 6 +++---
products/diffpycmi/contents.rst | 4 ++--
products/diffpycmi/contributecode.rst | 2 +-
products/diffpycmi/install.rst | 14 +++++++-------
products/diffpycmi/license.rst | 4 ++--
products/diffpycmi/updatesources.rst | 2 +-
products/mPDF.rst | 4 ++--
products/xPDFsuite.rst | 2 +-
products/xinterpdf.rst | 4 ++--
publications.rst | 2 +-
.../doc/pdfgetx/2.0.0/_sources/tutorial.rst.txt | 6 +++---
static_root/doc/pdfgetx/2.0.0/tutorial.html | 4 ++--
.../doc/pdfgetx/2.1.0/_sources/tutorial.rst.txt | 6 +++---
static_root/doc/pdfgetx/2.1.0/tutorial.html | 6 +++---
.../doc/pdfgetx/2.1.1/_sources/tutorial.rst.txt | 6 +++---
static_root/doc/pdfgetx/2.1.1/tutorial.html | 6 +++---
.../doc/pdfgetx/2.1.2/_sources/tutorial.rst.txt | 6 +++---
static_root/doc/pdfgetx/2.1.2/tutorial.html | 6 +++---
.../doc/pdfgetx/2.2.0/_sources/tutorial.rst.txt | 6 +++---
static_root/doc/pdfgetx/2.2.0/tutorial.html | 6 +++---
.../doc/pdfgetx/2.2.1/_sources/tutorial.rst.txt | 6 +++---
static_root/doc/pdfgetx/2.2.1/tutorial.html | 6 +++---
26 files changed, 68 insertions(+), 68 deletions(-)
diff --git a/README.md b/README.md
index 0a9c7c0c..966abed9 100644
--- a/README.md
+++ b/README.md
@@ -9,7 +9,7 @@ Sphinx sources for the [diffpy.org][site] web page.
- [Where to Make Changes](#where-to-make-changes)
- [Adding Citations](#adding-citations)
- [Adding Publications that Describe a DiffPy Project (the "Reference" Section)](#reference-section-1)
- - [Adding Other Publications (the "Publication Using DiffPy-CMI" Section)](#reference-section-2)
+ - [Adding Other Publications (the "Publication Using DiffPy.CMI" Section)](#reference-section-2)
- [New Version of Existing Project](#new-version)
- [New Project](#publishing-new-project)
- [Publishing Changes](#publishing-changes)
@@ -107,8 +107,8 @@ you add the reference to the proper section and do so in descending reverse chro
(i.e., the newest citations should appear at the top of their respective sections).
*Note:* In this example, the citation is for a publication
-which describes a product of the DiffPy-CMI project (namely, PDFgetN3). For publications which
-describe a component of DiffPy-CMI, we provide a link to download the publication directly from
+which describes a product of the DiffPy.CMI project (namely, PDFgetN3). For publications which
+describe a component of DiffPy.CMI, we provide a link to download the publication directly from
the [diffpy.org][site] website. Here, the link is provided via the `|downloadJuhasJac18|` tag
which is the identifier for another snippet within [abbreviations.txt](https://github.com/diffpy/diffpy.github.io/blob/source/abbreviations.txt#L294) following the definition
of `|citeJuhasJac18|`, seen here as:
@@ -130,10 +130,10 @@ placed within `pdfgetx`'s documentation directory and referenced accordingly wit
-### Adding Other Publications (the "Publication Using DiffPy-CMI" Section)
+### Adding Other Publications (the "Publication Using DiffPy.CMI" Section)
-Adding references to publications that do not describe the release/use of a product within the DiffPy-CMI
-project (e.g., papers which use some component of DiffPy-CMI), we simply provide the usual citation text (with
+Adding references to publications that do not describe the release/use of a product within the DiffPy.CMI
+project (e.g., papers which use some component of DiffPy.CMI), we simply provide the usual citation text (with
appropriate DOI link). To add a citation of this type, refer to the information in [Reference Section](#reference-section-1), but
disregard everything starting at, and following, the [Note](#reference-section-note).
diff --git a/_templates/menu01.html b/_templates/menu01.html
index 6dc9147d..3c291077 100644
--- a/_templates/menu01.html
+++ b/_templates/menu01.html
@@ -7,7 +7,7 @@
diff --git a/static_root/doc/pdfgetx/2.1.0/_sources/tutorial.rst.txt b/static_root/doc/pdfgetx/2.1.0/_sources/tutorial.rst.txt
index af6ef5db..8ad44c46 100644
--- a/static_root/doc/pdfgetx/2.1.0/_sources/tutorial.rst.txt
+++ b/static_root/doc/pdfgetx/2.1.0/_sources/tutorial.rst.txt
@@ -644,14 +644,14 @@ the zero offset may change for different samples.
This tutorial requires either Linux or Mac OS X platforms,
because the PDF fitting is conducted with
-`DiffPy-CMI `__,
+`DiffPy.CMI `__,
which is not yet available for Windows.
-If DiffPy-CMI is not yet installed,
+If DiffPy.CMI is not yet installed,
we recommend to use `Anaconda Python`_ and set up a dedicated
Anaconda environment *nbcmi* for this tutorial.
This can be accomplished using the following steps::
- $ conda create -n nbcmi -c diffpy python=2 diffpy-cmi
+ $ conda create -n nbcmi -c diffpy python=2 diffpy.cmi
$ conda activate nbcmi
$ pip install path/to/diffpy.pdfgetx-VERSION.whl
diff --git a/static_root/doc/pdfgetx/2.1.0/tutorial.html b/static_root/doc/pdfgetx/2.1.0/tutorial.html
index 2ae28d28..f896a7b9 100644
--- a/static_root/doc/pdfgetx/2.1.0/tutorial.html
+++ b/static_root/doc/pdfgetx/2.1.0/tutorial.html
@@ -646,13 +646,13 @@ Fit twothetazero,
+DiffPy.CMI,
which is not yet available for Windows.
-If DiffPy-CMI is not yet installed,
+If DiffPy.CMI is not yet installed,
we recommend to use Anaconda Python and set up a dedicated
Anaconda environment nbcmi for this tutorial.
This can be accomplished using the following steps:
-$ conda create -n nbcmi -c diffpy python=2 diffpy-cmi
+$ conda create -n nbcmi -c diffpy python=2 diffpy.cmi
$ conda activate nbcmi
$ pip install path/to/diffpy.pdfgetx-VERSION.whl
diff --git a/static_root/doc/pdfgetx/2.1.1/_sources/tutorial.rst.txt b/static_root/doc/pdfgetx/2.1.1/_sources/tutorial.rst.txt
index af6ef5db..8ad44c46 100644
--- a/static_root/doc/pdfgetx/2.1.1/_sources/tutorial.rst.txt
+++ b/static_root/doc/pdfgetx/2.1.1/_sources/tutorial.rst.txt
@@ -644,14 +644,14 @@ the zero offset may change for different samples.
This tutorial requires either Linux or Mac OS X platforms,
because the PDF fitting is conducted with
-`DiffPy-CMI
`__,
+`DiffPy.CMI `__,
which is not yet available for Windows.
-If DiffPy-CMI is not yet installed,
+If DiffPy.CMI is not yet installed,
we recommend to use `Anaconda Python`_ and set up a dedicated
Anaconda environment *nbcmi* for this tutorial.
This can be accomplished using the following steps::
- $ conda create -n nbcmi -c diffpy python=2 diffpy-cmi
+ $ conda create -n nbcmi -c diffpy python=2 diffpy.cmi
$ conda activate nbcmi
$ pip install path/to/diffpy.pdfgetx-VERSION.whl
diff --git a/static_root/doc/pdfgetx/2.1.1/tutorial.html b/static_root/doc/pdfgetx/2.1.1/tutorial.html
index 504ebc88..48e0e229 100644
--- a/static_root/doc/pdfgetx/2.1.1/tutorial.html
+++ b/static_root/doc/pdfgetx/2.1.1/tutorial.html
@@ -646,13 +646,13 @@ Fit twothetazero,
+DiffPy.CMI,
which is not yet available for Windows.
-If DiffPy-CMI is not yet installed,
+If DiffPy.CMI is not yet installed,
we recommend to use Anaconda Python and set up a dedicated
Anaconda environment nbcmi for this tutorial.
This can be accomplished using the following steps:
-$ conda create -n nbcmi -c diffpy python=2 diffpy-cmi
+$ conda create -n nbcmi -c diffpy python=2 diffpy.cmi
$ conda activate nbcmi
$ pip install path/to/diffpy.pdfgetx-VERSION.whl
diff --git a/static_root/doc/pdfgetx/2.1.2/_sources/tutorial.rst.txt b/static_root/doc/pdfgetx/2.1.2/_sources/tutorial.rst.txt
index af6ef5db..8ad44c46 100644
--- a/static_root/doc/pdfgetx/2.1.2/_sources/tutorial.rst.txt
+++ b/static_root/doc/pdfgetx/2.1.2/_sources/tutorial.rst.txt
@@ -644,14 +644,14 @@ the zero offset may change for different samples.
This tutorial requires either Linux or Mac OS X platforms,
because the PDF fitting is conducted with
-`DiffPy-CMI
`__,
+`DiffPy.CMI `__,
which is not yet available for Windows.
-If DiffPy-CMI is not yet installed,
+If DiffPy.CMI is not yet installed,
we recommend to use `Anaconda Python`_ and set up a dedicated
Anaconda environment *nbcmi* for this tutorial.
This can be accomplished using the following steps::
- $ conda create -n nbcmi -c diffpy python=2 diffpy-cmi
+ $ conda create -n nbcmi -c diffpy python=2 diffpy.cmi
$ conda activate nbcmi
$ pip install path/to/diffpy.pdfgetx-VERSION.whl
diff --git a/static_root/doc/pdfgetx/2.1.2/tutorial.html b/static_root/doc/pdfgetx/2.1.2/tutorial.html
index f7293751..761ff7fb 100644
--- a/static_root/doc/pdfgetx/2.1.2/tutorial.html
+++ b/static_root/doc/pdfgetx/2.1.2/tutorial.html
@@ -646,13 +646,13 @@ Fit twothetazero,
+DiffPy.CMI,
which is not yet available for Windows.
-If DiffPy-CMI is not yet installed,
+If DiffPy.CMI is not yet installed,
we recommend to use Anaconda Python and set up a dedicated
Anaconda environment nbcmi for this tutorial.
This can be accomplished using the following steps:
-$ conda create -n nbcmi -c diffpy python=2 diffpy-cmi
+$ conda create -n nbcmi -c diffpy python=2 diffpy.cmi
$ conda activate nbcmi
$ pip install path/to/diffpy.pdfgetx-VERSION.whl
diff --git a/static_root/doc/pdfgetx/2.2.0/_sources/tutorial.rst.txt b/static_root/doc/pdfgetx/2.2.0/_sources/tutorial.rst.txt
index 7850ec08..671bc319 100644
--- a/static_root/doc/pdfgetx/2.2.0/_sources/tutorial.rst.txt
+++ b/static_root/doc/pdfgetx/2.2.0/_sources/tutorial.rst.txt
@@ -644,14 +644,14 @@ the zero offset may change for different samples.
This tutorial requires either Linux or Mac OS X platforms,
because the PDF fitting is conducted with
-`DiffPy-CMI
`__,
+`DiffPy.CMI `__,
which is not yet available for Windows.
-If DiffPy-CMI is not yet installed,
+If DiffPy.CMI is not yet installed,
we recommend to use `Anaconda Python`_ and set up a dedicated
Anaconda environment *nbcmi* for this tutorial.
This can be accomplished using the following steps::
- $ conda create -n nbcmi -c diffpy python=2 diffpy-cmi
+ $ conda create -n nbcmi -c diffpy python=2 diffpy.cmi
$ conda activate nbcmi
$ pip install path/to/diffpy.pdfgetx-VERSION.whl
diff --git a/static_root/doc/pdfgetx/2.2.0/tutorial.html b/static_root/doc/pdfgetx/2.2.0/tutorial.html
index cb47ae94..1cb9b30f 100644
--- a/static_root/doc/pdfgetx/2.2.0/tutorial.html
+++ b/static_root/doc/pdfgetx/2.2.0/tutorial.html
@@ -646,13 +646,13 @@ Fit twothetazero,
+DiffPy.CMI,
which is not yet available for Windows.
-If DiffPy-CMI is not yet installed,
+If DiffPy.CMI is not yet installed,
we recommend to use Anaconda Python and set up a dedicated
Anaconda environment nbcmi for this tutorial.
This can be accomplished using the following steps:
-$ conda create -n nbcmi -c diffpy python=2 diffpy-cmi
+$ conda create -n nbcmi -c diffpy python=2 diffpy.cmi
$ conda activate nbcmi
$ pip install path/to/diffpy.pdfgetx-VERSION.whl
diff --git a/static_root/doc/pdfgetx/2.2.1/_sources/tutorial.rst.txt b/static_root/doc/pdfgetx/2.2.1/_sources/tutorial.rst.txt
index 7850ec08..671bc319 100644
--- a/static_root/doc/pdfgetx/2.2.1/_sources/tutorial.rst.txt
+++ b/static_root/doc/pdfgetx/2.2.1/_sources/tutorial.rst.txt
@@ -644,14 +644,14 @@ the zero offset may change for different samples.
This tutorial requires either Linux or Mac OS X platforms,
because the PDF fitting is conducted with
-`DiffPy-CMI
`__,
+`DiffPy.CMI `__,
which is not yet available for Windows.
-If DiffPy-CMI is not yet installed,
+If DiffPy.CMI is not yet installed,
we recommend to use `Anaconda Python`_ and set up a dedicated
Anaconda environment *nbcmi* for this tutorial.
This can be accomplished using the following steps::
- $ conda create -n nbcmi -c diffpy python=2 diffpy-cmi
+ $ conda create -n nbcmi -c diffpy python=2 diffpy.cmi
$ conda activate nbcmi
$ pip install path/to/diffpy.pdfgetx-VERSION.whl
diff --git a/static_root/doc/pdfgetx/2.2.1/tutorial.html b/static_root/doc/pdfgetx/2.2.1/tutorial.html
index df564fed..24348192 100644
--- a/static_root/doc/pdfgetx/2.2.1/tutorial.html
+++ b/static_root/doc/pdfgetx/2.2.1/tutorial.html
@@ -646,13 +646,13 @@ Fit twothetazero,
+DiffPy.CMI,
which is not yet available for Windows.
-If DiffPy-CMI is not yet installed,
+If DiffPy.CMI is not yet installed,
we recommend to use Anaconda Python and set up a dedicated
Anaconda environment nbcmi for this tutorial.
This can be accomplished using the following steps:
-$ conda create -n nbcmi -c diffpy python=2 diffpy-cmi
+$ conda create -n nbcmi -c diffpy python=2 diffpy.cmi
$ conda activate nbcmi
$ pip install path/to/diffpy.pdfgetx-VERSION.whl
From ce22cb3c8c50d3e299739d932fa02c182ea3f2e8 Mon Sep 17 00:00:00 2001
From: Caden Myers
Date: Tue, 16 Sep 2025 16:17:54 -0400
Subject: [PATCH 09/46] add link to cmi docs
---
products/diffpycmi/index.rst | 7 +++++--
1 file changed, 5 insertions(+), 2 deletions(-)
diff --git a/products/diffpycmi/index.rst b/products/diffpycmi/index.rst
index 70f6a4d4..3043de56 100644
--- a/products/diffpycmi/index.rst
+++ b/products/diffpycmi/index.rst
@@ -168,11 +168,14 @@ What next?
Tutorials
=========
-* Worked examples and experimental data from the book are freely available at our
+* A step-by-step tutorial on using diffpy.cmi for PDF analysis is available at the documentation site for
+ ``DiffPy.CMI`` -- https://www.diffpy.org/diffpy.cmi/tutorials/index.html.
+
+* Worked examples and experimental data from the book *Atomic Pair Distribution Function Analysis: A Primer* are freely available at our
`GitHub repository `_.
* ADD2019 school and conference --
- https://github.com/diffpy/add2019-diffpy-cmi
+ https://github.com/diffpy/add2019-diffpy-cmi.
Documentation
=============
From 10dc537a2b376828b68fa9feffa9e5b03682e407 Mon Sep 17 00:00:00 2001
From: Caden Myers
Date: Wed, 17 Sep 2025 13:06:46 -0400
Subject: [PATCH 10/46] add alias for diffpy.cmi and manually change non-rst
file references
---
README.md | 12 ++++++------
_includes/substitutions.rst | 2 ++
_templates/menu01.html | 2 +-
abbreviations.txt | 2 +-
conf.py | 5 +++++
products/diffpycmi/LICENSE.txt | 6 +++---
products/diffpycmi/cmi_exchange.rst | 6 +++---
products/diffpycmi/contents.rst | 4 ++--
products/diffpycmi/contributecode.rst | 2 +-
products/diffpycmi/index.rst | 10 +++++-----
products/diffpycmi/install.rst | 14 +++++++-------
products/diffpycmi/license.rst | 4 ++--
products/diffpycmi/updatesources.rst | 2 +-
products/mPDF.rst | 4 ++--
products/xPDFsuite.rst | 2 +-
products/xinterpdf.rst | 4 ++--
publications.rst | 2 +-
.../doc/pdfgetx/2.0.0/_sources/tutorial.rst.txt | 4 ++--
static_root/doc/pdfgetx/2.0.0/tutorial.html | 4 ++--
.../doc/pdfgetx/2.1.0/_sources/tutorial.rst.txt | 4 ++--
static_root/doc/pdfgetx/2.1.0/tutorial.html | 4 ++--
.../doc/pdfgetx/2.1.1/_sources/tutorial.rst.txt | 4 ++--
static_root/doc/pdfgetx/2.1.1/tutorial.html | 4 ++--
.../doc/pdfgetx/2.1.2/_sources/tutorial.rst.txt | 4 ++--
static_root/doc/pdfgetx/2.1.2/tutorial.html | 4 ++--
.../doc/pdfgetx/2.2.0/_sources/tutorial.rst.txt | 4 ++--
static_root/doc/pdfgetx/2.2.0/tutorial.html | 4 ++--
.../doc/pdfgetx/2.2.1/_sources/tutorial.rst.txt | 4 ++--
static_root/doc/pdfgetx/2.2.1/tutorial.html | 4 ++--
29 files changed, 69 insertions(+), 62 deletions(-)
create mode 100644 _includes/substitutions.rst
diff --git a/README.md b/README.md
index 966abed9..f15d06d4 100644
--- a/README.md
+++ b/README.md
@@ -9,7 +9,7 @@ Sphinx sources for the [diffpy.org][site] web page.
- [Where to Make Changes](#where-to-make-changes)
- [Adding Citations](#adding-citations)
- [Adding Publications that Describe a DiffPy Project (the "Reference" Section)](#reference-section-1)
- - [Adding Other Publications (the "Publication Using DiffPy.CMI" Section)](#reference-section-2)
+ - [Adding Other Publications (the "Publication Using diffpy.cmi" Section)](#reference-section-2)
- [New Version of Existing Project](#new-version)
- [New Project](#publishing-new-project)
- [Publishing Changes](#publishing-changes)
@@ -107,8 +107,8 @@ you add the reference to the proper section and do so in descending reverse chro
(i.e., the newest citations should appear at the top of their respective sections).
*Note:* In this example, the citation is for a publication
-which describes a product of the DiffPy.CMI project (namely, PDFgetN3). For publications which
-describe a component of DiffPy.CMI, we provide a link to download the publication directly from
+which describes a product of the diffpy.cmi project (namely, PDFgetN3). For publications which
+describe a component of diffpy.cmi, we provide a link to download the publication directly from
the [diffpy.org][site] website. Here, the link is provided via the `|downloadJuhasJac18|` tag
which is the identifier for another snippet within [abbreviations.txt](https://github.com/diffpy/diffpy.github.io/blob/source/abbreviations.txt#L294) following the definition
of `|citeJuhasJac18|`, seen here as:
@@ -130,10 +130,10 @@ placed within `pdfgetx`'s documentation directory and referenced accordingly wit
-### Adding Other Publications (the "Publication Using DiffPy.CMI" Section)
+### Adding Other Publications (the "Publication Using diffpy.cmi" Section)
-Adding references to publications that do not describe the release/use of a product within the DiffPy.CMI
-project (e.g., papers which use some component of DiffPy.CMI), we simply provide the usual citation text (with
+Adding references to publications that do not describe the release/use of a product within the diffpy.cmi
+project (e.g., papers which use some component of diffpy.cmi), we simply provide the usual citation text (with
appropriate DOI link). To add a citation of this type, refer to the information in [Reference Section](#reference-section-1), but
disregard everything starting at, and following, the [Note](#reference-section-note).
diff --git a/_includes/substitutions.rst b/_includes/substitutions.rst
new file mode 100644
index 00000000..96287220
--- /dev/null
+++ b/_includes/substitutions.rst
@@ -0,0 +1,2 @@
+.. define global names and alias here
+.. |diffpycmi| replace:: diffpy.cmi
diff --git a/_templates/menu01.html b/_templates/menu01.html
index 3c291077..1a235d9b 100644
--- a/_templates/menu01.html
+++ b/_templates/menu01.html
@@ -7,7 +7,7 @@