Fix documentation (#711)

* Fix display of "broken" PyTrilinos

* Build PDF on Py3k

* Fix display of "broken" PyTrilinos

* Build PDF on Py3k

* Tarball the html docs

* Strip leading directories from tarball

* Don't tar the tarball into itself

* Tar documentation only

* Fiddling with what artifacts to store for html docs

* Revise instructions on where to get build products

* Change AppVeyor links to organization builds

.circleci/config.yml

@@ -104,6 +104,10 @@ commands:
             source activate ~/project/<< parameters.condaenv >>
             export ETS_TOOLKIT=null
             python setup.py build_docs --html
+            tar -czf ~/project/html.tar.gz -C ~/project/documentation/_build html
+
+      - store_artifacts:
+          path: ~/project/html.tar.gz
 
       - store_artifacts:
           path: ~/project/documentation/_build/html
@@ -465,9 +469,6 @@ jobs:
       - build_html_docs:
           condaenv: << parameters.condaenv >>
 
-      - build_pdf_docs:
-          condaenv: << parameters.condaenv >>
-
   build-36-docs:
     <<: *defaults3
 
@@ -501,6 +502,9 @@ jobs:
       - build_html_docs:
           condaenv: << parameters.condaenv >>
 
+      - build_pdf_docs:
+          condaenv: << parameters.condaenv >>
+
   build-binaries:
     <<: *defaults3
 

README.rst

@@ -163,7 +163,7 @@ or a
 .. |TravisCI|      image:: https://img.shields.io/travis/usnistgov/fipy/master.svg?label=macOS
 .. _TravisCI:      https://travis-ci.org/usnistgov/fipy
 .. |AppVeyor|      image:: https://ci.appveyor.com/api/projects/status/github/usnistgov/fipy?branch=master&svg=true&failingText=Windows%20-%20failing&passingText=Windows%20-%20passing&pendingText=Windows%20-%20pending
-.. _AppVeyor:      https://ci.appveyor.com/project/guyer/fipy
+.. _AppVeyor:      https://ci.appveyor.com/project/usnistgov/fipy
 .. |OpenHub|       image:: https://www.openhub.net/p/fipy/widgets/project_thin_badge.gif
 .. _OpenHub:       https://www.openhub.net/p/fipy
 .. |PyPI|          image:: https://img.shields.io/pypi/v/fipy.svg

documentation/ADMINISTRATA.rst

@@ -130,7 +130,7 @@ Windows builds are performed on AppVeyor_. This CI is configured in
 .. |TravisCI|      image:: https://img.shields.io/travis/usnistgov/fipy/master.svg?label=macOS
 .. _TravisCI:      https://travis-ci.org/usnistgov/fipy
 .. |AppVeyor|      image:: https://ci.appveyor.com/api/projects/status/github/usnistgov/fipy?branch=master&svg=true&failingText=Windows%20-%20failing&passingText=Windows%20-%20passing&pendingText=Windows%20-%20pending
-.. _AppVeyor:      https://ci.appveyor.com/project/guyer/fipy
+.. _AppVeyor:      https://ci.appveyor.com/project/usnistgov/fipy
 
 .. _{FiPySource}/.circleci/config.yml: https://github.com/usnistgov/fipy/blob/master/.circleci/config.yml
 .. _{FiPySource}/.travis.yml: https://github.com/usnistgov/fipy/blob/master/.travis.yml
@@ -214,21 +214,19 @@ the tagged build products and place in :file:`dist/`:
   :file:`FiPy-x.y.tar.gz`
     From CircleCI_ `build-binaries` Artifacts
 
-  :file:`FiPy-x.y.win32.zip`
-    From AppVeyor_ Artifacts
-
-Clean the working copy::
-
-    $ git clean -fd
+  :file:`~/project/documentation/_build/latex/fipy.pdf`
+    From CircleCI_ `build-36-docs` Artifacts
 
-.. note::
+  :file:`~/project/html.tar.gz`
+    From CircleCI_ `build-36-docs` Artifacts
 
-   Alternatively, clone into a clean repository.
+  :file:`FiPy-x.y.win32.zip`
+    From AppVeyor_ Artifacts
 
-Build the documentation and the web pages::
+From the :file:`{FiPySource}` directory, unpack :file:`dist/html.tar.gz`
+into file:`documentation/_build` with::
 
-    $ python setup.py bdist_egg
-    $ python setup.py build_docs --pdf --html --cathartic
+    $ tar -xzf dist/html.tar.gz -C documentation/_build
 
 ------
 Upload
@@ -258,7 +256,13 @@ Upload the web site to CTCMS ::
 Update conda-forge feedstock
 ----------------------------
 
-Using a pull request, update the fipy-feedstock_ with:
+Once you push the tag to GitHub_, the fipy-feedstock_ should automatically
+receive a pull request.  Review and amend this pull request as necessary
+and ask the `feedstock maintainers`_ to merge it.
+
+This automated process only runs once an hour, so if you don't wish to wait
+(or it doesn't trigger for some reason), you can manually generate a pull
+request to update the fipy-feedstock_ with:
 
 * revised version number
 * revised sha256 (use ``openssl dgst -sha256 /path/to/fipy-x.y.tar.gz``)
@@ -282,3 +286,4 @@ Make an announcement to `fipy@nist.gov`_
 .. _twine: https://pypi.org/project/twine
 .. _fipy-feedstock: https://github.com/conda-forge/fipy-feedstock
 .. _fipy@nist.gov: mailto:fipy@nist.gov
+.. _feedstock maintainers: https://github.com/conda-forge/fipy-feedstock#feedstock-maintainers

documentation/USAGE.rst

@@ -358,11 +358,11 @@ that there is either a problem importing one of the required packages or
 that there is some problem with the :term:`MPI` environment. For example::
 
          mpi4py            PyTrilinos           petsc4py                   FiPy            
-    processor 0 of 3 :: processor 0 of 3 :: processor 0 of 3 :: 10 cells on processor 0 of 1
+    processor 0 of 3 :: processor 0 of 1 :: processor 0 of 3 :: 10 cells on processor 0 of 1
     [my.machine.com:69815] WARNING: There were 4 Windows created but not freed.
-    processor 1 of 3 :: processor 1 of 3 :: processor 1 of 3 :: 10 cells on processor 0 of 1
+    processor 1 of 3 :: processor 0 of 1 :: processor 1 of 3 :: 10 cells on processor 0 of 1
     [my.machine.com:69814] WARNING: There were 4 Windows created but not freed.
-    processor 2 of 3 :: processor 2 of 3 :: processor 2 of 3 :: 10 cells on processor 0 of 1
+    processor 2 of 3 :: processor 0 of 1 :: processor 2 of 3 :: 10 cells on processor 0 of 1
     [my.machine.com:69813] WARNING: There were 4 Windows created but not freed.
 
 indicates :term:`mpi4py` is properly communicating with :term:`MPI` and is running
@@ -371,8 +371,9 @@ serial environments. As a result, :term:`FiPy` is limited to three separate
 serial operations, too. In this instance, the problem is that although
 :ref:`TRILINOS` was compiled with :term:`MPI` enabled, it was compiled against a
 different :term:`MPI` library than is currently available (and which :term:`mpi4py`
-was compiled against). The solution is to rebuild :ref:`TRILINOS` against
-the active :term:`MPI` libraries.
+was compiled against).  The solution, in this instance, is to solve with
+:ref:`PETSC` or to rebuild :ref:`TRILINOS` against the active :term:`MPI`
+libraries.
 
 When solving in parallel, :term:`FiPy` essentially breaks the problem
 up into separate sub-domains and solves them (somewhat) independently.

documentation/_templates/index.html

@@ -64,7 +64,7 @@ <h1>FiPy: A Finite Volume PDE Solver Using Python</h1>
   <!-- Development & Quality Assurance Badges -->
   <a href="https://circleci.com/gh/usnistgov/fipy"><img src="https://img.shields.io/circleci/project/github/usnistgov/fipy/master.svg?label=Linux" alt="Linux status"></img></a>
   <a href="https://travis-ci.org/usnistgov/fipy"><img src="https://img.shields.io/travis/usnistgov/fipy/master.svg?label=macOS" alt="macOS status"></img></a>
-  <a href="https://ci.appveyor.com/project/guyer/fipy"><img src="https://ci.appveyor.com/api/projects/status/github/usnistgov/fipy?branch=master&svg=true&failingText=Windows%20-%20failing&passingText=Windows%20-%20passing&pendingText=Windows%20-%20pending" alt="Windows status"></img></a>
+  <a href="https://ci.appveyor.com/project/usnistgov/fipy"><img src="https://ci.appveyor.com/api/projects/status/github/usnistgov/fipy?branch=master&svg=true&failingText=Windows%20-%20failing&passingText=Windows%20-%20passing&pendingText=Windows%20-%20pending" alt="Windows status"></img></a>
   <br>
   <a href="https://github.com/usnistgov/fipy"><img src="https://img.shields.io/github/contributors/usnistgov/fipy.svg" alt="GitHub"></img></a>
   <a href="https://pypi.python.org/pypi/FiPy"><img src="https://img.shields.io/pypi/v/fipy.svg" alt="PyPi"></img></a>