Sphinx Nuances

Tips for In-Line Python Examples

• For Python in-line examples, make sure to use 3 spaces for indents in the rst files. Not tabs, not 4 spaces, not 5 spaces. They often work, but sphinx can get confused. The 3 spaces is as shown in the sphinx docs.
• Make sure to leave an empty line after ".. ipython:: python". Otherwise, you'll get argument warnings/errors in the sphinx build.
• GitHub.io renders documentation using Python 2.7. But, try to write examples for python 3.4. That way, if it renders on both, new users won't have to worry about compatibility with copy/pasted code.
• Sphinx attempts to render multi-line functions, and sometimes doesn't render what comes after the function. Be sure to check the final output, and spacing.
• Consider using an extra ".. ipython:: python" if something doesn't render.