skpkg: user facing files and requirements

Author: cadenmyers13

.readthedocs.yaml

@@ -0,0 +1,13 @@
+version: 2
+
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "latest"
+
+python:
+  install:
+    - requirements: requirements/docs.txt
+
+sphinx:
+  configuration: doc/source/conf.py

README.rst

@@ -37,7 +37,35 @@
 
 Calculators for PDF, bond valence sum, and other quantities based on atom pair interaction.
 
-* LONGER DESCRIPTION HERE
+The diffpy.srreal package provides calculators for atomic pair distribution
+function (PDF), bond valence sums (BVS), atom overlaps for a hard-sphere
+model, bond distances and directions up to specified maximum distance.   The
+atomic structure models are represented with internal classes as non-periodic,
+periodic or structures with space group symmetries.  The package provides
+implicit adapters from diffpy.structure classes or from Crystal or Molecule
+objects from pyobjcryst.  Adapters can be easily defined for any other
+structure representations in Python allowing their direct use with the
+calculators.  Calculators support two evaluation models - BASIC, which
+performs a full pair-summation every time, and OPTIMIZED, which updates only
+pair contributions that have changed since the last evaluation.  Calculations
+can be split among parallel jobs using Python multiprocessing package or any
+other library that provides parallel map function.  PDF calculations can
+be done in two modes - either as a real-space summation of peak profiles
+(PDFCalculator) or as a reciprocal-space Debye summation and Fourier
+transform of the total scattering structure function (DebyePDFCalculator).
+
+The diffpy.srreal package is a Python binding to the C++ library libdiffpy
+(https://github.com/diffpy/libdiffpy).  Calculators are created as
+objects of a given calculator type and so multiple instances of the same
+calculator type can exist with different configurations.  Calculators are
+composed of other objects that perform lower-level tasks, such as calculating
+peak profile or looking up atom scattering factors.  These objects can be
+re-assigned at runtime allowing to easily customize the calculation procedure.
+New classes can be defined using object inheritance either in Python or in C++
+and used with the existing calculators; as an example, this allows to
+calculate PDF with a user-defined profile function.  A new calculator class
+can be also defined for any quantity that is obtained by iteration over atom
+pairs, by defining only the function that processes atom-pair contributions.
 
 For more information about the diffpy.srreal library, please consult our `online documentation <https://diffpy.github.io/diffpy.srreal>`_.
 

doc/source/api/diffpy.srreal.devutils.rst

@@ -0,0 +1,20 @@
+:tocdepth: -1
+
+diffpy.srreal.devutils package
+==============================
+
+.. automodule:: diffpy.srreal.devutils
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+Submodules
+----------
+
+diffpy.srreal.devutils.tunePeakPrecision module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: diffpy.srreal.devutils.tunePeakPrecision
+    :members:
+    :undoc-members:
+    :show-inheritance:

doc/source/conf.py

@@ -18,6 +18,12 @@
 from importlib.metadata import version
 from pathlib import Path
 
+# Attempt to import the version dynamically from GitHub tag.
+try:
+    fullversion = version("diffpy.srreal")
+except Exception:
+    fullversion = "No version found. The correct version will appear in the released version."  # noqa: E501
+
 # 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 Path().resolve() to make it absolute, like shown here.
@@ -43,6 +49,7 @@
     "sphinx.ext.viewcode",
     "sphinx.ext.intersphinx",
     "sphinx_rtd_theme",
+    "sphinx_copybutton",
     "m2r",
 ]
 
@@ -68,7 +75,6 @@
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 
-fullversion = version(project)
 # The short X.Y version.
 version = "".join(fullversion.split(".post")[:1])
 # The full version, including alpha/beta/rc tags.
@@ -88,6 +94,11 @@
 # substitute YEAR in the copyright string
 copyright = copyright.replace("%Y", year)
 
+# For sphinx_copybutton extension.
+# Do not copy "$" for shell commands in code-blocks.
+copybutton_prompt_text = r"^\$ "
+copybutton_prompt_is_regexp = True
+
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 exclude_patterns = ["build"]
@@ -123,6 +134,14 @@
 #
 html_theme = "sphinx_rtd_theme"
 
