merge website/README.md into CONTRIBUTORS.rst (#100)

* rebuild docs if CONTRIBUTING.rst, NEWS.rst, LICENSE changes

* integrate website/README.md into CONTRIBUTING.rst

.github/workflows/documentation.yaml

@@ -3,6 +3,9 @@ on:
   push:
     paths:
       - 'README.rst'
+      - 'CONTRIBUTING.rst'
+      - 'NEWS.rst'
+      - 'LICENSE'
       - 'website/**'
       - 'src/PyPop/CommandLineInterface.py'
       - '!website/README.md'
@@ -11,6 +14,9 @@ on:
   pull_request:
     paths:
       - 'README.rst'
+      - 'CONTRIBUTING.rst'
+      - 'NEWS.rst'
+      - 'LICENSE'
       - 'website/**'
       - 'src/PyPop/CommandLineInterface.py'
       - '!website/README.md'
@@ -19,6 +25,9 @@ on:
   workflow_dispatch:
     paths:
       - 'README.rst'
+      - 'CONTRIBUTING.rst'
+      - 'NEWS.rst'
+      - 'LICENSE'
       - 'website/**'
       - 'src/PyPop/CommandLineInterface.py'
       - '!website/README.md'

CONTRIBUTING.rst

@@ -53,9 +53,12 @@ Documentation improvements
 
 **pypop** could always use more documentation, whether as part of the
 official docs, in docstrings, or even on the web in blog posts,
-articles, and such. Write us a `documentation issue <https://github.com/alexlancaster/pypop/issues/new>`_ describing what you
-would like to see improved in here, and, if you can do
-it, just `Pull Request <https://github.com/alexlancaster/pypop/pulls>`_ your proposed updates ``:-)``.
+articles, and such. Write us a `documentation issue
+<https://github.com/alexlancaster/pypop/issues/new>`_ describing what
+you would like to see improved in here.
+
+If you are able to contribute directly (e.g., via a pull request), please read
+our `website contribution guide <Making a documentation or website contribution_>`_.
 
 Feature requests and feedback
 -----------------------------
@@ -123,15 +126,15 @@ From the ``main`` branch create a new branch where to develop the new code.
 
 **Note** the ``main`` branch is from the main repository.
 
-Build locally
--------------
+Build locally and make your changes
+-----------------------------------
 
 Now you are ready to make your changes.  First, you need to build
 ``pypop`` locally on your machine, and ensure it works, see the
 separate section on `building and installing a development version
 <Installation for developers_>`_.
 
-Once you have done the installation and have verified that it works
+Once you have done the installation and have verified that it works,
 you can start to develop the feature, or make the bug fix, and keep
 regular pushes to your fork with comprehensible commit messages.
 
@@ -170,8 +173,8 @@ You can push to your fork now if you wish:
 
 And, continue doing your developments are previously discussed.
 
-Update NEWS.rst
----------------
+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
@@ -512,6 +515,188 @@ command:
 
    ./setup clean --all
 
