Merge pull request #360 from MikhailRyazanov/offline

Tweaks for documentation and PyPI

.travis.yml

@@ -1,24 +1,18 @@
 language: python
-sudo: false
+os: linux
+env: DEPS="numpy scipy cython"
 jobs:
   include:
-    - os: linux
-      dist: jammy
+    - dist: jammy
+      python: 3.11
+    - dist: jammy
       python: 3.10
-      env: DEPS="numpy scipy cython"
-    - os: linux
-      python: 3.9
-      env: TOXENV=py39, DEPS="numpy scipy cython"
-    - os: linux
-      python: 3.8
-      env: TOXENV=py38, DEPS="numpy scipy cython"
-    - os: linux
-      python: 2.7
-      env: TOXENV=py27, DEPS="numpy scipy cython"
+    - python: 3.9
+    - python: 3.8
+    - python: 2.7
     - os: osx
       language: generic
       osx_image: xcode10.1
-      env: TOXENV=py39, DEPS="numpy scipy cython"
     # - os: windows
     #   language: generic
     #   env: TOXENV=py39, DEPS="numpy scipy cython"    
@@ -27,17 +21,20 @@ install:
   # python >=3.7 has built-in dataclasses,
   # and the external package preinstalled on Travis breaks SciPy
   - pip uninstall -y dataclasses
-  - "pip install ${DEPS}"
+  - pip install ${DEPS}
   - pip install --upgrade coveralls pytest pytest-cov
   - pip install . -v
 script:
   - cd /tmp; pytest -v --cov=abel --pyargs abel
+# give RTD enough time to build the docs before strating the PyPI deployment
+before_deploy: sleep 5m
 deploy:
   provider: pypi
-  user: DanHickstein
+  username: DanHickstein
   password:
     secure: RlJ41NowzFZ57pzbCQNTnm2OY5tSoCocbassn03GEzWrUqDnVG/jtvqWxf5bKdJ5T1WrFmjeI6/GWGx9Xk5HXAfWQLJjtmtrN/SYerBtdUAEyyV0s//o/Wd2qEB3tj8FCtUAx+mf5Q9ck3mRCFuYqK9rApXXxeUOqCE3R6pnEf/Ubpg7NYqMphziZA65qClqJNl1RFxBRD8mVoik99IrLitka6UnctFMBMWhchuGP80FTG5kyl6sIvVn1cwQISSF3Yr+IVqiKQGL1syRnef4FzOhn5sY4tZwR50cEF1CdAAZQU5GqiFwMKTjmocT/YIMVViJm6/SukJUzPeZNC7YuQBb9ZGroF257PgYyrnGkEK6qs3i3qexRI2c2uLmq19H0FbBtNo1ZHYUF6kzmga+7dW9brzd7zLU2em+nqN7w09JO1Z9gFfHIC5XD276bkwtIK5qT0r7SjNY/HdO/HYaSCLI+FR4R/XpTzC+vWIkhpdv3WZ5IpdIFn9f1SW3Uq4hyro0wlojb26TUyidSIzHDYgPepxLVy5YPuT8Css0kqMh5j9uZeTCqMkyeeSrTBOF64NO6w7RH5cLTYGXMixMNudzHY8yZfH9NaynG+dRwwyy7okFg5D8qKT4zMJfn3yvzg1DAENqz2/cNL38epDEXRruTR99qGnN+xMG2WE/WRs=
+  distributions: sdist bdist_wheel
+  skip_existing: true
   on:
     tags: true
-    distributions: sdist bdist_wheel
     repo: PyAbel/PyAbel

CONTRIBUTING.rst

@@ -4,19 +4,52 @@ Contributing to PyAbel
 
 PyAbel is an open-source project, and we welcome improvements! Please let us know about any issues with the software, even if's just a typo. The easiest way to get started is to open a `new issue <https://github.com/PyAbel/PyAbel/issues>`__.
 
