From 79fd7d05207fd15ab714f771dbec5a59df358168 Mon Sep 17 00:00:00 2001 From: Sam Andrello Date: Fri, 26 Jul 2024 13:21:02 -0400 Subject: [PATCH 1/3] modify README.rst to be like cookiecutter --- README.rst | 138 +++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 96 insertions(+), 42 deletions(-) diff --git a/README.rst b/README.rst index 6bc9518f..e4ddb15e 100644 --- a/README.rst +++ b/README.rst @@ -1,10 +1,39 @@ +|Icon| |title|_ +=============== -.. image:: https://codecov.io/gh/diffpy/diffpy.pdffit2/branch/master/graph/badge.svg - :target: https://codecov.io/gh/diffpy/diffpy.pdffit2 +.. |title| replace:: diffpy.pdffit2 +.. _title: https://diffpy.github.io/diffpy.pdffit2 +.. |Icon| image:: https://avatars.githubusercontent.com/diffpy + :target: https://diffpy.github.io/diffpy.pdffit2 + :height: 100px -PDFfit2 -======================================================================== +|PyPi| |Forge| |PythonVersion| |PR| + +|CI| |Codecov| |Black| |Tracking| + +.. |Black| image:: https://img.shields.io/badge/code_style-black-black + :target: https://github.com/psf/black + +.. |CI| image:: https://github.com/diffpy/diffpy.pdffit2/actions/workflows/main.yml/badge.svg + :target: https://github.com/diffpy/diffpy.pdffit2/actions/workflows/main.yml + +.. |Codecov| image:: https://codecov.io/gh/diffpy/diffpy.pdffit2/branch/main/graph/badge.svg + :target: https://codecov.io/gh/diffpy/diffpy.pdffit2 + +.. |Forge| image:: https://img.shields.io/conda/vn/conda-forge/diffpy.pdffit2 + :target: https://anaconda.org/conda-forge/diffpy.pdffit2 + +.. |PR| image:: https://img.shields.io/badge/PR-Welcome-29ab47ff + +.. |PyPi| image:: https://img.shields.io/pypi/v/diffpy.pdffit2 + :target: https://pypi.org/project/diffpy.pdffit2/ + +.. |PythonVersion| image:: https://img.shields.io/pypi/pyversions/diffpy.pdffit2 + :target: https://pypi.org/project/diffpy.pdffit2/ + +.. |Tracking| image:: https://img.shields.io/badge/issue_tracking-github-blue + :target: https://github.com/diffpy/diffpy.pdffit2/issues Real space structure refinement to atomic pair distribution function. @@ -29,11 +58,18 @@ To learn more about diffpy.pdffit2 library, see the examples directory included in this distribution or the API documentation at http://www.diffpy.org/doc/pdffit2. +Citation +-------- + +If you use diffpy.pdffit2 in a scientific publication, we would like you to cite this package as + + diffpy.pdffit2 Package, https://github.com/diffpy/diffpy.pdffit2 -REQUIREMENTS ------------------------------------------------------------------------- -diffpy.pdffit2 requires Python 3.7 or later or 2.7 and +Installation +------------ + +diffpy.pdffit2 requires Python 3.10 or later and the following external software: * ``setuptools`` - software distribution tools for Python @@ -43,50 +79,44 @@ the following external software: * ``diffpy.structure`` - simple storage and manipulation of atomic structures, https://github.com/diffpy/diffpy.structure -We recommend to use `Anaconda Python `_ -as it allows to install all software dependencies together with -PDFfit2. For other Python distributions it is necessary to -install the required software separately. As an example, on Ubuntu -Linux some of the required software can be installed using :: - - sudo apt-get install \ - python-setuptools python-dev libgsl0-dev build-essential +---- +The preferred method is to use `Miniconda Python +`_ +and install from the "conda-forge" channel of Conda packages. -INSTALLATION ------------------------------------------------------------------------- +To add "conda-forge" to the conda channels, run the following in a terminal. :: -The preferred method is to use Anaconda Python and install from the -"conda-forge" channel of Anaconda packages :: + conda config --add channels conda-forge - conda install -c conda-forge diffpy.pdffit2 +We want to install our packages in a suitable conda environment. +The following creates and activates a new environment named ``diffpy.pdffit2_env`` :: -If you don't use Anaconda or prefer to install from sources, make -sure the required software is in place and run :: + conda create -n diffpy.pdffit2_env python=3 + conda activate diffpy.pdffit2_env - python setup.py install +Then, to fully install ``diffpy.pdffit2`` in our active environment, run :: -By default the files get installed to standard system directories, -which may require the use of ``sudo`` for write permissions. If -administrator (root) access is not available, consult the output from -``python setup.py install --help`` for options to install as a regular -user to other locations. The installation integrity can be -verified by changing to the HOME directory and running :: + conda install diffpy.pdffit2 - python -m diffpy.pdffit2.tests.rundeps +Another option is to use ``pip`` to download and install the latest release from +`Python Package Index `_. +To install using ``pip`` into your ``diffpy.pdffit2_env`` environment, we will also have to install dependencies :: -Anaconda Python allows to later update PDFfit2 using :: + pip install -r https://raw.githubusercontent.com/diffpy/diffpy.pdffit2/main/requirements/run.txt - conda update diffpy.pdffit2 +and then install the package :: -With other Python distributions use the easy_install program to -upgraded to the latest version :: + pip install diffpy.pdffit2 - easy_install --upgrade diffpy.pdffit2 +If you prefer to install from sources, after installing the dependencies, obtain the source archive from +`GitHub `_. Once installed, ``cd`` into your ``diffpy.pdffit2`` directory +and run the following :: + pip install . -DEVELOPMENT ------------------------------------------------------------------------- +Support and Contribute +---------------------- PDFfit2 is not developed anymore and is only maintained due to its status of a sole computational engine for PDFgui. We don't expect any @@ -97,12 +127,36 @@ at https://github.com/diffpy/diffpy.pdffit2. For an actively developed codes for PDF simulations see the DiffPy-CMI framework at http://www.diffpy.org. +---- + +`Diffpy user group `_ is the discussion forum for general questions and discussions about the use of diffpy.pdffit2. Please join the diffpy.pdffit2 users community by joining the Google group. The diffpy.pdffit2 project welcomes your expertise and enthusiasm! + +If you see a bug or want to request a feature, please `report it as an issue `_ and/or `submit a fix as a PR `_. You can also post it to the `Diffpy user group `_. + +Feel free to fork the project and contribute. To install diffpy.pdffit2 +in a development mode, with its sources being directly used by Python +rather than copied to a package directory, use the following in the root +directory :: + + pip install -e . + +To ensure code quality and to prevent accidental commits into the default branch, please set up the use of our pre-commit +hooks. + +1. Install pre-commit in your working environment by running ``conda install pre-commit``. + +2. Initialize pre-commit (one time only) ``pre-commit install``. + +Thereafter your code will be linted by black and isort and checked against flake8 before you can commit. +If it fails by black or isort, just rerun and it should pass (black and isort will modify the files so should +pass after they are modified). If the flake8 test fails please see the error messages and fix them manually before +trying to commit again. -CONTACTS ------------------------------------------------------------------------- +Improvements and fixes are always appreciated. -For more information on diffpy.pdffit2 please visit the project web-page: +Before contributing, please read our `Code of Conduct `_. -http://www.diffpy.org/ +Contact +------- -or email Prof. Simon Billinge at sb2896@columbia.edu. +For more information on diffpy.pdffit2 please visit the project `web-page `_ or email Prof. Simon Billinge at sb2896@columbia.edu. From d59c6ec50fa4d2aa0c19236b65b9216e6213135e Mon Sep 17 00:00:00 2001 From: Sam Andrello Date: Fri, 26 Jul 2024 13:32:43 -0400 Subject: [PATCH 2/3] cite paper instead of repo --- README.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/README.rst b/README.rst index e4ddb15e..702131a4 100644 --- a/README.rst +++ b/README.rst @@ -61,10 +61,11 @@ http://www.diffpy.org/doc/pdffit2. Citation -------- -If you use diffpy.pdffit2 in a scientific publication, we would like you to cite this package as - - diffpy.pdffit2 Package, https://github.com/diffpy/diffpy.pdffit2 +If you use diffpy.pdffit2 in a scientific publication, we would like you to cite the following paper: + C\. L. Farrow, P. Juhás, 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://stacks.iop.org/0953-8984/19/335219), *J. Phys.: Condens. Matter*, 19, 335219 (2007) Installation ------------ From a70155143d60dc4f9923031427474fd0aaa3d2e8 Mon Sep 17 00:00:00 2001 From: Sam Andrello Date: Fri, 26 Jul 2024 13:35:18 -0400 Subject: [PATCH 3/3] fix citation in LICENSE.rst --- LICENSE.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/LICENSE.rst b/LICENSE.rst index 9618d51a..daeacb69 100644 --- a/LICENSE.rst +++ b/LICENSE.rst @@ -5,10 +5,9 @@ If you use this program to do productive 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. Bozin, - J. Bloch, Th. Proffen and S. J. L. Billinge, PDFfit2 and - PDFgui: computer programs for studying nanostructure in - crystals, J. Phys.: Condens. Matter 19, 335219 (2007) + C\. L. Farrow, P. Juhás, 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://stacks.iop.org/0953-8984/19/335219), *J. Phys.: Condens. Matter*, 19, 335219 (2007) Copyright 2006-2007, Board of Trustees of Michigan State University, Copyright 2008-2024, Board of Trustees of Columbia University in the