Cleaner warning display in CircleCI (#570)

* Split standard output and standard error of CircleCI doc build

Update astropy_helpers to remove a few warnings
Remove 'macros' from circleci

.circleci/config.yml

@@ -1,32 +1,42 @@
-deps-run: &deps-install
-  name: Install Python dependencies and PlasmaPy
-  command: |
-    pip install --user -r requirements/automated-documentation-tests.txt | cat
-    pip install --user . | cat
-
-html-run: &doc-html
-  name: Build HTML documentation
-  command: python setup.py build_docs -w
-
-latex-run: &doc-latex
-  name: Build LaTeX documentation
-  command: python setup.py build_docs -b latex -w
-
 version: 2
 jobs:
   test-html:
     docker:
       - image: plasmapy/documentation-builder:latest
     steps:
       - checkout
-      - run: *deps-install
-      - run: *doc-html
+      - run: 
+          name: Install Python dependencies and PlasmaPy
+          command: |
+            pip install --user -r requirements/automated-documentation-tests.txt | cat
+            pip install --user . | cat
+      - run:
+          name: Build HTML documentation
+          shell: /bin/bash
+          # command needed to not fail the build step on non-zero exit code from sphinx
+          # (now is not the time for build fail)
+          # (that comes later)
+          command: |
+            # build docs, sending standard output and error to separate files in /tmp
+            # || true ignores the error code as stated above
+            # echo | tee prints out sphinx's error code and saves it to /tmp
+            python setup.py build_docs -W 2> >(tee /tmp/stderr) 1> >(tee /tmp/stdout) || true; echo $? | tee /tmp/EXITCODE
       - store_artifacts:
           path: docs/_build/html
       - run:
           name: "Built documentation is available at:"
           command: DOCS_URL="${CIRCLE_BUILD_URL}/artifacts/${CIRCLE_NODE_INDEX}/${CIRCLE_WORKING_DIRECTORY/#\~/$HOME}/docs/_build/html/index.html"; echo $DOCS_URL
-      - run: *doc-latex
+      - run:
+          name: "Output from html documentation build is:"
+          command: cat /tmp/stdout
+      - run:
+          name: "Error from html documentation build is:"
+          # display stderr from build AND assert the build went successfully
+          # build errors should fail at this stage
+          command: cat /tmp/stderr && [ $(cat /tmp/EXITCODE) -eq 0 ]
+      - run: 
+          name: Build LaTeX documentation
+          command: python setup.py build_docs -b latex -w
 
 workflows:
   version: 2