How to auto generate documentation with Sphinx?

Coding
#1

Hi,

I’d like to auto generate some documentation for a rigging system that I’m writing, I know that Sphinx can be used to do it but I can’t figure out how… I’d like to supply it with my python package and have it go through the python files in the directories and convert the docstring and comments into documentation and output it as an html. Can anyone help?

Thanks!

#2

@Jeff_Hanna spent some time setting this up for us last year, I don’t know the particulars of it, but possibly he remembers.

#3

It’s one of those things you setup then forget all about how to do it, but if you want some reference we use Sphinx in our Red9 documentation and all the code to run it is on gitHub

I’d like to update a lot of the formatting but just never find the time to do so…

cheers

Mark

1 Like
#4

There are 2 sorts of docs you can generate with Sphinx:

  1. API docs based on docstrings
  2. docs based on restructured text

This shows you how to do the later, but it’s a start and you should be able to continue from here…
First, get Sphinx and the RTD theme, which looks nicer than the default one.

  1. pip install sphinx
  2. pip install sphinx_rtd_theme

Create a directory named source wherever you want the source for your docs to live. (e.g. C:\somewhere\docs\source). Next create a file called conf.py and put it into the source directory. This is the general config file for the docs you are building.
Example:

# -*- coding: utf-8 -*-

import sys
import os
import shlex
import sphinx_rtd_theme

project = u'Documentation of my Project'
author = u'Robert Kist'

version = '0.0.1'
release = '0.0.1'
basename = 'mysoftwaretool'

extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.todo',
'sphinx.ext.ifconfig',
'sphinx.ext.graphviz',
]

inheritance_graph_attrs = dict(rankdir="TB", size='""')
graphviz_output_format = 'svg'
templates_path = ['_templates']

source_suffix = '.rst'
master_doc = 'index'
language = None

exclude_patterns = []
pygments_style = 'sphinx'

todo_include_todos = True
html_theme = 'sphinx_rtd_theme'
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
# html_static_path = ['_static']
html_show_sourcelink = False
html_show_sphinx = False
html_show_copyright = False
htmlhelp_basename = '%sdoc' % basename
latex_elements = {}
latex_documents = [
(master_doc, '%s.tex' % basename, u'%s Documentation' % basename,
author, 'manual'),
]

man_pages = [
(master_doc, basename, u'%s Documentation' % basename,
[author], 1)
]

texinfo_documents = [
(master_doc, basename, u'%s Documentation' % basename,
author, basename, 'One line description of project.',
'Miscellaneous'),
]

intersphinx_mapping = {'https://docs.python.org/': None}

Next create an index.rst file and put it into the source directory. This will be the starting page of your documentation. Example:

Hello World!
############

outside the source directory run this command. It will take read source/conf.py and process any RST .files in source. It will then create HTML output in output

C:\Python27\Scripts\sphinx-build.exe -b html source output