Add tutorials/extension to docs nav bar, create pip.txt (#128)

* cap in description * Add news for doc nav * Install pip with pip.txt, conda with conda.txt * Overall doc paths and nav * Fix api doc table of content order * Add news on adding tutorials
diffpy · Oct 3, 2024 · c2ab7b0 · c2ab7b0
1 parent 2df560c
commit c2ab7b0
Show file tree

Hide file tree

Showing 16 changed files with 94 additions and 54 deletions.
diff --git a/README.rst b/README.rst
@@ -35,7 +35,7 @@
 .. |Tracking| image:: https://img.shields.io/badge/issue_tracking-github-blue
         :target: https://github.com/diffpy/diffpy.srmise/issues
 
-implementation of the ParSCAPE algorithm for peak extraction from atomic pair distribution functions (PDFs)
+Implementation of the ParSCAPE algorithm for peak extraction from atomic pair distribution functions (PDFs)
 
 SrMise is an implementation of the `ParSCAPE algorithm
 <https://dx.doi.org/10.1107/S2053273315005276>`_ for peak extraction from

diff --git a/doc/source/extending.rst b/doc/source/extending.rst
@@ -1,4 +1,4 @@
-.. _extending-srmise:
+.. index:: extending-srmise
 
 ===================
 Extending SrMise
@@ -47,7 +47,7 @@ To add a baseline, create a new module which defines a class inheriting from
 which need to be implemented are summarized in the source code.
 
 
-.. literalinclude:: ../../../diffpy/srmise/baselines/base.py
+.. literalinclude:: ../../src/diffpy/srmise/baselines/base.py
     :pyobject: BaselineFunction
     :end-before: __init__
 

diff --git a/doc/source/index.rst b/doc/source/index.rst
@@ -23,18 +23,21 @@ https://github.com/diffpy/diffpy.srmise/graphs/contributors.
 Installation
 ============
 
-See the `README <https://github.com/diffpy/diffpy.srmise#installation>`_
+See the `README <https://github.com/diffpy/diffpy.srmise/blob/main/README.rst>`_
 file included with the distribution.
 
 =================
 Table of contents
 =================
 .. toctree::
+   :maxdepth: 1
    :titlesonly:
 
-   license
-   release
+   tutorial/index
+   extending
    Package API <api/diffpy.srmise>
+   release
+   license
 
 =======
 Indices

diff --git a/doc/source/license.rst b/doc/source/license.rst
@@ -9,9 +9,25 @@ OPEN SOURCE LICENSE AGREEMENT
 =============================
 BSD 3-Clause License
 
-Copyright (c) 2024, The Trustees of Columbia University in
-the City of New York.
-All Rights Reserved.
+Copyright 2014-2015, Board of Trustees of Michigan State University
+
+Copyright 2016-2024, The Trustees of Columbia University in the City of New York.
+
+All rights reserved.
+
+If you use this program to do productive scientific research that
+leads to publication, we ask that you acknowledge use of the
+program by citing the following paper in your publication:
+
+    L. Granlund, S.J.L. Billinge, P.M. Duxbury, Algorithm for
+    systematic peak extraction from atomic pair distribution
+    functions, Acta Crystallographica A 71(4), 392-409 (2015).
+    doi:10.1107/S2053273315005276
+
+For more information please visit the diffpy web-page at
+    http://www.diffpy.org
+or email Luke Granlund at [email protected], or Prof. Simon
+Billinge at [email protected].
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met:
@@ -23,9 +39,9 @@ modification, are permitted provided that the following conditions are met:
    this list of conditions and the following disclaimer in the documentation
    and/or other materials provided with the distribution.
 
-3. Neither the name of the copyright holder nor the names of its
-   contributors may be used to endorse or promote products derived from
-   this software without specific prior written permission.
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
 
 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE

diff --git a/doc/source/tutorial/abbreviations.txt b/doc/source/tutorial/abbreviations.txt
@@ -10,21 +10,18 @@
 .. |tar.gz| replace:: :source-release:`tar.gz`
 
 .. Image substitutions
-.. |images/extract_single_peak1.png| image:: ../../../examples/images/extract_single_peak1.png
-.. |images/extract_single_peak2.png| image:: ../../../examples/images/extract_single_peak2.png
-.. |images/extract_single_peak3.png| image:: ../../../examples/images/extract_single_peak3.png
-.. |images/parameter_summary1.png| image:: ../../../examples/images/parameter_summary1.png
-.. |images/parameter_summary2.png| image:: ../../../examples/images/parameter_summary2.png
-.. |images/parameter_summary3.png| image:: ../../../examples/images/parameter_summary3.png
-.. |images/parameter_summary4.png| image:: ../../../examples/images/parameter_summary4.png
-.. |images/fit_initial1.png| image:: ../../../examples/images/fit_initial1.png
-.. |images/fit_initial2.png| image:: ../../../examples/images/fit_initial2.png
-.. |images/query_results1.png| image:: ../../../examples/images/query_results1.png
-.. |images/query_results2.png| image:: ../../../examples/images/query_results2.png
-.. |images/query_results3.png| image:: ../../../examples/images/query_results3.png
-
-.. Links to non-tutorial parts of documentation.
-.. |Extending SrMise| replace:: :ref:`extending-srmise`
+.. |images/extract_single_peak1.png| ge:: ../../examples/images/extract_single_peak1.png
+.. |images/extract_single_peak2.png| image:: ../../examples/images/extract_single_peak2.png
+.. |images/extract_single_peak3.png| image:: ../../examples/images/extract_single_peak3.png
+.. |images/parameter_summary1.png| image:: ../../examples/images/parameter_summary1.png
+.. |images/parameter_summary2.png| image:: ../../examples/images/parameter_summary2.png
+.. |images/parameter_summary3.png| image:: ../../examples/images/parameter_summary3.png
+.. |images/parameter_summary4.png| image:: ../../examples/images/parameter_summary4.png
+.. |images/fit_initial1.png| image:: ../../examples/images/fit_initial1.png
+.. |images/fit_initial2.png| image:: ../../examples/images/fit_initial2.png
+.. |images/query_results1.png| image:: ../../examples/images/query_results1.png
+.. |images/query_results2.png| image:: ../../examples/images/query_results2.png
+.. |images/query_results3.png| image:: ../../examples/images/query_results3.png
 
 .. External links
 .. _ParSCAPE algorithm: https://dx.doi.org/10.1107/S2053273315005276
@@ -42,3 +39,4 @@
 .. |pi/Qmax| replace:: π/Q\ :sub:`max`
 
 .. Links to PDF information defined in sample_links.txt
+.. |Extending SrMise| replace:: :ref:`extending-srmise`
diff --git a/doc/source/tutorial/extract_single_peak.rst b/doc/source/tutorial/extract_single_peak.rst
@@ -3,7 +3,7 @@
 .. include:: sample_links.txt
 
 
-.. include:: ../../../examples/README
+.. include:: ../../examples/README.rst
    :start-after: ~Example 1~
    :end-before: ~Example 2~
 
@@ -13,4 +13,4 @@
 Script (extract_single_peak.py)
 -------------------------------
 
-.. literalinclude:: ../../../examples/extract_single_peak.py
+.. literalinclude:: ../../examples/extract_single_peak.py
diff --git a/doc/source/tutorial/fit_initial.rst b/doc/source/tutorial/fit_initial.rst
@@ -3,7 +3,7 @@
 .. include:: sample_links.txt
 
 
-.. include:: ../../../examples/README
+.. include:: ../../examples/README.rst
    :start-after: ~Example 3~
    :end-before: ~Example 4~
 
@@ -13,4 +13,4 @@
 Script (fit_initial.py)
 ---------------------------
 
-.. literalinclude:: ../../../examples/fit_initial.py
+.. literalinclude:: ../../examples/fit_initial.py
diff --git a/doc/source/tutorial/index.rst b/doc/source/tutorial/index.rst
@@ -1,33 +1,29 @@
 .. include:: abbreviations.txt
 
-
 .. _tutorial:
 
 ===================
 Tutorial
 ===================
 
-.. include:: ../../../examples/README
+.. include:: ../../examples/README.rst
    :end-before: ~List of Examples~
 
 
 .. Replace bare list from README
 
-Examples
-========
-
 .. toctree::
    :maxdepth: 1
 
-   extract_single_peak.rst
-   parameter_summary.rst
-   fit_initial.rst
-   query_results.rst
-   multimodel_known_uncertainties.rst
-   multimodel_unknown_uncertainties.rst
+   extract_single_peak
+   parameter_summary
+   fit_initial
+   query_results
+   multimodel_known_uncertainties
+   multimodel_unknown_uncertainties
 
 
 .. Now add information about the samples
 
-.. include:: ../../../examples/README
+.. include:: ../../examples/README
    :start-after: ~PDF Info~
diff --git a/doc/source/tutorial/multimodel_known_uncertainties.rst b/doc/source/tutorial/multimodel_known_uncertainties.rst
@@ -3,7 +3,7 @@
 .. include:: sample_links.txt
 
 
-.. include:: ../../../examples/README
+.. include:: ../../examples/README.rst
    :start-after: ~Example 5~
    :end-before: ~Example 6~
 
@@ -14,12 +14,12 @@
 Extraction Script (multimodel_known_dG1.py)
 ---------------------------------------------
 
-.. literalinclude:: ../../../examples/multimodel_known_dG1.py
+.. literalinclude:: ../../examples/multimodel_known_dG1.py
 
 
 .. _multimodel_known_dG2.py:
 
 Analysis Script (multimodel_known_dG2.py)
 -----------------------------------------
 
-.. literalinclude:: ../../../examples/multimodel_known_dG2.py
+.. literalinclude:: ../../examples/multimodel_known_dG2.py
diff --git a/doc/source/tutorial/multimodel_unknown_uncertainties.rst b/doc/source/tutorial/multimodel_unknown_uncertainties.rst
@@ -3,7 +3,7 @@
 .. include:: sample_links.txt
 
 
-.. include:: ../../../examples/README
+.. include:: ../../examples/README.rst
    :start-after: ~Example 6~
    :end-before: ~PDF Info~
 
@@ -14,12 +14,12 @@
 Extraction Script (multimodel_unknown_dG1.py)
 ---------------------------------------------
 
-.. literalinclude:: ../../../examples/multimodel_unknown_dG1.py
+.. literalinclude:: ../../examples/multimodel_unknown_dG1.py
 
 
 .. _multimodel_unknown_dG2.py:
 
 Analysis Script (multimodel_unknown_dG2.py)
 -------------------------------------------
 
-.. literalinclude:: ../../../examples/multimodel_unknown_dG2.py
+.. literalinclude:: ../../examples/multimodel_unknown_dG2.py
diff --git a/doc/source/tutorial/parameter_summary.rst b/doc/source/tutorial/parameter_summary.rst
@@ -3,7 +3,7 @@
 .. include:: sample_links.txt
 
 
-.. include:: ../../../examples/README
+.. include:: ../../examples/README.rst
    :start-after: ~Example 2~
    :end-before: ~Example 3~
 
@@ -13,4 +13,4 @@
 Script (parameter_summary.py)
 -----------------------------
 
-.. literalinclude:: ../../../examples/parameter_summary.py
+.. literalinclude:: ../../examples/parameter_summary.py
diff --git a/doc/source/tutorial/query_results.rst b/doc/source/tutorial/query_results.rst
@@ -3,7 +3,7 @@
 .. include:: sample_links.txt
 
 
-.. include:: ../../../examples/README
+.. include:: ../../examples/README.rst
    :start-after: ~Example 4~
    :end-before: ~Example 5~
 
@@ -13,4 +13,4 @@
 Script (query_results.py)
 -------------------------
 
-.. literalinclude:: ../../../examples/query_results.py
+.. literalinclude:: ../../examples/query_results.py
diff --git a/news/add-nav.rst b/news/add-nav.rst
@@ -0,0 +1,24 @@
+**Added:**
+
+* <news item>
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* <news item>
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* add pip dependencies under pip.txt, conda dependencies under conda.txt
+* add tutorial and extending examples to docs
+
+**Security:**
+
+* <news item>
diff --git a/pyproject.toml b/pyproject.toml
@@ -52,7 +52,7 @@ exclude = ["diffpy.srmise.tests*"]  # exclude packages matching these glob patte
 namespaces = false  # to disable scanning PEP 420 namespaces (true by default)
 
 [tool.setuptools.dynamic]
-dependencies = {file = ["requirements/run.txt"]}
+dependencies = {file = ["requirements/pip.txt"]}
 
 [tool.black]
 line-length = 115

diff --git a/requirements/run.txt → requirements/conda.txt b/requirements/run.txt → requirements/conda.txt
diff --git a/requirements/pip.txt b/requirements/pip.txt
@@ -0,0 +1,3 @@
+numpy
+scipy
+matplotlib