Expand HOW_TO_RELEASE and misc. docs fixes

[spencerahill]

HOW_TO_RELEASE now adds checks for doc builds and guide for updating feedstock for conda-forge

Made symbols for section headings consistent internally and adhering to suggested format (in order to suppress warnings from sphinx).

Other minor docstring edits to get rid of some sphinx warnings and to fix broken links.

I wrote a unit test for the doc builds, but I'm realizing that to ensure it runs correctly, we'd have to add sphinx, numpydoc, and sphinx_rtd_theme as package dependencies, which I don't think is worth it. I think we've learned our lesson, along with getting RTD configured properly and the expanded HOW_TO_RELEASE, so that this is unnecessary. So it's not in this PR, but for reference here's the code:

import subprocess
import os

import aospy

def test_docs_build():
    docs_dir = os.path.join(aospy.__path__[0], '..', 'docs')
    os.chdir(docs_dir)
    subprocess.call(['make', 'clean'])
    retcode = subprocess.call(['make', 'html'])
    # zero means success, nonzero means fail, so assert negation of retcode
    assert not retcode

[spencerahill]

xarray has a separate Travis build just for the docs (see the logic under the if [[ "$CONDA_ENV" == "docs" ]] statements in their .travis.yml file

Ah that's the perfect solution! Great catch. Will go this route.

[spencerkclark]

I'm not sure if this is relevant for the failing Travis builds: https://github.com/conda/conda/issues/3859.

It seems to suggest that the way we are calling conda env create -n test_env ... shouldn't work, but I'm a bit puzzled as to why it was working for so long before (the issue above seems fairly old). They suggest using conda create -n test_env (i.e. dropping the env) instead.

[spencerkclark]

Yikes! Sorry for sending you down the wrong path initially...thanks for figuring things out.

[spencerahill]

@spencerkclark ha no worries; it was a good idea. One of those hard-to-pin-down things...in fact I still don't fully understand it. But I don't care to dig any deeper now that it's finally working 😆

The Appveyor builds weren't triggered on the most recent commit probably by some internal error due to me pushing so many commits consecutively; the same thing happened on at least one of the earlier commits. So I'm willing to go ahead and merge this, but I'll wait for another once-over from you, since clearly I'm not doing so hot on catching details today!

[spencerahill]

Awesome. Thanks again @spencerkclark for the Travis docs build...definitely the way to go.