Dev:2.5/Py/API/Generating API Reference

API Documentation

For the API documentation, you can use the python module Sphinx to generate an up-to-date Python API local web site. With commit 25551, Campbell changed from epydocs to Sphinx as a means to generated API documentation.

Installing the Documentation Generator Sphinx

First, though, you need install:

1. Blender 2.7
2. Then get the Python Setup Tools.. Installing that gives you an easy_install executable in your Python/scripts folder.
3. Download and install Sphinx; run

• easy_install -U Sphinx

Note that easy_install may not be on your path, so you may have to fully qualify its location. This will go to PyPi on the internet, download and install the package.

Running Sphinx

Sphinx processes a set of input files and can output to multiple formats. To prepare this set of input files, from your GIT Blender source directory, every time you update from git, run.

blender --background --python ./doc/python_api/sphinx_doc_gen.py

This command will create a folder doc/python_api/sphinx-in. This folder contains a bunch of up-to-date rst files. Then, to make the documentation, from that same directory run:

sphinx-build doc/python_api/sphinx-in doc/python_api/sphinx-out

Note that sphinx-build may not be on your system PATH, so you may have to give the full path, eg: "c:\program files\blender foundation\python\scripts\sphinx-build". Worst case, use my little batch file and run the script via

"c:\program files\blender foundation\250\blender" --background --python ./doc/python_api/sphinx_doc_gen.py 
"c:\program files\blender foundation\python\scripts\sphinx-build-script.py" ./doc/python_api/sphinx-in .doc/python_api/sphinx-out
cd ./source/blender/python/doc/sphinx-out
echo opening Blender-Python API contents page. Find (ctrl-F) is your friend
contents.html

Note that I have my 2.7 in a subdirectory under the foundation, and my python is installed to run .py files, and firefox opens .html files.

Reading the docs

So now, if the python magic spell has worked, in your sphinx-out folder, you have a bunch of html files. Scroll to the bottom and open the contents.html file to get the main index. If the docs look like "real" python docs, that's because of sphinx. The Contents page lists all of the base classes and their implementations. For a kind of top-down view, start with Main. Have fun!