+Making a documentation or website contribution
+==============================================
+
+Interested in maintaining the PyPop website and/or documentation, such
+as the *PyPop User Guide*? Here are ways to help.
+
+Overview
+--------
+
+All the documentation (including the website homepage) are maintained in
+this directory (and subdirectories) as
+`reStructuredText <https://docutils.sourceforge.io/rst.html>`__
+(``.rst``) documents. reStructuredText is very similar to GitHub
+markdown (``.md``) and should be fairly self-explanatory to edit
+(especially for pure text changes). From the .rst “source” files which
+are maintained here on github, we use
+`sphinx <https://www.sphinx-doc.org/en/master/>`__ to generate (aka
+“compile”) the HTML for both the pypop.org user guide and and PDF (via
+LaTeX) output. We have setup a GitHub action, so that as soon as a
+documentation source file is changed, it will automatically recompile
+all the documentation, update the ``gh-pages`` branch (which is synced
+to the GitHub pages) and update the files on the website.
+
+Here’s an overview of the process:
+
+::
+
+   .rst files -> sphinx -> HTML / PDF -> push to gh-pages branch -> publish on pypop.org
+
+This means that any changes to the source will automatically update both
+website home page the documentation.
+
+Once any changes are pushed to a branch (as described below), the GitHub
+action will automatically rebuild the website, and the results will be
+synced to a “staging” version of the website at:
+
+-  https://alexlancaster.github.io/beta.pypop.org/
+
+Structure
+---------
+
+Here’s an overview of the source files for the website/documentation
+located in the ``website`` subdirectory at the time of writing.  Note
+that some of the documentation and website files, use the
+``include::`` directive to include some "top-level" files, located
+outside ``website`` like ``README.rst`` and ``CONTRIBUTING.rst``:
+
+-  ``index.rst`` (this is the source for the homepage at
+   http://pypop.org/)
+-  ``conf.py`` (Sphinx configuration file - project name and other
+   global settings are stored here)
+   
+- ``docs`` (directory containing the source for the *PyPop User
+   Guide*, which will eventually live at http://pypop.org/docs). 
+
+   -  ``index.rst`` (source for the top-level of the *PyPop User Guide*)
+   -  ``guide-chapter-install.rst`` (pulls in parts of the top-level ``README.rst``)
+   -  ``guide-chapter-usage.rst``
+   -  ``guide-chapter-instructions.rst``
+   -  ``guide-chapter-contributing.rst`` (includes the top-level
+      ``.rst`` file ``CONTRIBUTING.rst`` that contains the source of
+      the text that you are reading right now)
+   -  ``guide-chapter-changes.rst`` (includes top-level ``NEWS.rst`` and ``AUTHORS.rst``, which is local to ``website``)
+   -  ``licenses.rst`` (includes top-level ``LICENSE``)
+   -  ``biblio.rst``
+
+-  ``html_root`` (any files or directories commited in this directory
+   will appear at the top-level of the website)
+
+   -  ``psb-pypop.pdf`` (e.g. this resides at
+      http://pypop.org/psb-pypop.pdf)
+   -  ``tissue-antigens-lancaster-2007.pdf``
+   -  ``PyPopLinux-0.7.0.tar.gz`` (old binaries - will be removed soon)
+   -  ``PyPopWin32-0.7.0.zip``
+   -  ``popdata`` (directory - Suppl. data for Solberg et. al 2018 -
+      https://pypop.org/popdata/)
+
+-  ``reference`` (directory containing the old DocBook-based
+   documentation, preserved to allow for unconverted files to be
+   converted later, this directory is ignored by the build process)
+
+Modifying documentation
+-----------------------
+
+Minor modifications
+~~~~~~~~~~~~~~~~~~~
+
+For small typo fixes, moderate copyedits at the paragraph level
+(e.g. adding or modifying paragraphs with little or no embedded markup),
+you can make changes directly on the github website.
+
+1. navigate to the ``.rst`` file you want to modify in the GitHub code
+   directory, you’ll see a preview of how most of the ``.rst`` will be
+   rendered
+
+2. hover over the edit button - you’ll see an “**Edit the file in a
+   fork in your project**” (if you are already a project collaborator,
+   you may also have the optional of creating a branch directly in the
+   main repository).
+
+3. click it and it will open up a window where you can make your changes
+
+4. make your edits (it’s a good idea to look at the preview tab
+   periodically as you make modifications)
+
+5. once you’ve finished with the modifications, click “**Commit
+   changes**”
+
+6. put in an a commit message, and click “**Propose changes**”
+
+7. this will automatically create a new branch in your local fork, and
+   you can immediately open up a pull-request by clicking “**Create pull
+   request**”
+
+8. open up a pull-request and submit - new documentation will be
+   automatically built and reviewed. if all is good, it will be merged
+   by the maintainer and made live on the site.
+
+Major modifications
+~~~~~~~~~~~~~~~~~~~
+
+For larger structural changes involving restructuring documentation or
+other major changes across multiple ``.rst`` files, **it is highly
+recommended** that you should make all changes in your own local fork,
+by cloning the repository on your computer and then building the
+documentation locally. Here’s an overview of how to do that:
+
+   The commands in
+   ```.github/workflows/documentation.yaml`` `</.github/workflows/documentation.yaml>`_
+   which are used to run the GitHub Action that builds the documentation
+   when it it deployed, is the best source for the most update-to-date
+   commands to run, and should be consulted if the instructions in this
+   README become out of date.
+
+1. install sphinx and sphinx extensions
+
+   ::
+
+      pip install --user sphinx piccolo-theme sphinx_rtd_theme myst_parser rst2pdf sphinx_togglebutton
+
+2. make a fork of pypop if you haven't already (see `previous section <Fork this repository_>`_)
+
+3. `clone the fork and add your fork as an upstream repository <Clone
+   the main repository_>`_ on your local computer, and `make a new
+   branch`_.
+
+4. make your changes to your ``.rst`` files and/or ``conf.py``
+
+5. build the HTML documentation:
+
+   ::
+
+      sphinx-build website _build
+
+6. view the local documention: you can open up browser and navigate to
+   the ``index.html`` in the top-level of the newly-created ``_build``
+   directory
+
+7. use ``git commit`` to commit your changes to your local fork.
+
+8. open up a pull-request against the upstream repository
+
+Building the PDF for the *PyPop User Guide* is a bit more involved, as
+you will need to have various TeX packages installed.
+
+1. install the LaTeX packages (these are packages needed for Ubuntu,
+   they may be different on your distribution):
+
+   ::
+
+      sudo apt-get install -y latexmk texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended texlive-fonts-extra texlive-luatex texlive-xetex
+
+2. build the LaTeX and then compile the PDF:
+
+   ::
+
+      sphinx-build -b latex website _latexbuild
+      make -C _latexbuild
+
+3. the user guide will be generated in ``_latexbuild/pypop-guide.pdf``
+
+
 
 .. _Fork this repository before contributing: https://github.com/alexlancaster/pypop/network/members
 .. _up to date with the upstream: https://gist.github.com/CristinaSolana/1885435

README.rst

@@ -367,6 +367,7 @@ Copyright and License
 
 PyPop is Copyright (C) 2003-2006. The Regents of the University of
 California (Regents)
+
 Copyright (C) 2007-2023 PyPop team.
 
 PyPop is distributed under the terms of GPLv2