From BlenderWiki

Jump to: navigation, search

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.5
  2. Python, which you got when you installed Blender 2.5
  3. Then get the Python Setup Tools.. Installing that gives you an easy_install executable in your Python/scripts folder.
  4. 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 makes reMarkup text. To prepare this set of input files, from your SVNroot Blender/trunk folder, every time you update from svn, run

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

Note that you must run blender 2.50, as the py script uses py31. This command will create a folder ./source/blender/python/doc/sphinx-in. This folder contains a bunch of up-to-date rst files. Then, to make the documentation, from that same folder run

sphinx-build source/blender/python/doc/sphinx-in source/blender/python/doc/sphinx-out

Note that sphinx-build.exe may not be on your path, so you have to qualify it via "c:\program files\blender foundation\python\scripts\sphinx-build" or some such nonsense as you had to above with easy_install. Worst case, use my little batch file and run the script via

"c:\program files\blender foundation\250\blender" --background --python ./source/blender/python/doc/sphinx_doc_gen.py 
"c:\program files\blender foundation\python\scripts\sphinx-build-script.py" ./source/blender/python/doc/sphinx-in ./source/blender/python/doc/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.50 in a subfolder 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!