Added packages and info on building docs on gh-pages to "Contributing"

doc/Makefile

@@ -14,6 +14,16 @@ help:
 
 .PHONY: help Makefile
 
+# make github: 
+github:
+	find .. -name '*.html' -exec rm {} +
+	@make clean
+	@make html
+	@cp -a $(BUILDDIR)/html/. ../
+
+clean:
+	rm -rf $(BUILDDIR)
+
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile

doc/source/contributing_code.rst

@@ -212,12 +212,18 @@ and activated your virtual environment. First we need to install dependencies:
          cython numpy mmtf-python mock six biopython \
          networkx cython matplotlib scipy griddataformats \
          hypothesis gsd codecov "seaborn>=0.7.0,<=0.9" \
-         clustalw=2.1 netcdf4 scikit-learn "joblib>=0.12"
+         clustalw=2.1 netcdf4 scikit-learn "joblib>=0.12"\
+         psutil pytest
+        # if using conda with python 3.7 or 3.8, also run
+        conda install -c conda-forge parmed
+        # if using conda with other versions of python, also run
+        pip install parmed
+
         # if using pip
         pip install cython numpy mmtf-python mock six biopython \
          networkx cython matplotlib scipy griddataformats \
          hypothesis gsd codecov "seaborn>=0.7.0,<=0.9" \
-         netcdf4 scikit-learn "joblib>=0.12"
+         netcdf4 scikit-learn "joblib>=0.12" parmed psutil pytest
 
 Ensure that you have a working C/C++ compiler (e.g. gcc or clang). You will also need Python ≥ 3.4. We will now install MDAnalysis. 
 
@@ -234,7 +240,7 @@ Ensure that you have a working C/C++ compiler (e.g. gcc or clang). You will also
         cd ../testsuite/
         pip install -e .
 
-At this point you should be able to import MDAnalysis from your locally built version, this is visible from the version number ending in "-dev0" for example:
+At this point you should be able to import MDAnalysis from your locally built version. If you are running the development version, this is visible from the version number ending in "-dev0". For example:
 
     .. code-block:: bash
 
@@ -243,6 +249,14 @@ At this point you should be able to import MDAnalysis from your locally built ve
         >>> mda.__version__
         '0.20.2-dev0'
 
+If your version number does not end in "-dev0", you may be on the ``master`` branch. In your ``mdanalysis/`` directory, switch to the ``develop`` branch:
+
+    .. code-block:: bash
+
+        $ git checkout develop
+        Switched to branch 'develop'
+
+
 .. _branches-in-mdanalysis:
 
 ----------------------

doc/source/contributing_docs.rst

@@ -119,6 +119,45 @@ Adding changes to the UserGuide
 
 As with the code, :ref:`commit and push <adding-code-to-mda>` your code to GitHub. Then :ref:`create a pull request <create-a-pull-request>`. The only test run for the User Guide is: that your file compile into HTML documents without errors. As usual, a developer will review your PR and merge the code into the User Guide when it looks good.
 
+It is often difficult to review Jupyter notebooks on GitHub, especially if you embed widgets and images. One way to make it easier on the developers who review your changes is to build the changes on your forked repository and link the relevant sections in your pull request. To do this, create a ``gh-pages`` branch and merge your new branch into it. 
+
+.. code-block:: bash
+
+    # the first time
+    git checkout -b gh-pages
+    git merge origin/my-new-branch
+
+Fix any merge conflicts that arise. Then edit ``UserGuide/doc/source/conf.py`` and change the URL of the site, which is set to ``site_url = "https://www.mdanalysis.org/UserGuide"``. Change it to your personal site, e.g. ::
+
+    site_url = "https://www.my_user_name.github.io/UserGuide"
+
+
+Now you can build your pages with the ``make github`` macro in the ``UserGuide/doc/`` directory, which builds the files and copies them to the top level of your directory.
+
+.. code-block:: bash
+
+    make github
+
+You should be able to open one of these new HTML files (e.g. ``UserGuide/index.html``) in a browser and navigate your new documentation. Check that your changes look right. If they are, push to your `gh-pages` branch from the ``UserGuide/`` directory.
+
+.. code-block:: bash
+
+    git add .
+    git commit -m 'built my-new-branch'
+    git push -f origin gh-pages
+
+On GitHub, navigate to your fork of the repository and go to **Settings**. In the **GitHub Pages** section, select the "gh-pages branch" from the **Source** dropdown. Check that your website is published at the given URL.
+
+.. image:: images/gh-pages-settings.png
+
+For each time you add changes to another branch later, just merge into gh-pages and rebuild. 
+
+.. code-block:: bash
+
+    git checkout gh-pages
+    git merge origin/my_branch
+    cd doc/
+    make github
 
 .. _autobuild-sphinx:
 

doc/source/index.rst

@@ -112,6 +112,7 @@ Wherever possible, do not take these conversations to private channels, includin
 
    standard_selections
    advanced_topology
+   datasets
 
 .. toctree::
    :maxdepth: 1
@@ -124,4 +125,4 @@ Wherever possible, do not take these conversations to private channels, includin
    preparing_releases_and_hotfixes
    module_imports
    testing
-   datasets
+