skpkg: migrate documentation, README, and public static files

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.
 

README.rst

@@ -8,7 +8,7 @@
         :target: https://diffpy.github.io/diffpy.pdfgui
         :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.pdfgui
+.. |PyPI| image:: https://img.shields.io/pypi/v/diffpy.pdfgui
         :target: https://pypi.org/project/diffpy.pdfgui/
 
 .. |PythonVersion| image:: https://img.shields.io/pypi/pyversions/diffpy.pdfgui
@@ -35,7 +35,7 @@
 .. |Tracking| image:: https://img.shields.io/badge/issue_tracking-github-blue
         :target: https://github.com/diffpy/diffpy.pdfgui/issues
 
-Graphical user interface program for structure refinements to atomic
+Graphical user interface program for structure refinements to the atomic
 pair distribution function.
 
 For users who do not have the expertise or necessity for command
@@ -167,4 +167,9 @@ Before contributing, please read our `Code of Conduct <https://github.com/diffpy
 Contact
 -------
 
-For more information on diffpy.pdfgui please visit the project `web-page <https://diffpy.github.io/>`_ or email Prof. Simon Billinge at [email protected].
+For more information on diffpy.pdfgui please visit the project `web-page <https://diffpy.github.io/>`_ or email Simon Billinge at [email protected].
+
+Acknowledgements
+----------------
+
+``diffpy.pdfgui`` is built and maintained with `scikit-package <https://scikit-package.github.io/scikit-package/>`_.

doc/source/api/diffpy.pdfgui.example_package.rst

@@ -0,0 +1,31 @@
+.. _example_package documentation:
+
+|title|
+=======
+
+.. |title| replace:: diffpy.pdfgui.example_package package
+
+.. automodule:: diffpy.pdfgui.example_package
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+|foo|
+-----
+
+.. |foo| replace:: diffpy.pdfgui.example_package.foo module
+
+.. automodule::  diffpy.pdfgui.example_package.foo
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+|bar|
+-----
+
+.. |bar| replace:: diffpy.pdfgui.example_package.bar module
+
+.. automodule:: diffpy.pdfgui.example_package.foo
+    :members:
+    :undoc-members:
+    :show-inheritance:

doc/source/conf.py

@@ -13,6 +13,12 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
+# Attempt to import the version dynamically from GitHub tag.
+try:
+    fullversion = version("diffpy.pdfgui")
+except Exception:
+    fullversion = "No version found. The correct version will appear in the released version."  # noqa: E501
+
 import sys
 import time
 from importlib.metadata import version
@@ -42,6 +48,7 @@
     "sphinx.ext.todo",
     "sphinx.ext.viewcode",
     "sphinx.ext.intersphinx",
+    "sphinx_copybutton",
     "sphinx_rtd_theme",
     "m2r",
 ]
@@ -64,6 +71,11 @@
 project = "diffpy.pdfgui"
 copyright = "%Y, The Trustees of Columbia University in the City of New York"
 
+# For sphinx_copybutton extension.
+# Do not copy "$" for shell commands in code-blocks.
+copybutton_prompt_text = r"^\$ "
+copybutton_prompt_is_regexp = True
+
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
@@ -123,6 +135,14 @@
 #
 html_theme = "sphinx_rtd_theme"
 
+html_context = {
+    "display_github": True,
+    "github_user": "diffpy",
+    "github_repo": "diffpy.pdfgui",
+    "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.
@@ -158,7 +178,7 @@
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
 # directly to the root of the documentation.
-html_extra_path = ["../manual"]
+html_extra_path = []
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
@@ -221,7 +241,13 @@
 # (source start file, target name, title,
 # author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    ("index", "diffpy.pdfgui.tex", "diffpy.pdfgui Documentation", ab_authors, "manual"),
+    (
+        "index",
+        "diffpy.pdfgui.tex",
+        "diffpy.pdfgui Documentation",
+        ab_authors,
+        "manual",
+    ),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -249,7 +275,15 @@
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [("index", "diffpy.pdfgui", "diffpy.pdfgui Documentation", ab_authors, 1)]
+man_pages = [
+    (
+        "index",
+        "diffpy.pdfgui",
+        "diffpy.pdfgui Documentation",
+        ab_authors,
+        1,
+    )
+]
 
 # If true, show URL addresses after external links.
 # man_show_urls = False

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,7 +4,7 @@
 
 .. |title| replace:: diffpy.pdfgui documentation
 
-diffpy.pdfgui - GUI for PDF simulation and structure refinement.
+``diffpy.pdfgui`` - Graphical user interface program for structure refinements to the atomic pair distribution function.
 
 | Software version |release|
 | Last updated |today|

doc/source/snippets/example-table.rst

@@ -0,0 +1,28 @@
+.. list-table:: 5 levels of reusing/sharing code
+   :widths: 5 15 40 40
+   :header-rows: 1
+
+   * - Level
+     - Name
+     - Scope
+     - How to setup
+   * - 1
+     - ``function``
+     - Reuse code in the single file.
+     - See Level 1 tutorial
+   * - 2
+     - ``module``
+     - Reuse code across files.
+     - See Level 2 tutorial
+   * - 3
+     - ``workspace``
+     - Reuse code across project folders.
+     - ``package create workspace``
+   * - 4
+     - ``system``
+     - Reuse code across any files in the computer.
+     - ``package create system``
+   * - 5
+     - ``public``
+     - Share code as publicly installable package.
+     - ``package create public``

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>