Populate API

Author: Sparks29032

doc/source/api/diffpy.pdfmorph.example_package.rst

@@ -0,0 +1,28 @@
+:tocdepth: -1
+
+diffpy.pdfmorph.morph_helpers package
+=====================================
+
+.. automodule:: diffpy.pdfmorph.morph_helpers
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+Submodules
+----------
+
+diffpy.pdfmorph.morph_helpers.transformpdftordf module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: diffpy.pdfmorph.morph_helpers.transformpdftordf
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+diffpy.pdfmorph.morph_helpers.transformrdftopdf module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: diffpy.pdfmorph.morph_helpers.transformrdftopdf
+    :members:
+    :undoc-members:
+    :show-inheritance:

doc/source/api/diffpy.pdfmorph.morph_helpers.rst

@@ -0,0 +1,92 @@
+:tocdepth: -1
+
+diffpy.pdfmorph.morphs package
+==============================
+
+.. automodule:: diffpy.pdfmorph.morphs
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+Submodules
+----------
+
+diffpy.pdfmorph.morphs.morphishape module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: diffpy.pdfmorph.morphs.morphishape
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+diffpy.pdfmorph.morphs.morphchain module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: diffpy.pdfmorph.morphs.morphchain
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+diffpy.pdfmorph.morphs.morphresolution module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: diffpy.pdfmorph.morphs.morphresolution
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+diffpy.pdfmorph.morphs.morphshape module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: diffpy.pdfmorph.morphs.morphshape
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+diffpy.pdfmorph.morphs.morphshift module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: diffpy.pdfmorph.morphs.morphshift
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+diffpy.pdfmorph.morphs.morph module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: diffpy.pdfmorph.morphs.morph
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+diffpy.pdfmorph.morphs.morphrgrid module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: diffpy.pdfmorph.morphs.morphrgrid
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+diffpy.pdfmorph.morphs.morphsmear module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: diffpy.pdfmorph.morphs.morphsmear
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+diffpy.pdfmorph.morphs.morphstretch module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: diffpy.pdfmorph.morphs.morphstretch
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+diffpy.pdfmorph.morphs.morphscale module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: diffpy.pdfmorph.morphs.morphscale
+    :members:
+    :undoc-members:
+    :show-inheritance:

doc/source/api/diffpy.pdfmorph.morphs.rst

@@ -1,7 +1,7 @@
 :tocdepth: -1
 
 diffpy.pdfmorph package
-=======================================
+=======================
 
 .. automodule:: diffpy.pdfmorph
     :members:
@@ -12,15 +12,66 @@ Subpackages
 -----------
 
 .. toctree::
-   diffpy.pdfmorph.example_package
+    :titlesonly:
+
+    diffpy.pdfmorph.morphs
+    diffpy.pdfmorph.morph_helpers
 
 Submodules
 ----------
 
-diffpy.pdfmorph.example_submodule module
-------------------------------------------------------------
+diffpy.pdfmorph.pdfplot module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: diffpy.pdfmorph.pdfplot
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+diffpy.pdfmorph.pdfmorph_api module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: diffpy.pdfmorph.pdfmorph_api
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+diffpy.pdfmorph.refine module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: diffpy.pdfmorph.refine
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+diffpy.pdfmorph.tools module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: diffpy.pdfmorph.tools
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+diffpy.pdfmorph.pdfmorph_io module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: diffpy.pdfmorph.pdfmorph_io
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+diffpy.pdfmorph.log module
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: diffpy.pdfmorph.log
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+diffpy.pdfmorph.pdfmorphapp module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. automodule:: diffpy.pdfmorph.example_submodule
+.. automodule:: diffpy.pdfmorph.pdfmorphapp
     :members:
     :undoc-members:
     :show-inheritance:

doc/source/api/diffpy.pdfmorph.rst

@@ -13,19 +13,21 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import os
 import sys
 import time
 from importlib.metadata import version
+from pathlib import Path
+
+autodoc_mock_imports = [
+    "diffpy.utils",
+]
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-# sys.path.insert(0, os.path.abspath('.'))
-sys.path.insert(0, os.path.abspath("../.."))
-sys.path.insert(0, os.path.abspath("../../src"))
-
-# abbreviations
+# documentation root, use Path().resolve() to make it absolute, like shown here.
+# sys.path.insert(0, str(Path(".").resolve()))
+sys.path.insert(0, str(Path("../..").resolve()))
+sys.path.insert(0, str(Path("../../src").resolve()))  # abbreviations
 ab_authors = "Billinge Group members and community contributors"
 
 # -- General configuration ------------------------------------------------
