Merge pull request #139 from cadenmyers13/rst-migration

sbillinge · web-flow · commit edc5bd05b7a5 · 2025-06-13T13:18:35.000-04:00
skpkg: Update rst files, copyright year in license, and `autodoc_mock_import`
diff --git a/.gitignore b/.gitignore
@@ -10,6 +10,7 @@ __pycache__/
 .Python
 env/
 build/
+_build/
 develop-eggs/
 dist/
 downloads/
@@ -90,10 +91,3 @@ target/
 
 # Ipython Notebook
 .ipynb_checkpoints
-
-# version information
-setup.cfg
-/src/diffpy/*/version.cfg
-
-# Rever
-rever/
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -1,5 +1,5 @@
 =============
-Release Notes
+Release notes
 =============
 
 .. current developments
@@ -65,7 +65,7 @@ Release Notes
 * No notable functional changes from 1.4.1
 
 1.4.4rc0
-=====
+========
 
 **Fixed:**
 
diff --git a/LICENSE.rst b/LICENSE.rst
@@ -13,7 +13,7 @@ the following paper in your publication:
         in crystals (https://stacks.iop.org/0953-8984/19/335219), *J. Phys.: Condens. Matter*, 19, 335219 (2007)
 
 Copyright 2006-2007, Board of Trustees of Michigan State University,
-Copyright 2008-2024, Board of Trustees of Columbia University in the
+Copyright 2008-2025, Board of Trustees of Columbia University in the
 city of New York.  (Copyright holder indicated in each source file).
 
 For more information please visit the project web-page:
diff --git a/README.rst b/README.rst
@@ -8,7 +8,7 @@
         :target: https://diffpy.github.io/diffpy.pdffit2
         :height: 100px
 
-|PyPi| |Forge| |PythonVersion| |PR|
+|PyPI| |Forge| |PythonVersion| |PR|
 
 |CI| |Codecov| |Black| |Tracking|
 
@@ -26,7 +26,7 @@
 
 .. |PR| image:: https://img.shields.io/badge/PR-Welcome-29ab47ff
 
-.. |PyPi| image:: https://img.shields.io/pypi/v/diffpy.pdffit2
+.. |PyPI| image:: https://img.shields.io/pypi/v/diffpy.pdffit2
         :target: https://pypi.org/project/diffpy.pdffit2/
 
 .. |PythonVersion| image:: https://img.shields.io/pypi/pyversions/diffpy.pdffit2
@@ -87,19 +87,17 @@ The preferred method is to use `Miniconda Python
 <https://docs.conda.io/projects/miniconda/en/latest/miniconda-install.html>`_
 and install from the "conda-forge" channel of Conda packages.
 
-Add the "conda-forge" channel by running the following command in a terminal: ::
+To add "conda-forge" to the conda channels, run the following in a terminal. ::
 
         conda config --add channels conda-forge
 
-Create a new environment named ``diffpy.pdffit2_env`` and install ``diffpy.pdffit2``: ::
+We want to install our packages in a suitable conda environment.
+The following creates and activates a new environment named ``diffpy.pdffit2_env`` ::
 
         conda create -n diffpy.pdffit2_env diffpy.pdffit2
-
-Activate the environment: ::
-
         conda activate diffpy.pdffit2_env
 
-Confirm that the installation was successful: ::
+To confirm that the installation was successful, type ::
 
         python -c "import diffpy.pdffit2; print(diffpy.pdffit2.__version__)"
 
@@ -118,25 +116,20 @@ Install pdffit2 using ``pip`` to download and install the latest version from `P
 
         pip install diffpy.pdffit2
 
-Confirm that the installation was successful: ::
+To confirm that the installation was successful, type ::
 
         python -c "import diffpy.pdffit2; print(diffpy.pdffit2.__version__)"
 
-Build from source
-~~~~~~~~~~~~~~~~~
+If you prefer to install from sources, after installing the dependencies, obtain the source archive from
+`GitHub <https://github.com/diffpy/diffpy.pdffit2/>`_. Once installed, ``cd`` into your ``diffpy.pdffit2`` directory
+and run the following ::
 
-For advanced users, obtain the source archive, and in the ``diffpy.pdffit2`` directory, run ::
+        pip install .
 
-        conda create -n diffpy.pdffit2_env python=3.13 \
-                --file requirements/test.txt \
-                --file requirements/conda.txt \
-                --file requirements/build.txt
+Getting Started
+---------------
 
-Activate the environment, build the package, and run unit tests by following commands sequentially: ::
-
-        conda activate diffpy.pdffit2_env
-        pip install . --no-deps
-        pytest
+You may consult our `online documentation <https://diffpy.github.io/diffpy.pdffit2>`_ for tutorials and API references.
 
 Support and Contribute
 ----------------------
@@ -182,4 +175,9 @@ Before contributing, please read our `Code of Conduct <https://github.com/diffpy
 Contact
 -------
 
-For more information on diffpy.pdffit2 please visit the project `web-page <https://diffpy.github.io/>`_ or email Prof. Simon Billinge at sb2896@columbia.edu.
+For more information on diffpy.pdffit2 please visit the project `web-page <https://diffpy.github.io/>`_ or email Simon Billinge at sb2896@columbia.edu.
+
+Acknowledgements
+----------------
+
+``diffpy.pdffit2`` is built and maintained with `scikit-package <https://scikit-package.github.io/scikit-package/>`_.
diff --git a/doc/source/api/diffpy.pdffit2.rst b/doc/source/api/diffpy.pdffit2.rst
@@ -1,7 +1,9 @@
 :tocdepth: -1
 
-diffpy.pdffit2 package
-======================
+|title|
+=======
+
+.. |title| replace:: diffpy.pdffit2 package
 
 .. automodule:: diffpy.pdffit2
     :members:
diff --git a/doc/source/conf.py b/doc/source/conf.py
@@ -53,6 +53,10 @@
     "m2r",
 ]
 
+autodoc_mock_imports = [
+    "diffpy.pdffit2.pdffit2",
+]
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
diff --git a/doc/source/index.rst b/doc/source/index.rst
@@ -4,9 +4,9 @@
 
 .. |title| replace:: diffpy.pdffit2 documentation
 
-diffpy.pdffit2 - PDFfit2 - real space structure refinement program.
+``diffpy.pdffit2`` - PDFfit2 - real space structure refinement program.
 
-| Software version |release|.
+| Software version |release|
 | Last updated |today|.
 
 The diffpy.pdffit2 package provides functions for the calculation and
@@ -75,19 +75,25 @@ in your publication:
 Installation
 ============
 
-Please see the `README <https://github.com/diffpy/diffpy.pdffit2#installation>`_
+See the `README <https://github.com/diffpy/diffpy.pdffit2#installation>`_
 file included with the distribution.
 
+================
+Acknowledgements
+================
+
+``diffpy.pdffit2`` is built and maintained with `scikit-package <https://scikit-package.github.io/scikit-package/>`_.
+
 =================
 Table of contents
 =================
 .. toctree::
    :titlesonly:
 
-   license
-   release
    examples
    Package API <api/diffpy.pdffit2>
+   release
+   license
 
 =======
 Indices
diff --git a/doc/source/license.rst b/doc/source/license.rst
@@ -17,7 +17,7 @@ the following paper in your publication:
         in crystals (https://stacks.iop.org/0953-8984/19/335219), *J. Phys.: Condens. Matter*, 19, 335219 (2007)
 
 Copyright 2006-2007, Board of Trustees of Michigan State University,
-Copyright 2008-|year|, Board of Trustees of Columbia University in the
+Copyright 2008-2025, Board of Trustees of Columbia University in the
 city of New York.  (Copyright holder indicated in each source file).
 
 For more information please visit the project web-page:
diff --git a/news/rst-migration.rst b/news/rst-migration.rst
@@ -0,0 +1,23 @@
+**Added:**
+
+* <news item>
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* <news item>
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* Migrate documentation to `scikit-package 0.1.0` standards, including a mock import for API rendering.
+
+**Security:**
+
+* <news item>
diff --git a/src/diffpy/pdffit2/version.py b/src/diffpy/pdffit2/version.py
@@ -61,3 +61,5 @@ def get_pypi_release_date(package_name, timeout=5):
 __date__ = get_pypi_release_date("diffpy.pdffit2")
 
 # End of file
+
+# Release date: 2025-02-07

Original file line number	Diff line number	Diff line change
`@@ -53,6 +53,10 @@`
`53`	`53`	`"m2r",`
`54`	`54`	`]`
`55`	`55`
	`56`	`+autodoc_mock_imports = [`
	`57`	`+ "diffpy.pdffit2.pdffit2",`
	`58`	`+]`
	`59`	`+`
`56`	`60`	`# Add any paths that contain templates here, relative to this directory.`
`57`	`61`	`templates_path = ["_templates"]`
`58`	`62`