Fix Sphinx warnings (broken line blocks, short title underline, html_static_path)

[wking]

See the commit messages for details. With this series, the only
outstanding Sphinx warnings are:

/.../docs/index.rst:4: WARNING: nonlocal image URI found: https://api.travis-ci.org/wcdolphin/flask-cors.png?branch=master

and nine other nonlocal image warnings.

[coveralls]

Coverage remained the same when pulling 7999a1a on wking:doc-fixes into ae1e08a on wcdolphin:master.

[corydolphin]

Hi WKing,

Thanks for your contribution! I am new to sphinx and any help is much
appreciated. These changes look good at a glance (I need to read through
them more and get a better understanding of RST terminology before I merge.
)

Currently my workflow for docs is to use pandoc to convert the markdown
readme to RST, and then manually copy the relevant portions into the
index.rst file for sphinx to pick up. I spent some time googling but could
not find any good solutions which allow me to:

1. Write a single markdown readme with an overview of the project and
   common use cases
2. Import that readme into pypi/setup tools as the description (RST is
   supported)
3. Add auto generated documentation from the code automatically.

My dream is to have this process automated and seamless, so anything I
write in the readme propagates through. Do you have any idea or
suggestions for the process? You seem to know a lot about sphinx.

Thanks for your help!
Cory

On Wednesday, August 6, 2014, W. Trevor King notifications@github.com
wrote:

See the commit messages for details. With this series, the only
outstanding Sphinx warnings are:

/.../docs/index.rst:4: WARNING: nonlocal image URI found:
https://api.travis-ci.org/wcdolphin/flask-cors.png?branch=master

and nine other nonlocal image warnings.

You can merge this Pull Request by running

git pull https://github.com/wking/flask-cors doc-fixes

Or view, comment on, or merge it at:

#44
Commit Summary

• docs/index.rst: Remove line blocks
• docs/index.rst: Fix short underline for 'Full list of options'
• docs/conf.py: Remove _static from html_static_path

File Changes

• M docs/conf.py
  https://github.com/wcdolphin/flask-cors/pull/44/files#diff-0 (2)
• M docs/index.rst
  https://github.com/wcdolphin/flask-cors/pull/44/files#diff-1 (56)

Patch Links:

• https://github.com/wcdolphin/flask-cors/pull/44.patch
• https://github.com/wcdolphin/flask-cors/pull/44.diff

—
Reply to this email directly or view it on GitHub
#44.

Sent from my mobile, please excuse spelling and brevity

[wking]

On Wed, Aug 06, 2014 at 10:37:11PM -0700, Cory Dolphin wrote:

Currently my workflow for docs is to use pandoc to convert the
markdown readme to RST, and then manually copy the relevant portions
into the index.rst file for sphinx to pick up. I spent some time
googling but could not find any good solutions which allow me to:

1. Write a single markdown readme with an overview of the project
   and common use cases
2. Import that readme into pypi/setup tools as the description (RST
   is supported)
3. Add auto generated documentation from the code automatically.

PyPI uses reStructuredText 1, so I generally just write ReST
directly. GitHub also supports ReST 2, so there's no reason to
bring Markdown into the mix. If you don't want to search through the
ReST guide 3 to find the syntax for a particular construct, you can
always use Pandoc locally to figure out how the Markdown translates.

It's more awkward to get the README changes automatically included in
your Sphinx docs. Personally, I'd probably put most of the “How do I
use this” stuff in doc/source/index.rst (or doc/source/tutorial.rst,
or whatever), and push it to pythonhosted.org 4. Then have your
README.rst sketch out the basics (canonical repository, license, links
to bugtracker, etc.), and link to your pythonhosted docs for the
meatier stuff.

[corydolphin]

@wking I like that approach for the most part, but I am so used to writing Markdown, and at this point, PyPi is the only place I am forced to use ReST.

Soon I will restructure the README and add a better separation of concerns and information between README and the pythonhosted/readthedocs meatier documentation.

Thanks!
Cory

[wking]

On Wed, Aug 06, 2014 at 11:25:22PM -0700, Cory Dolphin wrote:

I like that approach for the most part, but I am so used to writing
Markdown, and at this point, PyPi is the only place I am forced to
use ReST.

You need ReST for Sphinx too, and you need Sphinx for autofunction
1. Going back and forth between Markdown (for other projects) and
ReST (for Python projects) isn't so bad ;).

Anyhow, can you hazard a guess about when you'll cut a release
containing this branch? I'm working up a package for Gentoo 2, and
I'd like to avoid patching your source. No hurry, but sometime in the
next few weeks would be nice :).