@@ -38,8 +40,11 @@
 # ones.
 extensions = [
     "sphinx.ext.autodoc",
-    "sphinx.ext.intersphinx",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.todo",
     "sphinx.ext.viewcode",
+    "sphinx.ext.intersphinx",
+    "sphinx_rtd_theme",
     "m2r",
 ]
 

doc/source/conf.py

@@ -7,12 +7,49 @@ diffpy.pdfmorph - Tools for manipulating and comparing PDF profiles.
 | Software version |release|.
 | Last updated |today|.
 
+Introduction
+++++++++++++
+
+``PDFmorph`` is a Python package that increases the insight 
+researchers can obtain from measured atomic pair distribution functions 
+(PDFs) in a model-independent way. It was designed to help a 
+researcher answer the question: "Has my material undergone a phase 
+transition between these two measurements?"
+
+One approach is to compare the two PDFs in a plot and view the 
+difference curve underneath. However, significant signal can be seen in 
+the difference curve from benign effects such as thermal expansion (peak 
+shifts) and increased thermal motion (peak broadening) or a change in 
+scale due to differences in incident flux, for example. ``PDFmorph`` will 
+do its best to correct for these benign effects before computing and 
+plotting the difference curve. One measured PDF (typically that 
+collected under higher temperature) is identified as the target PDF and 
+the second PDF is then morphed by "stretching" (changing the r-axis to
+simulate a uniform lattice expansion), "smearing" (broadening peaks 
+through a uniform convolution to simulate increased thermal motion), and 
+"scaling" (self-explanatory). PDFmorph will vary the amplitude of the 
+morphing transformations to obtain the best fit between the morphed and 
+the target PDFs, then plot them on top of each other with the difference 
+plotted below.
+
+There are also a few other morphing transformations in the program.
+If no morphing transformation is specified, ``PDFmorph`` will return just
+the plotted PDFs.
+
+Finally, we note that though ``PDFmorph`` should work on other spectra 
+that are not PDFs, it has not been extensively tested beyond the PDF.
+
+To get started, please download our :download:`user manual  <../manual/pdfmorph.pdf>`
+or visit the :ref:`quick_start`.
+
 =======
 Authors
 =======
 
-diffpy.pdfmorph is developed by Billinge Group
-and its community contributors.
+``PDFmorph`` is developed by members of the Billinge Group at 
+Columbia University and Brookhaven National Laboratory including 
+Christopher L. Farrow, Christopher J. Wright, Pavol Juhás, Chia-Hao
+(Timothy) Liu, S. Matthew Román, and Simon J. L. Billinge.
 
 For a detailed list of contributors see
 https://github.com/diffpy/diffpy.pdfmorph/graphs/contributors.
@@ -30,6 +67,7 @@ Table of contents
 .. toctree::
    :titlesonly:
 
+   quickstart
    license
    release
    Package API <api/diffpy.pdfmorph>

doc/source/index.rst

@@ -5,7 +5,7 @@ PDFmorph Tutorial
 
 Welcome! This will be a quick tutorial to accquaint users with PDFmorph
 and some of what it can do. For a more detailed tutorial, check out
-our :download:`user manual <../pdfmorph.pdf>`.
+our :download:`user manual <../manual/pdfmorph.pdf>`.
 
 As we described in the README and installation instructions, please make
 sure that you are familiar with working with your command line terminal
@@ -36,7 +36,7 @@ Basic PDFmorph Workflow
     3. Using the ``mkdir`` command, create a directory where you'll
        store the tutorial PDF files and use the ``cd`` command to change
        into that directory. You can download the tutorial files
-       :download:`here <../../../tutorial/tutorialData.zip>`.
+       :download:`here <../../tutorial/tutorialData.zip>`.
        Then, ``cd`` into the ``tutorialData`` directory.
 
        * The files in this dataset were collected by Soham Banerjee
@@ -179,13 +179,14 @@ Enjoy the software!
 .. Additional PDFmorph Functionality/Exploration
 .. ---------------------------------------------
 .. TODO include undoped PDF example
+
 Extra Tutorials
 ===============
 PDFmorph has some more functionalities not showcased in the basic workflow above
 (see `pdfmorph --help` for an overview of these functionalities).
 Tutorials for these additional functionalities are included below. Additional
 files for these tutorials can be downloaded
-:download:`here <../../../tutorial/additionalData.zip>`.
+:download:`here <../../tutorial/additionalData.zip>`.
 
 Performing Multiple Morphs
 --------------------------