-If you would like to make a Pull Request, the following information may be useful.
+If you would like to make a `pull request <https://github.com/PyAbel/PyAbel/pulls>`__, the following information may be useful.
 
 
-Change Log
+Rebasing
+--------
+
+If possible, before submitting your pull request please rebase your fork on the last master on PyAbel. This could be done `as explained in this post <https://stackoverflow.com/questions/7244321/how-do-i-update-or-sync-a-forked-repository-on-github>`__::
+
+    # Add the remote, call it "upstream" (only the fist time)
+    git remote add upstream https://github.com/PyAbel/PyAbel.git
+
+    # Fetch all the branches of that remote into remote-tracking branches,
+    # such as upstream/master:
+
+    git fetch upstream
+
+    # Make sure that you're on your master branch
+    # or any other branch your are working on
+
+    git checkout master  # or your other working branch
+
+    # Rewrite your master branch so that any commits of yours that
+    # aren't already in upstream/master are replayed on top of that
+    # other branch:
+
+    git rebase upstream/master
+
+    # push the changes to your fork
+
+    git push -f
+
+See `this wiki <https://github.com/openedx/edx-platform/wiki/How-to-Rebase-a-Pull-Request>`__ for more information.
+
+
+Code style
 ----------
 
-If the change is significant (more than just a typo-fix), please leave a short note about the change in `CHANGELOG.rst <https://github.com/PyAbel/PyAbel/blob/master/CHANGELOG.rst>`__
+We hope that the PyAbel code will be understandable, hackable, and maintainable for many years to come. So, please use good coding style, include plenty of comments, use docstrings for functions, and pick informative variable names.
+
+PyAbel attempts to follow `PEP8 <https://peps.python.org/pep-0008/>`__ style whenever possible, since the PEP8 recommendations typically produces code that is easier to read. You can check your code using `pycodestyle <https://pypi.org/project/pycodestyle/>`__, which can be called from the command line or incorporated right into most text editors. Also, PyAbel is using automated pycodestyle checking of all pull requests using `pep8speaks <https://github.com/apps/pep8-speaks>`__. However, `producing readable code <https://peps.python.org/pep-0008/#a-foolish-consistency-is-the-hobgoblin-of-little-minds>`__ is the primary goal, so please go ahead and break the rules of PEP8 when doing so improves readability. For example, if a section of your code is easier to read with lines slightly longer than 79 characters, then use the longer lines.
 
 
 Unit tests
 ----------
 
-Before submitting at Pull Request, be sure to run the unit tests. The test suite can be run from within the PyAbel package with ::
+Before submitting a pull request, be sure to run the unit tests. The test suite can be run from within the PyAbel package with ::
     
     pytest
     
@@ -64,43 +97,10 @@ which should launch a browser window displaying the docs. When you save a change
 Alternatively, `restview <https://pypi.org/project/restview/>`__ is a nice way to preview the ``.rst`` files.
 
 
-Code Style
-----------
-
-We hope that the PyAbel code will be understandable, hackable, and maintainable for many years to come. So, please use good coding style, include plenty of comments, use docstrings for functions, and pick informative variable names.
-
-PyAbel attempts to follow `PEP8 <https://peps.python.org/pep-0008/>`__ style whenever possible, since the PEP8 recommendations typically produces code that is easier to read. You can check your code using `pycodestyle <https://pypi.org/project/pycodestyle/>`__, which can be called from the command line or incorporated right into most text editors. Also, PyAbel is using automated pycodestyle checking of all Pull Requests using `pep8speaks <https://github.com/apps/pep8-speaks>`__. However, `producing readable code <https://peps.python.org/pep-0008/#a-foolish-consistency-is-the-hobgoblin-of-little-minds>`__ is the primary goal, so please go ahead and break the rules of PEP8 when doing so improves readability. For example, if a section of your code is easier to read with lines slightly longer than 79 characters, then use the longer lines.
-
-
-Before merging
---------------
-
-If possible, before merging your pull request please rebase your fork on the last master on PyAbel. This could be done `as explained in this post <https://stackoverflow.com/questions/7244321/how-do-i-update-or-sync-a-forked-repository-on-github>`__::
-
-    # Add the remote, call it "upstream" (only the fist time)
-    git remote add upstream https://github.com/PyAbel/PyAbel.git
-
-    # Fetch all the branches of that remote into remote-tracking branches,
-    # such as upstream/master:
-
-    git fetch upstream
-
-    # Make sure that you're on your master branch
-    # or any other branch your are working on
-
-    git checkout master  # or your other working branch
-
-    # Rewrite your master branch so that any commits of yours that
-    # aren't already in upstream/master are replayed on top of that
-    # other branch:
-
-    git rebase upstream/master
-
-    # push the changes to your fork
-
-    git push -f
+Changelog
+---------
 
