skpkg: migrate documentation

Author: ycexiao

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/api/diffpy.pdfgui.rst

@@ -1,7 +1,9 @@
 :tocdepth: -1
 
-diffpy.pdfgui package
-=====================
+|title|
+=======
+
+.. |title| replace:: diffpy.pdfgui package
 
 .. automodule:: diffpy.pdfgui
     :members:
@@ -12,28 +14,17 @@ Subpackages
 -----------
 
 .. toctree::
-    :titlesonly:
-
-    diffpy.pdfgui.icons
-    diffpy.pdfgui.gui
-    diffpy.pdfgui.applications
-    diffpy.pdfgui.control
+   diffpy.pdfgui.example_package
 
 Submodules
 ----------
 
-diffpy.pdfgui.utils module
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. automodule:: diffpy.pdfgui.utils
-    :members:
-    :undoc-members:
-    :show-inheritance:
+|module|
+--------
 
-diffpy.pdfgui.tui module
-^^^^^^^^^^^^^^^^^^^^^^^^
+.. |module| replace:: diffpy.pdfgui.example_submodule module
 
-.. automodule:: diffpy.pdfgui.tui
+.. automodule:: diffpy.pdfgui.example_submodule
     :members:
     :undoc-members:
     :show-inheritance:

doc/source/conf.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 #
-# diffpy.pdfgui documentation build configuration file, created by
+# diffpy.pdfgui 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,15 +18,21 @@
 from importlib.metadata import version
 from pathlib import Path
 
+# 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
+
 # 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()))
 
 # abbreviations
-ab_authors = "Billinge Group members and community contributors"
+ab_authors = "Simon J.L. Billinge group"
 
 # -- General configuration ------------------------------------------------
 
@@ -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.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 +177,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 +240,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 +274,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/img/scikit-package-logo-text.png

@@ -4,94 +4,49 @@
 
 .. |title| replace:: diffpy.pdfgui documentation
 
-diffpy.pdfgui - GUI for PDF simulation and structure refinement.
+``diffpy.pdfgui`` - Graphical user interface program for structure refinements to atomic pair distribution function.
 
 | Software version |release|
-| Last updated |today|
+| Last updated |today|.
 
-For users who do not have the expertise or necessity for command
-line analysis, PDFgui is a convenient and easy to use graphical front
-end for the PDFfit2 refinement program. It is capable of full-profile
-fitting of the atomic pair distribution function (PDF) derived from x-ray
-or neutron diffraction data and comes with built in graphical and structure
-visualization capabilities.
+===============
+Getting started
+===============
 
-PDFgui is a friendly interface to the PDFfit2 refinement engine, with many
-powerful extensions. To get started, please open the :ref:`manual`
-(:download:`pdf <pdfgui.pdf>`) from the help menu or follow the :ref:`tutorial`.
+Welcome to the ``diffpy.pdfgui`` documentation!
+
+To get started, please visit the :ref:`Getting started <getting-started>` page.
 
 =======
 Authors
 =======
 
-DiffPy was initiated as part of the Distributed Data Analysis of Neutron
-Scattering Experiments (DANSE) project, funded by the National Science
-Foundation under grant DMR-0520547. Any opinions, findings, and conclusions or
-recommendations expressed in this material are those of the author(s)
-and do not necessarily reflect the views of the NSF.
-
-The main contributors to this package were
-
-    Chris Farrow,
-    Jiwu Liu,
-    Pavol Juhas,
-    Dmitriy Bryndin
-
-Other current and former contributors of the DiffPy project include
-
-    Simon Billinge,
-    Chris Farrow,
-    Emil Bozin,
-    Wenduo Zhou,
-    Peng Tian
-
-The DiffPy team is part of the Billinge Group at Columbia University in New York,
-within the Department of Applied Physics and Applied Mathematics.
-
-For a detailed list of contributors see
+``diffpy.pdfgui`` is developed by Simon J.L. Billinge group. The maintainer for this project is Simon J.L. Billinge group. For a detailed list of contributors see
 https://github.com/diffpy/diffpy.pdfgui/graphs/contributors.
 
-=========
-Reference
-=========
-
-If you use this program for a scientific research that leads to publication,
-we ask that you acknowledge use of the program by citing the following paper
-in your publication:
-
-   C L Farrow, P Juhas, J W Liu, D Bryndin, E S Božin,
-   J Bloch, Th Proffen and S J L Billinge, `PDFfit2 and PDFgui:
-   computer programs for studying nanostructure in crystals <https://doi.org/10.1088/0953-8984/19/33/335219>`_,
-   J. Phys.: Condens. Matter 19 (2007) 335219.
-
 ============
 Installation
 ============
 
 See the `README <https://github.com/diffpy/diffpy.pdfgui#installation>`_
 file included with the distribution.
 
-========
-Tutorial
-========
-
-The tutorial for the package can be found here:
-
-.. toctree::
+================
+Acknowledgements
+================
 
-   tutorial
+``diffpy.pdfgui`` is built and maintained with `scikit-package <https://scikit-package.github.io/scikit-package/>`_.
 
 =================
 Table of contents
 =================
 .. toctree::
-   :titlesonly:
+   :maxdepth: 2
 
-   examples
-   extras
-   license
-   release
+   getting-started
    Package API <api/diffpy.pdfgui>
+   release
+   license
 
 =======
 Indices