Convert NEWS.rst to NEWS.md, improve PDF documentation output (#175)

* replace NEWS.rst with NEWS.md, use https://keepachangelog.com format * only numbering two levels, not three * convert `AUTHORS.rst` to a table * use endnotes via `pagenote` for URLs in LaTeX backend, makes docs less cluttered, don't output footnotetext links for releases - rendering is off * update with new workflow for modifying NEWS
alexlancaster · Jan 2, 2024 · 9a32659 · 9a32659
1 parent 5e22a78
commit 9a32659
Show file tree

Hide file tree

Showing 9 changed files with 514 additions and 423 deletions.
diff --git a/.github/release-drafter.yml b/.github/release-drafter.yml
@@ -44,11 +44,18 @@ template: |
   ```
   pip install -U pypop-genomics
   ```
-  
-  ## Changes
+  Repository: $REPOSITORY
+
+  <!-- START cut-and-paste to NEWS.md -->
 
-  A full history of changes is available in [`NEWS.rst`](https://github.com/alexlancaster/pypop/blob/main/NEWS.rst).
+  ## $NEXT_PATCH_VERSION - YYYY-MM-DD
   
   $CHANGES
 
+  [$NEXT_PATCH_VERSION]: https://github.com/alexlancaster/pypop/releases/tag/v$NEXT_PATCH_VERSION
+
+  <!-- END cut-and-paste to NEWS.md -->
+
+  A full history of changes is available in [`NEWS.md`](https://github.com/alexlancaster/pypop/blob/main/NEWS.md).
+
   **Full Changelog:** https://github.com/alexlancaster/pypop/compare/$PREVIOUS_TAG...v$NEXT_PATCH_VERSION
diff --git a/AUTHORS.rst b/AUTHORS.rst
@@ -5,53 +5,77 @@ PyPop contributors
 
 (Listed in alphabetical order)
 
-Karl Kornel | `0000-0001-5847-5330 <https://orcid.org/0000-0001-5847-5330>`__ | Stanford Research Computing Center
-   Contributed containerization
-
-Alex Lancaster | `0000-0002-0002-9263 <https://orcid.org/0000-0002-0002-9263>`_ | Amber Biology LLC, Ronin Institute
-   Lead developer. Co-designer of Python framework: author of main engine, text file
-   parser, Python extension module framework using SWIG, XML output and
-   XSLT post-processing framework (to generate plain text and HTML
-   output).
-
-Steven J. Mack | `0000-0001-9820-9547 <https://orcid.org/0000-0001-9820-9547>`__ | University of California, San Francisco
-   Contributed bug reports, documentation, reviewed PRs.
-
-Michael P. Mariani | `0000-0001-5852-0517 <https://orcid.org/0000-0001-5852-0517>`__ | Mariani Systems LLC and University of Vermont
-   Contributed bug reports, documentation, reviewed PRs.
-
-Diogo Meyer | `0000-0002-7155-5674 <https://orcid.org/0000-0002-7155-5674>`__ | University of São Paulo
-   Reviewed and tested PyPop, contributed some statistical analysis code.
-
-Mark P. Nelson | University of California, Berkeley
-   Co-designer of Python framework: implemented and maintained Python
-   modules, particularly the module for Hardy-Weinberg analysis. Updated
-   and maintained XSLT code.
-
-Richard M. Single | `0000-0001-6054-6505 <https://orcid.org/0000-0001-6054-6505>`__ | University of Vermont
-   Author of haplotype frequency and linkage disequilibrium analysis
-   module ``emhaplofreq``.  Contributed documentation and testing/reviewing PRs.
-
-Vanessa Sochat | `0000-0002-4387-3819 <https://orcid.org/0000-0002-4387-3819>`__ | Lawrence Livermore National Laboratory
-   Contributed to the Python 3 port.
-
-Owen Solberg  | `0000-0003-3060-9709 <https://orcid.org/0000-0003-3060-9709>`__ 
-   Implemented filter modules, including conversion to allele name
-   information to sequence data.
-
-Jurriaan H. Spaaks | `0000-0002-7064-4069 <https://orcid.org/0000-0002-7064-4069>`__ | Netherlands eScience Center
-   Contributed to Zenodo upload GitHub action 
-
-Glenys Thomson | `0000-0001-5235-4159 <https://orcid.org/0000-0001-5235-4159>`__ | University of California, Berkeley
-   Principal investigator
-
-`Yingssu Tsai <https://github.com/ystsai>`__ | `0009-0006-0162-6066 <https://orcid.org/0009-0006-0162-6066>`__ | University of California, Berkeley
-   Implemented prototype of the allele names to sequence conversion
-   filter module.
-
-Gordon Webster | `0009-0009-2862-0467 <https://orcid.org/0009-0009-2862-0467>`__ | Amber Biology LLC
-   Contributed documentation and testing framework.
-
+.. list-table:: 
+   :widths: 18 22 28 30
+   :header-rows: 1
+   :class: longtable
+
+   * - Author
+     - ORCiD
+     - Affiliation
+     - Contribution
+   * - Karl Kornel
+     - `0000-0001-5847-5330 <https://orcid.org/0000-0001-5847-5330>`_
+     - Stanford Research Computing Center
+     - Contributed containerization
+   * - Alex Lancaster
+     - `0000-0002-0002-9263 <https://orcid.org/0000-0002-0002-9263>`_
+     - Amber Biology LLC,
+       Ronin Institute
+     - Lead developer. Co-designer of Python framework: author of main
+       engine, text file parser, Python extension module framework
+       using SWIG, XML output and XSLT post-processing framework (to
+       generate plain text and HTML output).
+   * - Steven J. Mack
+     - `0000-0001-9820-9547 <https://orcid.org/0000-0001-9820-9547>`__
+     - University of California, San Francisco
+     - Contributed bug reports, documentation, reviewed PRs.
+   * - Michael P. Mariani
+     - `0000-0001-5852-0517 <https://orcid.org/0000-0001-5852-0517>`__
+     - Mariani Systems LLC and University of Vermont
+     - Contributed bug reports, documentation, reviewed PRs.
+   * - Diogo Meyer
+     - `0000-0002-7155-5674 <https://orcid.org/0000-0002-7155-5674>`__
+     - University of São Paulo
+     - Reviewed and tested PyPop, contributed some statistical analysis code.
+   * - Mark P. Nelson
+     - 
+     - University of California, Berkeley
+     - Co-designer of Python framework: implemented and maintained
+       Python modules, particularly the module for Hardy-Weinberg
+       analysis. Updated and maintained XSLT code.
+   * - Richard M. Single
+     - `0000-0001-6054-6505 <https://orcid.org/0000-0001-6054-6505>`__
+     - University of Vermont
+     - Author of haplotype frequency and linkage disequilibrium
+       analysis module ``emhaplofreq``.  Contributed documentation and
+       testing/reviewing PRs.
+   * - Vanessa Sochat
+     - `0000-0002-4387-3819 <https://orcid.org/0000-0002-4387-3819>`__
+     - Lawrence Livermore National Laboratory
+     - Contributed to the Python 3 port.
+   * - Owen Solberg 
+     - `0000-0003-3060-9709 <https://orcid.org/0000-0003-3060-9709>`__
+     -
+     - Implemented filter modules, including conversion to allele name
+       information to sequence data.
+   * - Jurriaan H. Spaaks
+     - `0000-0002-7064-4069 <https://orcid.org/0000-0002-7064-4069>`__
+     - Netherlands eScience Center
+     - Contributed to Zenodo upload GitHub action 
+   * - Glenys Thomson
+     - `0000-0001-5235-4159 <https://orcid.org/0000-0001-5235-4159>`__
+     - University of California, Berkeley
+     - Principal investigator
+   * - `Yingssu Tsai <https://github.com/ystsai>`__
+     - `0009-0006-0162-6066 <https://orcid.org/0009-0006-0162-6066>`__
+     - University of California, Berkeley
+     - Implemented prototype of the allele names to sequence conversion
+       filter module.
+   * - Gordon Webster
+     - `0009-0009-2862-0467 <https://orcid.org/0009-0009-2862-0467>`__
+     - Amber Biology LLC
+     - Contributed documentation and testing framework.
 
 Third-party modules
 -------------------

diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
@@ -144,9 +144,10 @@ steps are:
 3. making a new branch
 4. `installing a development version <Installation for developers_>`_ on your machine
 5. updating your branch when "upstream" (the main repository) has changes to include those changes in your local branch
-6. updating the changelog in ``NEWS.rst``
+6. updating ``AUTHORS.rst``
 7. checking unit tests pass
-8. making a pull request
+8. making a pull request (including a description of your changes
+   suitable for inclusion in ``NEWS.md``)
 
 
 Fork this repository
@@ -232,29 +233,13 @@ You can push to your fork now if you wish:
 
 And, continue doing your developments are previously discussed.
 
-Update ``NEWS.rst``
--------------------
-
-Update the changelog file under :code:`NEWS.rst` with an explanatory
-bullet list of your contribution. Add that list under the "Notes
-towards the next release" under the appropriate category, e.g. for a
-new feature you would add something like:
-
-.. code-block:: text
-
-    Notes towards next release
-    --------------------------
-    (unreleased)
+Update ``AUTHORS.rst``
+----------------------
 
-    New features
-    ^^^^^^^^^^^^
-    
-    * here goes my new additions
-    * explain them shortly and well
-
-Also add your name to the authors list at :code:`AUTHORS.rst`, so you
+Also add your name to the author table at :code:`AUTHORS.rst`, so you
 will also be included in the periodic Zenodo software releases (see
-also the section on `Crediting contributors`_)
+also the section on `Crediting contributors`_).
+
 
 Run unit tests with ``pytest``
 ------------------------------
@@ -309,10 +294,29 @@ good practices (let us know if something can be improved).
 Make a Pull Request
 -------------------
 
-Once you are finished, you can create a pull request to the main
-repository and engage with the developers.  If you need some code
-review or feedback while you're developing the code just make a pull
-request.
+Once you are finished, create a pull request to the main repository
+and engage with the developers.
+
+When you create the pull request in the initial submission box, you
+should create a description of your changes with an explanatory bullet
+list of the contributions. Please note if any of your changes will
+break existing behaviour or anything else that would be important for
+an end-user to know. This description should be in Markdown format.
+Here is an example:
+
+.. code-block:: markdown
+
+    ### New features
+    
+    - here goes my new additions, explain them shortly and well
+    - this feature will require an an update to your `.ini` file
+
+This will be used to populate the Release Notes and eventually be
+included in the :code:`NEWS.md` file.
+
+If you need some code review or feedback while you're developing the
+code, you can also make a pull request, even if you're not fully
+finished.
 
 **However, before submitting a Pull Request, verify your development branch passes all
 tests as** `described above <run unit tests with pytest_>`_ **. If you are
@@ -325,7 +329,8 @@ Before requesting a finale merge, you should:
 1. Make sure your PR passes all ``pytest`` tests.
 2. Add unit tests if you are developing new features
 3. Update documentation when there's new API, functionality etc.
-4. Add a note to ``NEWS.rst`` about the changes.
+4. In the submission for the PR, include a description of the changes,
+   in markdown format, suitable for eventual inclusion in ``NEWS.md``.
 5. Add yourself to ``website/docs/AUTHORS.rst``.
 
 
@@ -651,7 +656,7 @@ outside ``website`` like ``README.rst`` and ``CONTRIBUTING.rst``:
    -  ``guide-chapter-instructions.rst``
    -  ``guide-chapter-contributing.rst`` (pulls in top-level
       ``CONTRIBUTING.rst`` that contains the source of the text that you are reading right now)
-   -  ``guide-chapter-changes.rst`` (pulls in top-level ``NEWS.rst`` and ``AUTHORS.rst``, which is local to ``website``)
+   -  ``guide-chapter-changes.rst`` (pulls in top-level ``NEWS.md`` and ``AUTHORS.rst``, which is local to ``website``)
    -  ``AUTHORS.rst``
    -  ``licenses.rst`` (pulls in top-level ``LICENSE``)
    -  ``biblio.rst``
@@ -728,7 +733,7 @@ documentation locally. Here’s an overview of how to do that:
 
    .. code-block:: shell
 
-      pip install setuptools_scm sphinx piccolo-theme sphinx_rtd_theme myst_parser rst2pdf sphinx_togglebutton sphinx-argparse
+      pip install setuptools_scm sphinx piccolo-theme sphinx_rtd_theme myst_parser rst2pdf sphinx_togglebutton sphinx-argparse sphinx_copybutton
 
 2. make a fork of pypop if you haven't already (see `previous section <Fork this repository_>`_)
 
@@ -786,7 +791,7 @@ We define *contributions* in a broad way: including both writing code
 as well as documentation, and reviewing issues and PRs etc. Here are
 some ways we credit contributors:
 
-``AUTHORS.rst``, ``NEWS.rst`` and GitHub Release Notes
+``AUTHORS.rst``, ``NEWS.md`` and GitHub Release Notes
 ------------------------------------------------------
 
 Anyone who has contributed a pull request to the project is welcome to
@@ -795,7 +800,7 @@ part of the repository and included with with distributions.
 
 Every time we make a release, everyone who has made a commit to the
 repository since the previous release will be mentioned in either the
-``NEWS.rst`` or in the GitHub Release Notes.
+``NEWS.md`` or in the GitHub Release Notes.
 
 Authorship on Zenodo archives of releases
 -----------------------------------------