-See `this wiki <https://github.com/openedx/edx-platform/wiki/How-to-Rebase-a-Pull-Request>`__ for more information.
+If the change is significant (more than just a typo-fix), please leave a short note about the change in `CHANGELOG.rst <https://github.com/PyAbel/PyAbel/blob/master/CHANGELOG.rst>`__, at the bottom of the "Unreleased" section (the PR number can be added later).
 
 
 Adding a new forward or inverse Abel implementation
@@ -116,8 +116,8 @@ Naming conventions
 
 The implementation named ``<implementation>``, located under ``abel/<implementation>.py``, should use the following naming system for top-level functions:
 
-- ``<implemenation>_transform`` :  core transform (when defined)
-- ``_bs_<implementation>`` :  function that generates  the basis sets (if necessary)
+- ``<implemenation>_transform`` — core transform (when defined)
+- ``_bs_<implementation>`` — function that generates  the basis sets (if necessary)
 
 
 Unit tests
@@ -136,26 +136,47 @@ Unit tests for a given implementation are located under ``abel/tests/test_<imple
 - ``test_<implementation>_zeros``
 - ``test_<implementation>_gaussian``
 
-See ``abel/tests/test_basex.py`` for a concrete example.
+.. |test_basex.py| replace:: ``abel/tests/test_basex.py``
+.. _test_basex.py: https://github.com/PyAbel/PyAbel/blob/master/abel/tests/test_basex.py
+
+See |test_basex.py|_ for a concrete example.
 
 
 Dependencies
 ------------
 
-The current list of dependencies can be found in `setup.py <https://github.com/PyAbel/PyAbel/blob/master/setup.py>`__. Please refrain from adding new dependencies, unless it cannot be avoided.
+.. |setup.py| replace:: ``setup.py``
+.. _setup.py: https://github.com/PyAbel/PyAbel/blob/master/setup.py
 
+The current list of dependencies can be found in |setup.py|_. Please refrain from adding new dependencies, unless it cannot be avoided.
 
 
-Releasing on PyPi
------------------
+Citations
+---------
 
-PyAbel should be automatically released on PyPi (see `PR #161 <https://github.com/PyAbel/PyAbel/pull/161>`__) whenever a new release is drafted on GitHub via the "Draft New Release" button on the `Releases page <https://github.com/PyAbel/PyAbel/releases>`__. But first, make a Pull Request that does the following:
+Each version of PyAbel that is released triggers a new DOI on Zenodo, so that people can cite the project. If you would like you name added to the author list on Zenodo, please include it in ``.zenodo.json``.
 
-- Increment the version number in abel/_version.py.
-- Modify CHANGELOG.rst to include the new changes in the new version.
 
+----
 
-Citations
----------
+For maintainers: Releasing a new version
+----------------------------------------
+
+First, make a pull request that does the following:
+
+- Increment the version number in ``abel/_version.py``.
+- Update ``CHANGELOG.rst`` by renaming the "Unreleased" section to the new version and the expected release date.
+- Use the changelog to write version release notes that can be included as a comment in the PR and will be used later.
+- Update copyright years in ``doc/conf.py``.
+
+After the PR is merged:
 
-Each version of PyAbel that is released triggers a new DOI on Zenodo, so that people can cite the project. If you would like you name added to the author list on Zenodo, please include it in ``.zenodo.json``. 
+- Press the "Draft a new release" button on the `Releases <https://github.com/PyAbel/PyAbel/releases>`__ page and create a new tag, matching the new version number (for example, "v1.2.3" for version "1.2.3").
+- Copy and paste the release notes from the PR into the release notes.
+- Release it!
+- PyAbel should be automatically released on PyPI (see `PR #161 <https://github.com/PyAbel/PyAbel/pull/161>`__).
+- Check that the new package is `on PyPI <https://pypi.org/project/PyAbel/>`__.
+- Check that the new docs are `on Read the Docs <https://readthedocs.org/projects/pyabel/versions/>`__.
+- Check that the new version is `on Zenodo <https://zenodo.org/record/5888391#.Yerecn3MKgw>`__.
+- A bot should automatically make a PR on the `conda-forge repo <https://github.com/conda-forge/pyabel-feedstock>`__. This takes a while and needs to be merged manually.
+- Check that the new conda packages are `on Anaconda.org <https://anaconda.org/conda-forge/pyabel/files>`__.

