From 95b49b6feb1c704a19f6c51ddf250adb4cbc059a Mon Sep 17 00:00:00 2001 From: stevenhua0320 Date: Tue, 21 Oct 2025 21:45:50 -0400 Subject: [PATCH 1/5] skpkg: migrate docs/source files --- doc/manual/source/index.rst | 62 --------- {doc/examples => docs}/KFe2As2-00838.tif | Bin .../examples => docs}/KFe2As2-00838_fit2d.chi | 0 .../KFe2As2-00838_twotheta.chi | 0 {doc/manual => docs}/Makefile | 27 +++- {doc/examples => docs}/config.cfg | 0 {doc/examples => docs}/fit2d.txt | 28 ++-- docs/make.bat | 36 +++++ docs/source/_static/.placeholder | 0 .../source/api/diffpy.confutils.rst | 0 {doc/manual => docs}/source/api/diffpy.rst | 0 .../source/api/diffpy.srxplanar.rst | 60 +++++--- {doc/manual => docs}/source/api/modules.rst | 0 {doc/manual => docs}/source/conf.py | 131 ++++++++++++------ docs/source/index.rst | 67 +++++++++ docs/source/license.rst | 38 +++++ docs/source/release.rst | 5 + 17 files changed, 310 insertions(+), 144 deletions(-) delete mode 100644 doc/manual/source/index.rst rename {doc/examples => docs}/KFe2As2-00838.tif (100%) rename {doc/examples => docs}/KFe2As2-00838_fit2d.chi (100%) rename {doc/examples => docs}/KFe2As2-00838_twotheta.chi (100%) rename {doc/manual => docs}/Makefile (83%) rename {doc/examples => docs}/config.cfg (100%) rename {doc/examples => docs}/fit2d.txt (98%) create mode 100644 docs/make.bat create mode 100644 docs/source/_static/.placeholder rename {doc/manual => docs}/source/api/diffpy.confutils.rst (100%) rename {doc/manual => docs}/source/api/diffpy.rst (100%) rename {doc/manual => docs}/source/api/diffpy.srxplanar.rst (52%) rename {doc/manual => docs}/source/api/modules.rst (100%) rename {doc/manual => docs}/source/conf.py (70%) create mode 100644 docs/source/index.rst create mode 100644 docs/source/license.rst create mode 100644 docs/source/release.rst diff --git a/doc/manual/source/index.rst b/doc/manual/source/index.rst deleted file mode 100644 index 7f17fc1..0000000 --- a/doc/manual/source/index.rst +++ /dev/null @@ -1,62 +0,0 @@ -.. diffpy.srxplanar documentation master file, created by - sphinx-quickstart on Mon Aug 19 16:59:08 2013. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -#################################################### -diffpy.srxplanar's documentation -#################################################### - -Software version |release|. - -Last updated |today|. - -diffpy.srxplanar package provides 2D diffraction image integration using -non splitting pixel algorithm. And it can estimate and propagate statistic -uncertainty of raw counts and integrated intensity. If you are using this -software. If you use this program to do productive scientific research that -leads to publication, we kindly ask that you acknowledge use of the program -by citing the following paper in your publication: - - Xiaohao Yang, Pavol Juhas, Simon J. L. Billinge, On the estimation of - statistical uncertainties on powder diffraction and small angle - scattering data from 2-D x-ray detectors, arXiv:1309.3614 - -=================== -Disclaimer -=================== - -.. literalinclude:: ../../../LICENSE.txt - -.. index:: authors - -================ -Acknowledgments -================ - -Developers ------------ - -diffpy.srxplanar is developed and maintained by - -.. literalinclude:: ../../../AUTHORS.txt - - -====================================== -Installation -====================================== - -See the `README.rst `_ -file included with the distribution. - -API and Indices -================== - -.. toctree:: - :maxdepth: 2 - - api/diffpy.rst - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/doc/examples/KFe2As2-00838.tif b/docs/KFe2As2-00838.tif similarity index 100% rename from doc/examples/KFe2As2-00838.tif rename to docs/KFe2As2-00838.tif diff --git a/doc/examples/KFe2As2-00838_fit2d.chi b/docs/KFe2As2-00838_fit2d.chi similarity index 100% rename from doc/examples/KFe2As2-00838_fit2d.chi rename to docs/KFe2As2-00838_fit2d.chi diff --git a/doc/examples/KFe2As2-00838_twotheta.chi b/docs/KFe2As2-00838_twotheta.chi similarity index 100% rename from doc/examples/KFe2As2-00838_twotheta.chi rename to docs/KFe2As2-00838_twotheta.chi diff --git a/doc/manual/Makefile b/docs/Makefile similarity index 83% rename from doc/manual/Makefile rename to docs/Makefile index 9d3be9d..85739d2 100644 --- a/doc/manual/Makefile +++ b/docs/Makefile @@ -6,6 +6,12 @@ SPHINXOPTS = SPHINXBUILD = sphinx-build PAPER = BUILDDIR = build +BASENAME = $(subst .,,$(subst $() $(),,diffpy.srxplanar)) + +# User-friendly check for sphinx-build +ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) +$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) +endif # Internal variables. PAPEROPT_a4 = -D latex_paper_size=a4 @@ -14,7 +20,7 @@ ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) sou # the i18n builder cannot share the environment and doctrees with the others I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext publish +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext help: @echo "Please use \`make ' where is one of" @@ -29,17 +35,20 @@ help: @echo " epub to make an epub" @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" @echo " text to make text files" @echo " man to make manual pages" @echo " texinfo to make Texinfo files" @echo " info to make Texinfo files and run them through makeinfo" @echo " gettext to make PO message catalogs" @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" @echo " linkcheck to check all external links for integrity" @echo " doctest to run all doctests embedded in the documentation (if enabled)" clean: - -rm -rf $(BUILDDIR)/* + rm -rf $(BUILDDIR)/* html: $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @@ -77,17 +86,17 @@ qthelp: @echo @echo "Build finished; now you can run "qcollectiongenerator" with the" \ ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Structure.qhcp" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/$(BASENAME).qhcp" @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Structure.qhc" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/$(BASENAME).qhc" devhelp: $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp @echo @echo "Build finished." @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/Structure" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Structure" + @echo "# mkdir -p $$HOME/.local/share/devhelp/$(BASENAME)" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/$(BASENAME)" @echo "# devhelp" epub: @@ -108,6 +117,12 @@ latexpdf: $(MAKE) -C $(BUILDDIR)/latex all-pdf @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + text: $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text @echo diff --git a/doc/examples/config.cfg b/docs/config.cfg similarity index 100% rename from doc/examples/config.cfg rename to docs/config.cfg diff --git a/doc/examples/fit2d.txt b/docs/fit2d.txt similarity index 98% rename from doc/examples/fit2d.txt rename to docs/fit2d.txt index dc38e1a..f56f3e3 100644 --- a/doc/examples/fit2d.txt +++ b/docs/fit2d.txt @@ -1,14 +1,14 @@ -INFO: Number of function calls = 7 -INFO: Sum of squares = 2.3219 -INFO: Number of rejected coordinates = 0 -INFO: Number of function calls = 7 -INFO: Sum of squares = 2.3219 -INFO: Refined Beam centre = 1299.430 1010.190 (pixels) -INFO: Refined Beam centre = 186.240 1.299 (mm) -INFO: Refined sample to detector distance = 369.579 mm -INFO: Refined wavelength = 0.1078 Angstroms - Energy (keV) = 115.0 -INFO: Refined tilt plane rotation angle = 49.715 degrees -INFO: Refined tilt angle = -1.480 degrees -INFO: ROT X = 0.068 ROT Y = -0.425 degrees -INFO: Stability indicator (proportional to D-spacing; Angstroms) = 0.46505 +INFO: Number of function calls = 7 +INFO: Sum of squares = 2.3219 +INFO: Number of rejected coordinates = 0 +INFO: Number of function calls = 7 +INFO: Sum of squares = 2.3219 +INFO: Refined Beam centre = 1299.430 1010.190 (pixels) +INFO: Refined Beam centre = 186.240 1.299 (mm) +INFO: Refined sample to detector distance = 369.579 mm +INFO: Refined wavelength = 0.1078 Angstroms + Energy (keV) = 115.0 +INFO: Refined tilt plane rotation angle = 49.715 degrees +INFO: Refined tilt angle = -1.480 degrees +INFO: ROT X = 0.068 ROT Y = -0.425 degrees +INFO: Stability indicator (proportional to D-spacing; Angstroms) = 0.46505 diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..2be8306 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,36 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build +set SPHINXPROJ=PackagingScientificPython + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% + +:end +popd diff --git a/docs/source/_static/.placeholder b/docs/source/_static/.placeholder new file mode 100644 index 0000000..e69de29 diff --git a/doc/manual/source/api/diffpy.confutils.rst b/docs/source/api/diffpy.confutils.rst similarity index 100% rename from doc/manual/source/api/diffpy.confutils.rst rename to docs/source/api/diffpy.confutils.rst diff --git a/doc/manual/source/api/diffpy.rst b/docs/source/api/diffpy.rst similarity index 100% rename from doc/manual/source/api/diffpy.rst rename to docs/source/api/diffpy.rst diff --git a/doc/manual/source/api/diffpy.srxplanar.rst b/docs/source/api/diffpy.srxplanar.rst similarity index 52% rename from doc/manual/source/api/diffpy.srxplanar.rst rename to docs/source/api/diffpy.srxplanar.rst index 8467e2c..a085477 100644 --- a/doc/manual/source/api/diffpy.srxplanar.rst +++ b/docs/source/api/diffpy.srxplanar.rst @@ -1,64 +1,88 @@ -srxplanar Package -================= +:tocdepth: -1 -:mod:`srxplanar` Package ------------------------- +|title| +======= + +.. |title| replace:: diffpy.srxplanar package .. automodule:: diffpy.srxplanar :members: :undoc-members: :show-inheritance: -:mod:`calculate` Module ------------------------ +Subpackages +----------- + +.. toctree:: + diffpy.srxplanar.example_package + +Submodules +---------- + +|module_1| +-------- + +.. |module_1| replace:: diffpy.srxplanar.calculate module .. automodule:: diffpy.srxplanar.calculate :members: :undoc-members: :show-inheritance: -:mod:`loadimage` Module ------------------------ +|module_2| +-------- + +.. |module_2| replace:: diffpy.srxplanar.loadimage module .. automodule:: diffpy.srxplanar.loadimage :members: :undoc-members: :show-inheritance: -:mod:`mask` Module ------------------- +|module_3| +-------- + +.. |module_3| replace:: diffpy.srxplanar.mask module .. automodule:: diffpy.srxplanar.mask :members: :undoc-members: :show-inheritance: -:mod:`saveresults` Module -------------------------- +|module_4| +-------- + +.. |module_4| replace:: diffpy.srxplanar.saveresults module .. automodule:: diffpy.srxplanar.saveresults :members: :undoc-members: :show-inheritance: -:mod:`srxplanar` Module ------------------------ +|module_5| +-------- + +.. |module_5| replace:: diffpy.srxplanar.srxplanar module .. automodule:: diffpy.srxplanar.srxplanar :members: :undoc-members: :show-inheritance: -:mod:`srxplanarconfig` Module ------------------------------ +|module_6| +-------- + +.. |module_6| replace:: diffpy.srxplanar.srxplanarconfig module .. automodule:: diffpy.srxplanar.srxplanarconfig :members: :undoc-members: :show-inheritance: -:mod:`version` Module ---------------------- +|module_7| +-------- + +.. |module_7| replace:: diffpy.srxplanar.version module .. automodule:: diffpy.srxplanar.version :members: diff --git a/doc/manual/source/api/modules.rst b/docs/source/api/modules.rst similarity index 100% rename from doc/manual/source/api/modules.rst rename to docs/source/api/modules.rst diff --git a/doc/manual/source/conf.py b/docs/source/conf.py similarity index 70% rename from doc/manual/source/conf.py rename to docs/source/conf.py index 514f189..fcb25aa 100644 --- a/doc/manual/source/conf.py +++ b/docs/source/conf.py @@ -1,11 +1,11 @@ #!/usr/bin/env python # -*- coding: utf-8 -*- # -# diffpy.Structure documentation build configuration file, created by -# sphinx-quickstart on Tue Oct 22 12:02:48 2013. +# diffpy.srxplanar 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 containing dir. +# This file is execfile()d with the current directory set to its +# containing dir. # # Note that not all possible configuration values are present in this # autogenerated file. @@ -13,41 +13,53 @@ # All configuration values have a default; values that are commented out # serve to show the default. -import os import sys import time +from importlib.metadata import version +from pathlib import Path -from setup import versiondata +# Attempt to import the version dynamically from GitHub tag. +try: + fullversion = version("diffpy.srxplanar") +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 os.path.abspath to make it absolute, like shown here. -# sys.path.insert(0, os.path.abspath('.')) -sys.path.insert(0, os.path.abspath("../../..")) +# 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 = "Xiaohao Yang, Simon J.L. Billinge group" +ab_authors = "Simon Billinge, Billinge Group members" -# -- General configuration ---------------------------------------------------- +# -- General configuration ------------------------------------------------ # If your documentation needs a minimal Sphinx version, state it here. # needs_sphinx = '1.0' -# Add any Sphinx extension module names here, as strings. -# They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. extensions = [ "sphinx.ext.autodoc", - "sphinx.ext.doctest", - "sphinx.ext.coverage", - "sphinx.ext.pngmath", + "sphinx.ext.napoleon", + "sphinx.ext.todo", + "sphinx.ext.viewcode", + "sphinx.ext.intersphinx", + "sphinx_rtd_theme", + "sphinx_copybutton", + "m2r", ] # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] -# The suffix of source filenames. -source_suffix = ".rst" +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +source_suffix = [".rst", ".md"] # The encoding of source files. # source_encoding = 'utf-8-sig' @@ -57,15 +69,14 @@ # General information about the project. project = "diffpy.srxplanar" -copyright = "%Y, Columbia University" +copyright = "%Y, The Trustees of Columbia University in the City of New York" # 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. -fullversion = versiondata.get("DEFAULT", "version") # The short X.Y version. -version = ".".join(fullversion.split(".")[:2]) +version = "".join(fullversion.split(".post")[:1]) # The full version, including alpha/beta/rc tags. release = fullversion @@ -76,20 +87,24 @@ # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: # today = '' -today_seconds = versiondata.getint("DEFAULT", "timestamp") -today = time.strftime("%B %d, %Y", time.localtime(today_seconds)) +today = time.strftime("%B %d, %Y", time.localtime()) year = today.split()[-1] # Else, today_fmt is used as the format for a strftime call. # today_fmt = '%B %d, %Y' # 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 = [] +exclude_patterns = ["build"] -# The reST default role (used for this markup: `text`) -# to use for all documents. +# The reST default role (used for this markup: `text`) to use for all +# documents. # default_role = None # If true, '()' will be appended to :func: etc. cross-reference text. @@ -112,17 +127,28 @@ # Display all warnings for missing links. nitpicky = True -# -- Options for HTML output -------------------------------------------------- +# -- Options for HTML output ---------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = "default" +# +html_theme = "sphinx_rtd_theme" + +html_context = { + "display_github": True, + "github_user": "diffpy", + "github_repo": "diffpy.srxplanar", + "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. -# html_theme_options = {} -html_theme_options = {"collapsiblesidebar": "true"} +# +html_theme_options = { + "navigation_with_keys": "true", +} # Add any paths that contain custom themes here, relative to this directory. # html_theme_path = [] @@ -146,7 +172,12 @@ # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ["_static"] +# html_static_path = ['_static'] + +# 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 = [] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. @@ -190,10 +221,11 @@ # html_file_suffix = None # Output file base name for HTML help builder. -htmlhelp_basename = "Structuredoc" +basename = "diffpy.srxplanar".replace(" ", "").replace(".", "") +htmlhelp_basename = basename + "doc" -# -- Options for LaTeX output ------------------------------------------------- +# -- Options for LaTeX output --------------------------------------------- latex_elements = { # The paper size ('letterpaper' or 'a4paper'). @@ -205,13 +237,13 @@ } # Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, -# documentclass [howto/manual]). +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). latex_documents = [ ( "index", - "srxplanar_manual.tex", - "srxplanar Documentation", + "diffpy.srxplanar.tex", + "diffpy.srxplanar Documentation", ab_authors, "manual", ), @@ -238,17 +270,25 @@ # latex_domain_indices = True -# -- Options for manual page output ------------------------------------------- +# -- Options for manual page output --------------------------------------- # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). -man_pages = [("index", "srxplanar", "srxplanar Documentation", ab_authors, 1)] +man_pages = [ + ( + "index", + "diffpy.srxplanar", + "diffpy.srxplanar Documentation", + ab_authors, + 1, + ) +] # If true, show URL addresses after external links. # man_show_urls = False -# -- Options for Texinfo output ----------------------------------------------- +# -- Options for Texinfo output ------------------------------------------- # Grouping the document tree into Texinfo files. List of tuples # (source start file, target name, title, author, @@ -256,10 +296,10 @@ texinfo_documents = [ ( "index", - "srxplanar", - "srxplanar Documentation", + "diffpy.srxplanar", + "diffpy.srxplanar Documentation", ab_authors, - "srxplanar", + "diffpy.srxplanar", "One line description of project.", "Miscellaneous", ), @@ -274,6 +314,9 @@ # How to display URL addresses: 'footnote', 'no', or 'inline'. # texinfo_show_urls = 'footnote' +# If true, do not generate a @detailmenu in the "Top" node's menu. +# texinfo_no_detailmenu = False + # Example configuration for intersphinx: refer to the Python standard library. # intersphinx_mapping = {'http://docs.python.org/': None} diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..09ee7ac --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,67 @@ +####### +|title| +####### + +.. |title| replace:: diffpy.srxplanar documentation + +``diffpy.srxplanar`` - Distance Printer, calculate the inter atomic distances. Part of xPDFsuite + +| Software version |release| +| Last updated |today|. + +=============== +Getting started +=============== + +Welcome to the ``diffpy.srxplanar`` documentation! + +To get started, please visit the :ref:`Getting started ` page. + +======= +Authors +======= + +``diffpy.srxplanar`` is developed by Simon Billinge, Billinge Group members. The maintainer for this project is Simon Billinge. For a detailed list of contributors see +https://github.com/diffpy/diffpy.srxplanar/graphs/contributors. + +============ +Installation +============ + +See the `README `_ +file included with the distribution. + +================ +Acknowledgements +================ + +``diffpy.srxplanar`` is built and maintained with `scikit-package `_. + +diffpy.srxplanar package provides 2D diffraction image integration using +non splitting pixel algorithm. And it can estimate and propagate statistic +uncertainty of raw counts and integrated intensity. If you are using this +software. If you use this program to do productive scientific research that +leads to publication, we kindly ask that you acknowledge use of the program +by citing the following paper in your publication: + + Xiaohao Yang, Pavol Juhas, Simon J. L. Billinge, On the estimation of + statistical uncertainties on powder diffraction and small angle + scattering data from 2-D x-ray detectors, arXiv:1309.3614 + +================= +Table of contents +================= +.. toctree:: + :maxdepth: 2 + + getting-started + Package API + release + license + +======= +Indices +======= + +* :ref:`genindex` +* :ref:`search` diff --git a/docs/source/license.rst b/docs/source/license.rst new file mode 100644 index 0000000..5e751f7 --- /dev/null +++ b/docs/source/license.rst @@ -0,0 +1,38 @@ +:tocdepth: -1 + +.. index:: license + +License +####### + +OPEN SOURCE LICENSE AGREEMENT +============================= +BSD 3-Clause License + +Copyright (c) 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 +modification, are permitted provided that the following conditions are met: + +1. Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. + +2. Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + +3. Neither the name of the copyright holder nor the names of its + contributors may be used to endorse or promote products derived from + this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/docs/source/release.rst b/docs/source/release.rst new file mode 100644 index 0000000..27cd0cc --- /dev/null +++ b/docs/source/release.rst @@ -0,0 +1,5 @@ +:tocdepth: -1 + +.. index:: release notes + +.. include:: ../../CHANGELOG.rst From dd2e54355561c427db8cb5dd28b54ad772d8b810 Mon Sep 17 00:00:00 2001 From: stevenhua0320 Date: Wed, 22 Oct 2025 10:43:09 -0400 Subject: [PATCH 2/5] skpkg: change documentation author, change license coverage --- docs/{ => examples}/KFe2As2-00838.tif | Bin docs/{ => examples}/KFe2As2-00838_fit2d.chi | 0 .../{ => examples}/KFe2As2-00838_twotheta.chi | 0 docs/{ => examples}/config.cfg | 0 docs/{ => examples}/fit2d.txt | 0 docs/source/conf.py | 2 +- docs/source/index.rst | 24 +----------------- docs/source/license.rst | 2 +- 8 files changed, 3 insertions(+), 25 deletions(-) rename docs/{ => examples}/KFe2As2-00838.tif (100%) rename docs/{ => examples}/KFe2As2-00838_fit2d.chi (100%) rename docs/{ => examples}/KFe2As2-00838_twotheta.chi (100%) rename docs/{ => examples}/config.cfg (100%) rename docs/{ => examples}/fit2d.txt (100%) diff --git a/docs/KFe2As2-00838.tif b/docs/examples/KFe2As2-00838.tif similarity index 100% rename from docs/KFe2As2-00838.tif rename to docs/examples/KFe2As2-00838.tif diff --git a/docs/KFe2As2-00838_fit2d.chi b/docs/examples/KFe2As2-00838_fit2d.chi similarity index 100% rename from docs/KFe2As2-00838_fit2d.chi rename to docs/examples/KFe2As2-00838_fit2d.chi diff --git a/docs/KFe2As2-00838_twotheta.chi b/docs/examples/KFe2As2-00838_twotheta.chi similarity index 100% rename from docs/KFe2As2-00838_twotheta.chi rename to docs/examples/KFe2As2-00838_twotheta.chi diff --git a/docs/config.cfg b/docs/examples/config.cfg similarity index 100% rename from docs/config.cfg rename to docs/examples/config.cfg diff --git a/docs/fit2d.txt b/docs/examples/fit2d.txt similarity index 100% rename from docs/fit2d.txt rename to docs/examples/fit2d.txt diff --git a/docs/source/conf.py b/docs/source/conf.py index fcb25aa..b86e8e3 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -32,7 +32,7 @@ sys.path.insert(0, str(Path("../../src").resolve())) # abbreviations -ab_authors = "Simon Billinge, Billinge Group members" +ab_authors = "Xiaohao Yang and Billinge Group members" # -- General configuration ------------------------------------------------ diff --git a/docs/source/index.rst b/docs/source/index.rst index 09ee7ac..112e858 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -4,24 +4,14 @@ .. |title| replace:: diffpy.srxplanar documentation -``diffpy.srxplanar`` - Distance Printer, calculate the inter atomic distances. Part of xPDFsuite - | Software version |release| | Last updated |today|. -=============== -Getting started -=============== - -Welcome to the ``diffpy.srxplanar`` documentation! - -To get started, please visit the :ref:`Getting started ` page. - ======= Authors ======= -``diffpy.srxplanar`` is developed by Simon Billinge, Billinge Group members. The maintainer for this project is Simon Billinge. For a detailed list of contributors see +``diffpy.srxplanar`` is developed by Xiaohao Yang and Billinge Group members. The maintainer for this project is Simon Billinge. For a detailed list of contributors see https://github.com/diffpy/diffpy.srxplanar/graphs/contributors. ============ @@ -37,24 +27,12 @@ Acknowledgements ``diffpy.srxplanar`` is built and maintained with `scikit-package `_. -diffpy.srxplanar package provides 2D diffraction image integration using -non splitting pixel algorithm. And it can estimate and propagate statistic -uncertainty of raw counts and integrated intensity. If you are using this -software. If you use this program to do productive scientific research that -leads to publication, we kindly ask that you acknowledge use of the program -by citing the following paper in your publication: - - Xiaohao Yang, Pavol Juhas, Simon J. L. Billinge, On the estimation of - statistical uncertainties on powder diffraction and small angle - scattering data from 2-D x-ray detectors, arXiv:1309.3614 - ================= Table of contents ================= .. toctree:: :maxdepth: 2 - getting-started Package API release license diff --git a/docs/source/license.rst b/docs/source/license.rst index 5e751f7..4b57678 100644 --- a/docs/source/license.rst +++ b/docs/source/license.rst @@ -9,7 +9,7 @@ OPEN SOURCE LICENSE AGREEMENT ============================= BSD 3-Clause License -Copyright (c) 2025, The Trustees of Columbia University in the City of New York. +Copyright (c) 2008-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 From de59d9299fc8942b7ed6f0a86e83198bed605648 Mon Sep 17 00:00:00 2001 From: stevenhua0320 Date: Wed, 22 Oct 2025 11:59:12 -0400 Subject: [PATCH 3/5] style: build html doc --- docs/source/api/diffpy.confutils.rst | 8 ++++---- docs/source/api/diffpy.srxplanar.rst | 22 ++++++++-------------- docs/source/index.rst | 3 ++- src/diffpy/confutils/version.py | 19 ++++++++----------- src/diffpy/srxplanar/srxplanar.py | 1 + 5 files changed, 23 insertions(+), 30 deletions(-) diff --git a/docs/source/api/diffpy.confutils.rst b/docs/source/api/diffpy.confutils.rst index ae7078e..a5aef90 100644 --- a/docs/source/api/diffpy.confutils.rst +++ b/docs/source/api/diffpy.confutils.rst @@ -1,7 +1,7 @@ confutils Package ================= -:mod:`confutils` Package +:mod:`diffpy.confutils` Package ------------------------ .. automodule:: diffpy.confutils @@ -9,7 +9,7 @@ confutils Package :undoc-members: :show-inheritance: -:mod:`config` Module +:mod:`diffpy.confutils.config` Module -------------------- .. automodule:: diffpy.confutils.config @@ -17,7 +17,7 @@ confutils Package :undoc-members: :show-inheritance: -:mod:`tools` Module +:mod:`diffpy.confutils.tools` Module ------------------- .. automodule:: diffpy.confutils.tools @@ -25,7 +25,7 @@ confutils Package :undoc-members: :show-inheritance: -:mod:`version` Module +:mod:`diffpy.confutils.version` Module --------------------- .. automodule:: diffpy.confutils.version diff --git a/docs/source/api/diffpy.srxplanar.rst b/docs/source/api/diffpy.srxplanar.rst index a085477..f7aedd7 100644 --- a/docs/source/api/diffpy.srxplanar.rst +++ b/docs/source/api/diffpy.srxplanar.rst @@ -10,17 +10,11 @@ :undoc-members: :show-inheritance: -Subpackages ------------ - -.. toctree:: - diffpy.srxplanar.example_package - Submodules ----------- +--------------------- |module_1| --------- +---------- .. |module_1| replace:: diffpy.srxplanar.calculate module @@ -30,7 +24,7 @@ Submodules :show-inheritance: |module_2| --------- +---------- .. |module_2| replace:: diffpy.srxplanar.loadimage module @@ -40,7 +34,7 @@ Submodules :show-inheritance: |module_3| --------- +---------- .. |module_3| replace:: diffpy.srxplanar.mask module @@ -50,7 +44,7 @@ Submodules :show-inheritance: |module_4| --------- +---------- .. |module_4| replace:: diffpy.srxplanar.saveresults module @@ -60,7 +54,7 @@ Submodules :show-inheritance: |module_5| --------- +---------- .. |module_5| replace:: diffpy.srxplanar.srxplanar module @@ -70,7 +64,7 @@ Submodules :show-inheritance: |module_6| --------- +---------- .. |module_6| replace:: diffpy.srxplanar.srxplanarconfig module @@ -80,7 +74,7 @@ Submodules :show-inheritance: |module_7| --------- +---------- .. |module_7| replace:: diffpy.srxplanar.version module diff --git a/docs/source/index.rst b/docs/source/index.rst index 112e858..6041b64 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -34,7 +34,8 @@ Table of contents :maxdepth: 2 Package API - release + Modules + Release notes license ======= diff --git a/src/diffpy/confutils/version.py b/src/diffpy/confutils/version.py index 7aa6b57..baedec1 100644 --- a/src/diffpy/confutils/version.py +++ b/src/diffpy/confutils/version.py @@ -14,18 +14,15 @@ ############################################################################## """Definition of __version__, __date__, __gitsha__.""" -from configparser import SafeConfigParser +# We do not use the other three variables, but can be added back if needed. +# __all__ = ["__date__", "__git_commit__", "__timestamp__", "__version__"] -from pkg_resources import resource_stream +# obtain version information +from importlib.metadata import PackageNotFoundError, version -# obtain version information from the version.cfg file -cp = SafeConfigParser() -cp.readfp(resource_stream(__name__, "version.cfg")) - -__version__ = cp.get("DEFAULT", "version") -__date__ = cp.get("DEFAULT", "date") -__gitsha__ = cp.get("DEFAULT", "commit") - -del cp +try: + __version__ = version("diffpy.srxplanar") +except PackageNotFoundError: + __version__ = "unknown" # End of file diff --git a/src/diffpy/srxplanar/srxplanar.py b/src/diffpy/srxplanar/srxplanar.py index 8dffa68..8e6971e 100644 --- a/src/diffpy/srxplanar/srxplanar.py +++ b/src/diffpy/srxplanar/srxplanar.py @@ -208,6 +208,7 @@ def integrate( in [tth or q, intensity, (uncertainty)]. rv['filename'] is the name of file to save to disk """ + rv = {} self.pic = self._getPic(image, flip, correction) From a7e787540bf386da59c35989fc61a5fd910795aa Mon Sep 17 00:00:00 2001 From: stevenhua0320 Date: Wed, 22 Oct 2025 14:35:17 -0400 Subject: [PATCH 4/5] chore: add description to the srxplanar in index.rst --- docs/source/index.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/source/index.rst b/docs/source/index.rst index 6041b64..2933b6d 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -7,6 +7,17 @@ | Software version |release| | Last updated |today|. +diffpy.srxplanar package provides 2D diffraction image integration using +non splitting pixel algorithm. And it can estimate and propagate statistic +uncertainty of raw counts and integrated intensity. If you are using this +software. If you use this program to do productive scientific research that +leads to publication, we kindly ask that you acknowledge use of the program +by citing the following paper in your publication: + + Xiaohao Yang, Pavol Juhas, Simon J. L. Billinge, On the estimation of + statistical uncertainties on powder diffraction and small angle + scattering data from 2-D x-ray detectors, arXiv:1309.3614 + ======= Authors ======= From 3a9ec205084dd717d0b08cc013b73c65c66c9f30 Mon Sep 17 00:00:00 2001 From: stevenhua0320 Date: Wed, 22 Oct 2025 21:21:57 -0400 Subject: [PATCH 5/5] style: move data into data folder and few more style change in build doc --- .../{ => data}/KFe2As2-00838_fit2d.chi | 0 .../{ => data}/KFe2As2-00838_twotheta.chi | 0 docs/source/api/diffpy.confutils.rst | 8 +++---- src/diffpy/confutils/config.py | 21 ++++++++++--------- 4 files changed, 15 insertions(+), 14 deletions(-) rename docs/examples/{ => data}/KFe2As2-00838_fit2d.chi (100%) rename docs/examples/{ => data}/KFe2As2-00838_twotheta.chi (100%) diff --git a/docs/examples/KFe2As2-00838_fit2d.chi b/docs/examples/data/KFe2As2-00838_fit2d.chi similarity index 100% rename from docs/examples/KFe2As2-00838_fit2d.chi rename to docs/examples/data/KFe2As2-00838_fit2d.chi diff --git a/docs/examples/KFe2As2-00838_twotheta.chi b/docs/examples/data/KFe2As2-00838_twotheta.chi similarity index 100% rename from docs/examples/KFe2As2-00838_twotheta.chi rename to docs/examples/data/KFe2As2-00838_twotheta.chi diff --git a/docs/source/api/diffpy.confutils.rst b/docs/source/api/diffpy.confutils.rst index a5aef90..ab7ad9d 100644 --- a/docs/source/api/diffpy.confutils.rst +++ b/docs/source/api/diffpy.confutils.rst @@ -2,7 +2,7 @@ confutils Package ================= :mod:`diffpy.confutils` Package ------------------------- +------------------------------- .. automodule:: diffpy.confutils :members: @@ -10,7 +10,7 @@ confutils Package :show-inheritance: :mod:`diffpy.confutils.config` Module --------------------- +------------------------------------- .. automodule:: diffpy.confutils.config :members: @@ -18,7 +18,7 @@ confutils Package :show-inheritance: :mod:`diffpy.confutils.tools` Module -------------------- +------------------------------------ .. automodule:: diffpy.confutils.tools :members: @@ -26,7 +26,7 @@ confutils Package :show-inheritance: :mod:`diffpy.confutils.version` Module ---------------------- +-------------------------------------- .. automodule:: diffpy.confutils.version :members: diff --git a/src/diffpy/confutils/config.py b/src/diffpy/confutils/config.py index f3140a0..e13728a 100644 --- a/src/diffpy/confutils/config.py +++ b/src/diffpy/confutils/config.py @@ -582,21 +582,22 @@ def parseConfigFile(self, filename): return def updateConfig(self, filename=None, args=None, **kwargs): - """Update config according to config file, args(from sys.argv) - or **kwargs. + """Update config according to a config file, args (from + ``sys.argv``), or ``**kwargs``. - 1. call self._preUpdateConfig() - 2. process file/args/kwargs passed to this method, - 3. read a configfile if specified in args or kwargs - 4. call self._postUpdateConfig() - 5. write config file if specified in args/kwargs + Steps: + 1. call ``self._preUpdateConfig()`` + 2. process file/args/kwargs passed to this method + 3. read a config file if specified in ``args`` or ``kwargs`` + 4. call ``self._postUpdateConfig()`` + 5. write config file if specified in ``args``/``kwargs`` :param filename: str, file name of the config file - :param args: list of str, args passed from cmd, - :param kwargs: dict, optional kwargs - + :param args: list of str, args passed from cmd + :param kwargs: dict, optional keyword arguments :return: True if anything updated, False if nothing updated """ + # call self._preUpdateConfig self._preUpdateConfig(**kwargs)