Sphinx is widely used to generate python document. Here is a brief tutorial to generate your own doc

brew install sphinx-doc
        

Source Code

# get source code 
git clone https://github.com/lin-chen-Langley/prime
		

Inside "Prime" folder, sphinx-quickstart doc

• Separate source and build directories (y/n) [n], press "Enter"
• Project name: yourProjectName
• Author Name: yourName
• Project version []: yourProjectVersion
• Project release [0.1], press "Enter"
• Project language [en], press "Enter"

sphinx-apidoc -o doc ./src inside "Prime" folder, generate a rst file for each py file or each package under "src" folder, and save them to "doc" folder

1. edit conf.py in "doc" folder, define where to search the source code

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

2. edit theme, built-in themes

html_theme = 'classic'

3. edit extensions

extensions = ['sphinx.ext.autodoc']

edit index.rst in "doc" folder, add rst files for the modules and packages that will be shown in index.html, use reStructuredText to edit the file, rst files are initial documentation files

.. toctree:: 
     :maxdepth: 2
     :caption: Contents:
     :glob: 
---Blank Line--- 
.. use three spaces instead of a tab
     modules.rst

edit modules.rst, change the title from "src" to "packages"

make html in "doc" folder, save the generated html doc to _build

1. edit conf.py in "doc" folder

# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
html_logo = 'img/prime.jepg'
			

2. make html, in "doc" folder

Mac OS

• Install Manport
• sudo port install texlive texlive-latex-extra, install latex
• make latexpdf, create latex files and a pdf file in _build/latex

Ubuntu

• sudo apt-get install texlive-base texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended texlive-fonts-extra texlive-latex-base texlive-font-utils
• sudo apt-get install latexmk
• make latexpdf, create latex files and a pdf file in _build/latex

Sphinx Themes

Sphinx Autodoc Tutorial for Dummies

Sphinx Docs, Logo and Updated Docstrings

Brandon’s Sphinx Tutorial