README.rst

@@ -3,6 +3,7 @@ PyAbel README
 
 ..
     Parts between "github-only" comments below are excluded or treated differently by Sphinx (see doc/readme_link.rst)
+    Links to RTD "latest" and GitHub "master" are also replaced with current version in setup.py for PyPI.
 
 .. begin-github-only1
 
@@ -62,19 +63,19 @@ The outcome of the numerical Abel transform depends on the exact method used. So
 Installation
 ------------
 
-PyAbel requires Python 3.5-3.9. (Note: PyAbel is also currently tested to work with Python 2.7, but Python 2 support will be removed soon.) `NumPy <https://numpy.org/>`__ and `SciPy <https://scipy.org/>`__ are also required, and `Matplotlib <https://matplotlib.org/>`__ is required to run the examples. If you don't already have Python, we recommend an "all in one" Python package such as the `Anaconda Python Distribution <https://www.anaconda.com/products/individual>`__, which is available for free.
+PyAbel requires Python 3.7–3.11. (Note: PyAbel is also currently tested to work with Python 2.7, but Python 2 support will be removed soon.) `NumPy <https://numpy.org/>`__ and `SciPy <https://scipy.org/>`__ are also required, and `Matplotlib <https://matplotlib.org/>`__ is required to run the examples. If you don't already have Python, we recommend an "all in one" Python package such as the `Anaconda Python Distribution <https://www.anaconda.com/products/individual>`__, which is available for free.
 
 With pip
 ~~~~~~~~
 
-The latest release can be installed from PyPi with ::
+The latest release can be installed from PyPI with ::
 
     pip install PyAbel
 
 With setuptools
 ~~~~~~~~~~~~~~~
 
-If you prefer the development version from GitHub, download it here, `cd` to the PyAbel directory, and use ::
+If you prefer the development version from GitHub, download it `here <https://github.com/PyAbel/PyAbel/tree/master>`__, ``cd`` to the PyAbel directory, and use ::
 
     python setup.py install
 
@@ -135,10 +136,12 @@ Output:
 .. image:: https://pyabel.readthedocs.io/en/latest/_images/readme_link-1.svg
     :alt: example Abel transform
 
-.. note:: Additional examples can be viewed on the `PyAbel examples <https://pyabel.readthedocs.io/en/latest/examples.html>`__ page and even more are found in the `PyAbel/examples <https://github.com/PyAbel/PyAbel/tree/master/examples>`__ directory.
+.. |examples| replace:: on the `PyAbel examples <https://pyabel.readthedocs.io/en/latest/examples.html>`__ page
 
 .. end-github-only3
 
+.. note:: Additional examples can be viewed |examples|, and even more are found in the `PyAbel/examples <https://github.com/PyAbel/PyAbel/tree/master/examples>`__ directory.
+
 
 Documentation
 -------------
@@ -198,9 +201,15 @@ Contributing
 
 We welcome suggestions for improvement, together with any interesting images that demonstrate  application of PyAbel.
 
-Either open a new `Issue <https://github.com/PyAbel/PyAbel/issues>`__ or make a `Pull Request <https://github.com/PyAbel/PyAbel/pulls>`__.
+Either open a new `issue <https://github.com/PyAbel/PyAbel/issues>`__ or make a `pull request <https://github.com/PyAbel/PyAbel/pulls>`__.
+
+.. begin-github-only4
+
+.. |CONTRIBUTING| replace:: `CONTRIBUTING.rst <https://github.com/PyAbel/PyAbel/blob/master/CONTRIBUTING.rst>`__
 
-`CONTRIBUTING.rst <https://github.com/PyAbel/PyAbel/blob/master/CONTRIBUTING.rst>`__ has more information on how to contribute, such as how to run the unit tests and how to build the documentation.
+.. end-github-only4
+
+|CONTRIBUTING| has more information on how to contribute, such as how to run the unit tests and how to build the documentation.
 
 
 License
