Help setting up Sphinx

Mario Figueiredo marfig at gmail.com
Mon Feb 16 18:55:29 EST 2015


Hello all,

I'm at loss as to how properly setup sphinx to document my code.
Getting a bit frustrated since I read everywhere it is an easy tool to
use, but I'm either too dumb or I'm missing something very obvious.

I setup sphinx with sphinx-quickstart. The following is how I answered
the prompts:

> Root path for the documentation [.]: docs
> Separate source and build directories (y/n) [n]:
> Name prefix for templates and static dir [_]:
> Project name: SmUDGE
> Author name(s): Mario Figueiredo
> Project version: 0.1
> Project release [0.1]: 
> Source file suffix [.rst]:
> Name of your master document (without suffix) [index]:
> Do you want to use the epub builder (y/n) [n]: n
> autodoc: automatically insert docstrings from modules (y/n) [n]: y
> doctest: automatically test code snippets in doctest blocks (y/n) [n]:
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]:
> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]:
> coverage: checks for documentation coverage (y/n) [n]: y
> pngmath: include math, rendered as PNG images (y/n) [n]:
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]:
> ifconfig: conditional inclusion of content based on config values (y/n) [n]:
> viewcode: include links to the source code of documented Python objects (y/n) [n]: y
> Create Makefile? (y/n) [y]: n
> Create Windows command file? (y/n) [y]: y

This resulted in a docs folder inside my project root, as intended.
For clarity, here's the project folder structure:

> /smudge --> project root
> /smudge/docs --> sphinx based documentation
> /smudge/smudge --> python scripts

Next I edited /smudge/docs/conf.py to include the path to my source
files:

> sys.path.insert(0, os.path.abspath('../smudge/'))

/smudge/smudge currently holds a single script file (item.py) with
some classes and docstrings.

Next I run $ make html to build the documentation, hoping the item.py
file gets parsed and added to the docs build folder.

But I get an empty documentation structure.
docs/_build/html/index.html shows only three entries in the Indices
and Tables section.

Index
Module Index
Search Page

Index is empty and Module Index is a 404

What am I missing in order to get item.py properly parsed by sphinx?



More information about the Python-list mailing list