skpkg: migrate documentation, README, and public static files (#153)

* skpkg: migrate documentation

* skpkg: add config files for authors, changelog, code of conduct, license

* skpkg: add README.rst

* skpkg: add news files

* chore: add back necessary lines from the files

* chore: fix files according to comments in the review

Author: zmx27

CHANGELOG.rst

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

LICENSE.rst

@@ -1,7 +1,6 @@
 BSD 3-Clause License
 
-Copyright (c) 2023-2024, The Trustees of Columbia University
-in the City of New York.
+Copyright (c) 2023-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.snmf
         :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.snmf
+.. |PyPI| image:: https://img.shields.io/pypi/v/diffpy.snmf
         :target: https://pypi.org/project/diffpy.snmf/
 
 .. |PythonVersion| image:: https://img.shields.io/pypi/pyversions/diffpy.snmf
@@ -132,4 +132,9 @@ Before contributing, please read our `Code of Conduct <https://github.com/diffpy
 Contact
 -------
 
-For more information on diffpy.snmf please visit the project `web-page <https://diffpy.github.io/>`_ or email Prof. Simon Billinge at [email protected].
+For more information on diffpy.snmf please visit the project `web-page <https://diffpy.github.io/>`_ or email Simon J.L. Billinge group at [email protected].
+
+Acknowledgements
+----------------
+
+``diffpy.snmf`` is built and maintained with `scikit-package <https://scikit-package.github.io/scikit-package/>`_.

doc/source/conf.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 #
-# diffpy.snmf documentation build configuration file, created by
+# diffpy.snmf 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.snmf")
+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.snmf",
+    "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.
@@ -221,7 +240,13 @@
 # (source start file, target name, title,
 # author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    ("index", "diffpy.snmf.tex", "diffpy.snmf Documentation", ab_authors, "manual"),
+    (
+        "index",
+        "diffpy.snmf.tex",
+        "diffpy.snmf Documentation",
+        ab_authors,
+        "manual",
+    ),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -249,7 +274,15 @@
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [("index", "diffpy.snmf", "diffpy.snmf Documentation", ab_authors, 1)]
+man_pages = [
+    (
+        "index",
+        "diffpy.snmf",
+        "diffpy.snmf Documentation",
+        ab_authors,
+        1,
+    )
+]
 
 # If true, show URL addresses after external links.
 # man_show_urls = False

doc/source/index.rst

@@ -1,6 +1,11 @@
 Welcome to SNMF's Documentation!
 ====================================
 
+``diffpy.snmf`` - Python package implementing the stretched NMF algorithm.
+
+| Software version |release|
+| Last updated |today|.
+
 ``SNMF``: This library implements the stretched non negative matrix factorization (sNMF) and sparse stretched NMF
 (ssNMF) algorithms described in the paper "Stretched Non-negative Matrix Factorization" by Ran Gu et al. (2023),
 which is referenced under the Citation section below.
@@ -52,8 +57,9 @@ by citing the following paper in your publication:
    *npj Comput Mater* **10**, 193 (2024).
 
 
+=======
 Authors
--------
+=======
 
 ``snmf`` implements the algorithms described in ...., developed by members of the Billinge Group at
 Columbia University, Brookhaven National Laboratory, Stony Brook University, Nankai University, and Colorado State
@@ -68,6 +74,19 @@ For a detailed list of contributors, check `here
 
 To get started, please go to :ref:`quick_start`
 
+============
+Installation
+============
+
+See the `README <https://github.com/diffpy/diffpy.snmf#installation>`_
+file included with the distribution.
+
+================
+Acknowledgements
+================
+
+``diffpy.snmf`` is built and maintained with `scikit-package <https://scikit-package.github.io/scikit-package/>`_.
+
 .. toctree::
    :maxdepth: 3
    :hidden:
@@ -84,8 +103,9 @@ To get started, please go to :ref:`quick_start`
 
 .. include:: ../../CHANGELOG.rst
 
+=======
 Indices
--------
+=======
 
 * :ref:`genindex`
 * :ref:`search`

doc/source/license.rst

@@ -9,8 +9,7 @@ OPEN SOURCE LICENSE AGREEMENT
 =============================
 BSD 3-Clause License
 
-Copyright (c) 2023-2024, The Trustees of Columbia University in
-the City of New York.
+Copyright (c) 2023-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

news/doc.rst

@@ -0,0 +1,23 @@
+**Added:**
+
+* <news item>
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* <news item>
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* Support ``scikit-package`` Level 5 standard (https://scikit-package.github.io/scikit-package/).
+
+**Security:**
+
+* <news item>

requirements/docs.txt

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