ericholscher / sphinx-tutorial

An opinionated tutorial on Sphinx.

Sphinx Tutorial

Welcome to the Introduction to Sphinx & Read the Docs. This tutorial will walk you through the initial steps writing reStructuredText and Sphinx, and deploying that code to Read the Docs.

Please provide feedback to @ericholscher.

Schedule

• 9-9:30 Introduction to the Tutorial
• 9:30-9:50 :doc:`start`
• 9:50-10:20 :doc:`step-1`
• 10:20-10:40 Break
• 10:40-11:10 :doc:`step-2`
• 11:10-11:40 :doc:`step-3`
• 11:40-12:20 :doc:`finish`

Thanks for coming

.. toctree::
   :maxdepth: 2
   :caption: Tutorial

   start
   step-1
   step-2
   step-3
   finish

.. toctree::
   :maxdepth: 2
   :caption: Supplemental Material

   cheatsheet

.. toctree::
   :caption: Step 1
   :glob:

   crawler/docs/step1/index

.. toctree::
   :caption: Step 2
   :glob:

   crawler/docs/step2/index

.. toctree::
   :caption: Step 3
   :glob:

   crawler/docs/step3/index

sphinx-tutorial's Issues

PDF of cheatsheet

Can you provide a pdf with the two pages of the cheatsheet?

The current pngs are not in a high resolution (which shows when printing) and two separate files makes it more difficult to print it double sized. A proper pdf can solve both these practical issues.

IMHO, there is no need to remove or replace the current pngs. They will show you the content of the pdf before you download it.

failed to import utils

without adding

sys.path.insert(0, os.path.abspath('../src/crawler/'))

to conf.py I get following error message:

WARNING: autodoc: failed to import module 'main' from module 'crawler'; the following exception was raised:
No module named 'utils'

Think this should be added in the Tutorial because it took me one hour to find out while doing Step 2

Getting grey background in preformatted text sections instead of #eeffcc

I'm going though the Sphinx tutorial and everything is working great, except for the preformatted text section backgrounds. They turn out grey, but when I click on the Live Preview links, the example pages have #eeffcc background color. I'm using the sphinx_rtd_theme as recommended and configured it according to the instructions. How can I get the #eeffcc background color which seems to be standard?

Typo in code-block directive

The directive .. code-block:: is erroneously listed as .. codeblock:: in cheatsheet-back-full.png.

addendum

Re last issue submitted by me. Having examined the tutorial code in detail I have re-edited the file 'pycon-sphinx-tutorial/crawler/src/main.py' so that when I run 'make.html' the build no longer fails and 'api.rst' displays correctly.

What I had to do was to modify the line 'from utils import log, should_ignore' to 'from crawler.utils import log, should_ignore'. The context for this change is that I had previously added 'pycon-sphinx-tutorial/crawler/src', the directory containing 'utils.py', to the Python sys.path so as to import 'log' and 'should_ignore' from the module now renamed crawler.utils.

Typo in cheatsheet: italic ↔ bold

Tiny typo spotted in files/cheatsheet-front-full.png on the Styles section. 😊

The correct version is:

*Italic text*
**Bold text**
…

exception prevents command make.html from importing module 'main' from module 'crawler'

I had to modify one line in 'pycon-sphinx-tutorial/src/crawler/main.py' to deal with an import exception:
'from utils import log, shouldignore'. To import the module 'main' so that Crawler Python API is displayed correctly one could either comment out the line or put it inside a try/except block:

try:
from utils import log, shouldignore
except ImportError:
pass

The command 'make html' now runs without WARNING and the page displays as intended, 'tho this will presumably affect the log and shouldignore flags elsewhere in the tutorial.

Documentation for how to use audodoc is missing important parts

For someone new to sphinx going through the simple setup is quite difficult and confusing to figure out how to use autodoc:

• what is autodoc? an extension? a module? a command?
• how to install the autodoc?
• how to set the source code path with sys.path.insert(0, os.path.abspath('.')) ?
• a working example of setting up autodoc complete with everything, not just incomplete bits and pieces

For dummies installation tutorial for starting

The installation part (http://sphinx-tutorial.readthedocs.org/start/) should be more "for the dummies" oriented:

• What are prerequisites for the installation ?
• On which OS is it possible to install it ?
• How do I create my first Sphinx documentation page ?

Too low resolution

User visits
https://sphinx-tutorial.readthedocs.io/cheatsheet/
but no matter how they try, all they can see are rather blurry low resolution images of the cheat sheet.

I would make a non-image version.