+html_context = {
+    "display_github": True,
+    "github_user": "diffpy",
+    "github_repo": "diffpy.srreal",
+    "github_version": "main",
+    "conf_py_path": "/doc/source/",
+}
+
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.

doc/source/getting-started.rst

@@ -0,0 +1,79 @@
+:tocdepth: -1
+
+.. index:: getting-started
+
+.. _getting-started:
+
+================
+Getting started
+================
+
+Here are some example templates provided to help you get started with writing your documentation. You can use these templates to create your own documentation.
+
+Reuse ``.rst`` files across multiple pages
+------------------------------------------
+
+Here is how you can reuse a reusable block of ``.rst`` files across multiple pages:
+
+.. include:: snippets/example-table.rst
+
+.. warning::
+
+    Ensure that the ``.rst`` file you are including is not too long. If it is too long, it may be better to split it into multiple files and include them separately.
+
+Refer to a specific section in the documentation
+------------------------------------------------
+
+You can use the ``ref`` tag to refer to a specific section in the documentation. For example, you can refer to the section below using the ``:ref:`` tag as shown :ref:`here <attach-image>`.
+
+.. note::
+
+    Please check the raw ``.rst`` file of this page to see the exact use of the ``:ref:`` tag.
+
+Embed your code snippets in the documentation
+---------------------------------------------
+
+Here is how you can write a block of code in the documentation. You can use the ``code-block`` directive to write a block of code in the documentation. For example, you can write a block of code as shown below:
+
+.. code-block:: bash
+
+    # Create a new environment, without build dependencies (pure Python package)
+    conda create -n <package_name>-env python=3.13 \
+        --file requirements/test.txt \
+        --file requirements/conda.txt
+
+    # Create a new environment, with build dependencies (non-pure Python package)
+    conda create -n <package_name>-env python=3.13 \
+        --file requirements/test.txt \
+        --file requirements/conda.txt \
+        --file requirements/build.txt
+
+    # Activate the environment
+    conda activate <package_name>_env
+
+    # Install your package locally
+    # `--no-deps` to NOT install packages again from `requirements.pip.txt`
+    pip install -e . --no-deps
+
+    # Run pytest locally
+    pytest
+
+    # ... run example tutorials
+
+.. _attach-image:
+
+Attach an image to the documentation
+------------------------------------
+
+Here is how you attach an image to the documentation. The ``/doc/source/img/scikit-package-logo-text.png`` example image is provided in the template.
+
+.. image:: ./img/scikit-package-logo-text.png
+    :alt: codecov-in-pr-comment
+    :width: 400px
+    :align: center
+
+
+Other useful directives
+-----------------------
+
+Here is how you can do menu selection  :menuselection:`Admin --> Settings` and display labels for buttons like :guilabel:`Privacy level`.

doc/source/index.rst

@@ -4,9 +4,9 @@
 
 .. |title| replace:: diffpy.srreal documentation
 
-diffpy.srreal - Calculators for PDF, bond valence sum, and other quantities based on atom pair interaction.
+``diffpy.srreal`` - Calculators for PDF, bond valence sum, and other quantities based on atom pair interaction.
 
-| Software version |release|.
+| Software version |release|
 | Last updated |today|.
 
 The diffpy.srreal package provides calculators for atomic pair distribution
@@ -66,6 +66,12 @@ Installation
 See the `README <https://github.com/diffpy/diffpy.srreal#installation>`_
 file included with the distribution.
 
+================
+Acknowledgements
+================
+
+``diffpy.srreal`` is built and maintained with `scikit-package <https://scikit-package.github.io/scikit-package/>`_.
+
 =================
 Table of contents
 =================

doc/source/license.rst

@@ -22,7 +22,7 @@ Copyright (c) 2008-2012, The Trustees of Columbia University in the City of New
 
 Copyright (c) 2014-2019, Brookhaven Science Associates, Brookhaven National Laboratory
 
-Copyright (c) 2024, The Trustees of Columbia University in the City of New York.
+Copyright (c) 2025, The Trustees of Columbia University in the City of New York.
 All rights reserved.
 
 The "DiffPy-CMI" is distributed subject to the following license conditions:

requirements/docs.txt

@@ -1,4 +1,5 @@
 sphinx
 sphinx_rtd_theme
+sphinx-copybutton
 doctr
 m2r