Merge pull request #43 from dabeycorn/doc

skpkg: migrate documentation, README, and public static files

Author: sbillinge

.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

AUTHORS.rst

@@ -1,9 +1,9 @@
 Authors
 =======
 
-Simon J. L. Billinge
-Zachary A. Thatcher
-Billinge Group and community contributors.
+- Simon J. L. Billinge
+- Zachary A. Thatcher
+- Billinge Group members and community contributors
 
 Contributors
 ------------

CHANGELOG.rst

@@ -1,5 +1,5 @@
 =============
-Release Notes
+Release notes
 =============
 
 .. current developments

CODE_OF_CONDUCT.rst

@@ -8,7 +8,7 @@ Our Pledge
 We as members, contributors, and leaders pledge to make participation in our
 community a harassment-free experience for everyone, regardless of age, body
 size, visible or invisible disability, ethnicity, sex characteristics, gender
-identity and expression, level of experience, education, socio-economic status,
+identity and expression, level of experience, education, socioeconomic status,
 nationality, personal appearance, race, caste, color, religion, or sexual
 identity and orientation.
 

LICENSE.rst

@@ -1,7 +1,6 @@
 BSD 3-Clause License
 
-Copyright (c) 2022-2024, The Trustees of Columbia University
-in the City of New York.
+Copyright (c) 2022-2025, The Trustees of Columbia University in the City of New York.
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

README.rst

@@ -8,7 +8,7 @@
         :target: https://diffpy.github.io/diffpy.nmf_mapping
         :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.nmf_mapping
+.. |PyPI| image:: https://img.shields.io/pypi/v/diffpy.nmf_mapping
         :target: https://pypi.org/project/diffpy.nmf_mapping/
 
 .. |PythonVersion| image:: https://img.shields.io/pypi/pyversions/diffpy.nmf_mapping
@@ -105,15 +105,14 @@ and run the following ::
 Getting Started
 ---------------
 
-
 You may consult our `online documentation <https://diffpy.github.io/diffpy.nmf_mapping>`_ for tutorials and API references.
 
 Support and Contribute
 ----------------------
 
 `Diffpy user group <https://groups.google.com/g/diffpy-users>`_ is the discussion forum for general questions and discussions about the use of diffpy.nmf_mapping. Please join the diffpy.nmf_mapping users community by joining the Google group. The diffpy.nmf_mapping project welcomes your expertise and enthusiasm!
 
-If you see a bug or want to request a feature, please `report it as an issue <https://github.com/diffpy/diffpy.nmf_mapping/issues>`_ and/or `submit a fix as a PR <https://github.com/diffpy/diffpy.nmf_mapping/pulls>`_. You can also post it to the `Diffpy user group <https://groups.google.com/g/diffpy-users>`_.
+If you see a bug or want to request a feature, please `report it as an issue <https://github.com/diffpy/diffpy.nmf_mapping/issues>`_ and/or `submit a fix as a PR <https://github.com/diffpy/diffpy.nmf_mapping/pulls>`_.
 
 Feel free to fork the project and contribute. To install diffpy.nmf_mapping
 in a development mode, with its sources being directly used by Python
@@ -141,4 +140,9 @@ Before contributing, please read our `Code of Conduct <https://github.com/diffpy
 Contact
 -------
 
-For more information on diffpy.nmf_mapping please visit the project `web-page <https://diffpy.github.io/>`_ or email Prof. Simon Billinge at [email protected].
+For more information on diffpy.nmf_mapping please visit the project `web-page <https://diffpy.github.io/>`_ or email Simon J.L. Billinge group at [email protected].
+
+Acknowledgements
+----------------
+
+``diffpy.nmf_mapping`` is built and maintained with `scikit-package <https://scikit-package.github.io/scikit-package/>`_.

doc/source/api/diffpy.nmf_mapping.rst

@@ -1,28 +1,30 @@
 :tocdepth: -1
 
-diffpy.nmf-mapping package
-==========================
+|title|
+=======
+
+.. |title| replace:: diffpy.nmf_mapping package
 
 .. automodule:: diffpy.nmf_mapping
     :members:
     :undoc-members:
     :show-inheritance:
 
+Subpackages
+-----------
+
+.. toctree::
+   diffpy.nmf_mapping.example_package
+
 Submodules
 ----------
 
-diffpy.nmf_mapping.nmf_mapping_code module
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. automodule:: diffpy.nmf_mapping.nmf_mapping_code
-    :members:
-    :undoc-members:
-    :show-inheritance:
+|module|
+--------
 
-diffpy.nmf_mapping.main module
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. |module| replace:: diffpy.nmf_mapping.example_submodule module
 
-.. automodule:: diffpy.nmf_mapping.main
+.. automodule:: diffpy.nmf_mapping.example_submodule
     :members:
     :undoc-members:
     :show-inheritance:

doc/source/conf.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 #
-# diffpy.nmf_mapping documentation build configuration file, created by
+# diffpy.nmf_mapping documentation build configuration file, created by  # noqa: E501
 # sphinx-quickstart on Thu Jan 30 15:49:41 2014.
 #
 # This file is execfile()d with the current directory set to its
@@ -18,9 +18,15 @@
 from importlib.metadata import version
 from pathlib import Path
 
+# Attempt to import the version dynamically from GitHub tag.
+try:
+    fullversion = version("diffpy.nmf_mapping")
+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.
+# documentation root, use Path().resolve() to make it absolute, like shown here.  # noqa: E501
 # sys.path.insert(0, str(Path(".").resolve()))
 sys.path.insert(0, str(Path("../..").resolve()))
 sys.path.insert(0, str(Path("../../src").resolve()))
@@ -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.nmf_mapping",
+    "github_version": "main",
+    "conf_py_path": "/docs/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/img/.placeholder

@@ -4,19 +4,16 @@
 
 .. |title| replace:: diffpy.nmf_mapping documentation
 
-diffpy.nmf_mapping - Python package for running NMF analysis on PDF and XRD data..
+``diffpy.nmf_mapping`` - Python package for running NMF analysis on PDF and XRD data.
 
-| Software version |release|.
+| Software version |release|
 | Last updated |today|.
 
 =======
 Authors
 =======
 
-diffpy.nmf_mapping is developed by Billinge Group
-and its community contributors.
-
-For a detailed list of contributors see
+``diffpy.nmf_mapping`` is developed by Billinge Group members and community contributors. The maintainer for this project is Simon J.L. Billinge group. For a detailed list of contributors see
 https://github.com/diffpy/diffpy.nmf_mapping/graphs/contributors.
 
 ============
@@ -26,15 +23,21 @@ Installation
 See the `README <https://github.com/diffpy/diffpy.nmf_mapping#installation>`_
 file included with the distribution.
 
+================
+Acknowledgements
+================
+
+``diffpy.nmf_mapping`` is built and maintained with `scikit-package <https://scikit-package.github.io/scikit-package/>`_.
+
 =================
 Table of contents
 =================
 .. toctree::
-   :titlesonly:
+   :maxdepth: 2
 
-   license
-   release
    Package API <api/diffpy.nmf_mapping>
+   release
+   license
 
 =======
 Indices