@@ -218,12 +227,12 @@ First and foremost, please cite the paper(s) corresponding to the implementation
 
 If you find PyAbel useful in you work, it would bring us great joy if you would cite the project. You can find the DOI for the lastest verison at `Zenodo <https://dx.doi.org/10.5281/zenodo.594858>`__.
 
-.. begin-github-only4
+.. begin-github-only5
 
 .. image:: https://zenodo.org/badge/30170345.svg
     :target: https://zenodo.org/badge/latestdoi/30170345
 
-.. end-github-only4
+.. end-github-only5
 
 Additionally, we have written a scientific paper comparing various Abel transform methods. You can find the manuscript at the Review of Scientific Instruments (DOI: `10.1063/1.5092635 <https://doi.org/10.1063/1.5092635>`__) or on arxiv (`arxiv.org/abs/1902.09007 <https://arxiv.org/abs/1902.09007>`__).
 

appveyor.yml

@@ -13,10 +13,10 @@ environment:
     - PYTHON_VERSION: 2.7
       PYTHON_ARCH: "64"
       MINICONDA: C:\Miniconda-x64
-    - PYTHON_VERSION: 3.8
+    - PYTHON_VERSION: 3.7
       PYTHON_ARCH: "64"
       MINICONDA: C:\Miniconda3-x64
-    - PYTHON_VERSION: 3.9
+    - PYTHON_VERSION: 3.10
       PYTHON_ARCH: "64"
       MINICONDA: C:\Miniconda3-x64
 

doc/readme_link.rst

@@ -37,11 +37,17 @@
 
     plt.tight_layout()
 
-.. note:: Additional examples can be viewed in :doc:`PyAbel examples <examples>` and even more are found in the `PyAbel/examples <https://github.com/PyAbel/PyAbel/tree/master/examples>`__ directory.
+.. |examples| replace:: in :doc:`PyAbel examples <examples>`
 
 .. include:: ../README.rst
     :start-after: end-github-only3
     :end-before: begin-github-only4
 
+.. |CONTRIBUTING| replace:: :doc:`Contributing to PyAbel <contributing_link>`
+
 .. include:: ../README.rst
     :start-after: end-github-only4
+    :end-before: begin-github-only5
+
+.. include:: ../README.rst
+    :start-after: end-github-only5

setup.py

@@ -5,7 +5,7 @@
 from setuptools import setup, find_packages, Extension
 from distutils.errors import CCompilerError, DistutilsExecError, DistutilsPlatformError
 
-# a define the version string inside the package, see:
+# define the version string inside the package, see:
 # https://stackoverflow.com/questions/458550/standard-way-to-embed-version-into-python-package
 VERSIONFILE = "abel/_version.py"
 verstrline = open(VERSIONFILE, "rt").read()
@@ -91,9 +91,24 @@ def build_extensions(self):
                   'ext_modules': ext_modules}
 
 
+# use README as project description on PyPI:
 with open('README.rst') as file:
     long_description = file.read()
 
+# but remove CI badges
+long_description = re.sub(
+    '^.+?https://(travis-ci\.com|ci\.appveyor\.com)/.+?\n', '',
+    long_description, flags=re.MULTILINE,
+    count=4)  # limit to top 2 pairs of image + target
+
+# and change GH and RTD links to specific PyAbel version
+long_description = long_description.\
+    replace('https://github.com/PyAbel/PyAbel/tree/master/',
+            'https://github.com/PyAbel/PyAbel/tree/v' + version + '/').\
+    replace('https://pyabel.readthedocs.io/en/latest/',
+            'https://pyabel.readthedocs.io/en/v' + version + '/')
+
+
 setup(name='PyAbel',
       version=version,
       description='A Python package for forward and inverse Abel transforms',
@@ -107,6 +122,7 @@ def build_extensions(self):
                         "six >= 1.10.0"],
       package_data={'abel': ['tests/data/*']},
       long_description=long_description,
+      long_description_content_type='text/x-rst',
       classifiers=[
           # How mature is this project? Common values are
           #  3 - Alpha
@@ -134,6 +150,7 @@ def build_extensions(self):
           'Programming Language :: Python :: 3.8',
           'Programming Language :: Python :: 3.9',
           'Programming Language :: Python :: 3.10',
+          'Programming Language :: Python :: 3.11',
           ],
       **setup_args
       )