tmaq
/
tornavis
1
0
Fork 0
Code Issues 2 Pull Requests 29 Packages Projects 24 Releases Wiki Activity
tornavis/source/blender/python/doc/sphinx_doc_gen.py

863 lines
29 KiB
Python
Raw Normal View History

sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
# ***** BEGIN GPL LICENSE BLOCK *****
#
# This program is free software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License
# as published by the Free Software Foundation; either version 2
# of the License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software Foundation,
correct fsf address
2010-02-12 14:34:04 +01:00
# Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
#
# Contributor(s): Campbell Barton
#
# #**** END GPL LICENSE BLOCK #****
script_help_msg = '''
Usage,
run this script from blenders root path once you have compiled blender
Mathutils doc improvements + other small things - bpy.app moved into PyStructSequence (used by sys.float_info) - added buildinfo into bpy.app.build_* - bpy.ui removed (wasnt used) - include external example files in Mathutils docs (only Mathutils and Vector are currently written) - added support to auto document PyStructSequence's - CMake had "'s inside all its strings.
2010-01-31 22:52:26 +01:00
./blender.bin -b -P /b/source/blender/python/doc/sphinx_doc_gen.py
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
write our to a shorter path, was failing unless you made the path manually since it was trying to write to a subsub dir that didnt exist.
2010-01-06 10:42:41 +01:00
This will generate python files in "./source/blender/python/doc/sphinx-in"
== python api docs == * source/blender/python/doc/sphinx_doc_gen.py: changed the "undocumented" message so that it still links to http://wiki.blender.org/index.php/Dev:2.5/Py/API/Documentation/Contribute but uses flags in the url to help documenting. Example: http://www.blender.org/documentation/250PythonDoc/bpy.ops.node.html#bpy.ops.node.link click on "contribute", the new section has title "bpy.ops.node.link" and a howto message is shown * source/blender/python/intern/bpy.c: fixed a typo
2010-06-15 04:06:01 +02:00
Generate html docs by running...
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
write our to a shorter path, was failing unless you made the path manually since it was trying to write to a subsub dir that didnt exist.
2010-01-06 10:42:41 +01:00
sphinx-build source/blender/python/doc/sphinx-in source/blender/python/doc/sphinx-out
minor changes needed for PDF generation
2010-01-28 11:48:17 +01:00
For PDF generation
sphinx-build -b latex source/blender/python/doc/sphinx-in source/blender/python/doc/sphinx-out
cd source/blender/python/doc/sphinx-out
make
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
'''
== Sphinx Doc Gen == Workaround to address attribute description issue. In resulting .rst file attribute's descriptions appeared not indented which sphinx considered as anoter blocks.
2010-05-30 02:24:32 +02:00
# import rpdb2; rpdb2.start_embedded_debugger('test')
Mathutils refactor & include in sphinx generated docs, (TODO, include getset'ers in docs) - Mathutils.MidpointVecs --> vector.lerp(other, fac) - Mathutils.AngleBetweenVecs --> vector.angle(other) - Mathutils.ProjectVecs --> vector.project(other) - Mathutils.DifferenceQuats --> quat.difference(other) - Mathutils.Slerp --> quat.slerp(other, fac) - Mathutils.Rand: removed, use pythons random module - Mathutils.RotationMatrix(angle, size, axis_flag, axis) --> Mathutils.RotationMatrix(angle, size, axis); merge axis & axis_flag args - Matrix.scalePart --> Matrix.scale_part - Matrix.translationPart --> Matrix.translation_part - Matrix.rotationPart --> Matrix.rotation_part - toMatrix --> to_matrix - toEuler --> to_euler - toQuat --> to_quat - Vector.toTrackQuat --> Vector.to_track_quat
2010-01-25 10:44:04 +01:00
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
import os
* sphinx docgen * py_function_args wasnt working right (was using function namespace for function args), use pythons inspect module instead. move the function to get a type description into rna_info
2009-12-26 17:47:25 +01:00
import inspect
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
import bpy
import rna_info
reload(rna_info)
document bpy.types.Struct methods C methods, currently only keyframe_delete() and keyframe_insert() have useful docstrings. http://www.blender.org/documentation/250PythonDoc/bpy.types.Struct.html?highlight=bpy.types.struct#bpy.types.Struct.keyframe_insert
2010-04-06 00:37:09 +02:00
# lame, python wont give some access
add support for documenting class methods
2010-08-11 19:13:39 +02:00
ClassMethodDescriptorType = type(dict.__dict__['fromkeys'])
document bpy.types.Struct methods C methods, currently only keyframe_delete() and keyframe_insert() have useful docstrings. http://www.blender.org/documentation/250PythonDoc/bpy.types.Struct.html?highlight=bpy.types.struct#bpy.types.Struct.keyframe_insert
2010-04-06 00:37:09 +02:00
MethodDescriptorType = type(dict.get)
GetSetDescriptorType = type(int.real)
examples for autogenerated docs are now implicit and used when available. This means adding the file "bpy.props.py" in the examples dir will automatically be used when generating docs, unused examples give warnings.
2010-02-28 14:45:08 +01:00
EXAMPLE_SET = set()
EXAMPLE_SET_USED = set()
rna/py/reference doc improvements.. - vectors now respect min/max settings. - keyframing and adding drivers raises an error in an index is set on a non array, keyframing raises an error if it fails. reference docs... - added docstrings for remaining python bpy_struct functions - added fake class for docs, bpy_struct, which is the base class of everything in bpy.types - improved inherictance references for struct classes, include bpy_struct members.
2010-04-10 20:35:50 +02:00
_BPY_STRUCT_FAKE = "bpy_struct"
sphinx doc generation - include default values as well as min/max. - partial rebuilds, so we dont have to build all docs each time, only the changed files.
2010-05-03 17:52:15 +02:00
_BPY_FULL_REBUILD = False
rna/py/reference doc improvements.. - vectors now respect min/max settings. - keyframing and adding drivers raises an error in an index is set on a non array, keyframing raises an error if it fails. reference docs... - added docstrings for remaining python bpy_struct functions - added fake class for docs, bpy_struct, which is the base class of everything in bpy.types - improved inherictance references for struct classes, include bpy_struct members.
2010-04-10 20:35:50 +02:00
== python api docs == * source/blender/python/doc/sphinx_doc_gen.py: changed the "undocumented" message so that it still links to http://wiki.blender.org/index.php/Dev:2.5/Py/API/Documentation/Contribute but uses flags in the url to help documenting. Example: http://www.blender.org/documentation/250PythonDoc/bpy.ops.node.html#bpy.ops.node.link click on "contribute", the new section has title "bpy.ops.node.link" and a howto message is shown * source/blender/python/intern/bpy.c: fixed a typo
2010-06-15 04:06:01 +02:00
def undocumented_message(module_name, type_name, identifier):
message = "Undocumented (`contribute " \
"<http://wiki.blender.org/index.php/Dev:2.5/Py/API/Documentation/Contribute" \
== addons == - release/scripts/ui/space_userpref.py added the change to add a 'warning' field to bl_addon_info warning icons are used to show 'broken' scripts or warnings asked permission to campbell and matt in blendercoders to apply this - source/blender/python/doc/sphinx_doc_gen.py: small fix in the url
2010-06-17 04:38:49 +02:00
"?action=edit&section=new&preload=Dev:2.5/Py/API/Documentation/Contribute/Howto-message" \
== python api docs == * source/blender/python/doc/sphinx_doc_gen.py: changed the "undocumented" message so that it still links to http://wiki.blender.org/index.php/Dev:2.5/Py/API/Documentation/Contribute but uses flags in the url to help documenting. Example: http://www.blender.org/documentation/250PythonDoc/bpy.ops.node.html#bpy.ops.node.link click on "contribute", the new section has title "bpy.ops.node.link" and a howto message is shown * source/blender/python/intern/bpy.c: fixed a typo
2010-06-15 04:06:01 +02:00
"&preloadtitle=%s.%s.%s>`_)\n\n" % (module_name, type_name, identifier)
return message
== python api docs == * source/gameengine/PyDoc/bge.types.rst: KX_PolygonMaterial was missing the parent class indication (PyObjectPlus) * source/blender/python/doc/sphinx_doc_gen.py: * unified all the "undocumented" descriptions, like http://www.blender.org/documentation/250PythonDoc/bpy.ops.anim.html#bpy.ops.anim.keyframe_delete_button so that it will be easy for Alex to CCS 'em and also now people will have a link to contribute descriptions, see http://wiki.blender.org/index.php/Dev:2.5/Py/API/Documentation/Contribute * moved the note about bpy_struct not being available in the api in a proper note directive, so that it's more evident (I didn't see it at first)
2010-06-12 00:41:13 +02:00
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
def range_str(val):
== python api docs == * source/blender/python/doc/sphinx_doc_gen.py: changed the "undocumented" message so that it still links to http://wiki.blender.org/index.php/Dev:2.5/Py/API/Documentation/Contribute but uses flags in the url to help documenting. Example: http://www.blender.org/documentation/250PythonDoc/bpy.ops.node.html#bpy.ops.node.link click on "contribute", the new section has title "bpy.ops.node.link" and a howto message is shown * source/blender/python/intern/bpy.c: fixed a typo
2010-06-15 04:06:01 +02:00
'''
Converts values to strings for the range directive.
(unused function it seems)
'''
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
if val < -10000000: return '-inf'
if val > 10000000: return 'inf'
if type(val)==float:
return '%g' % val
else:
return str(val)
examples for autogenerated docs are now implicit and used when available. This means adding the file "bpy.props.py" in the examples dir will automatically be used when generating docs, unused examples give warnings.
2010-02-28 14:45:08 +01:00
== python api docs == * source/blender/python/doc/sphinx_doc_gen.py: changed the "undocumented" message so that it still links to http://wiki.blender.org/index.php/Dev:2.5/Py/API/Documentation/Contribute but uses flags in the url to help documenting. Example: http://www.blender.org/documentation/250PythonDoc/bpy.ops.node.html#bpy.ops.node.link click on "contribute", the new section has title "bpy.ops.node.link" and a howto message is shown * source/blender/python/intern/bpy.c: fixed a typo
2010-06-15 04:06:01 +02:00
def write_example_ref(ident, fw, example_id, ext="py"):
examples for autogenerated docs are now implicit and used when available. This means adding the file "bpy.props.py" in the examples dir will automatically be used when generating docs, unused examples give warnings.
2010-02-28 14:45:08 +01:00
if example_id in EXAMPLE_SET:
== python api docs == * source/blender/python/doc/sphinx_doc_gen.py: changed the "undocumented" message so that it still links to http://wiki.blender.org/index.php/Dev:2.5/Py/API/Documentation/Contribute but uses flags in the url to help documenting. Example: http://www.blender.org/documentation/250PythonDoc/bpy.ops.node.html#bpy.ops.node.link click on "contribute", the new section has title "bpy.ops.node.link" and a howto message is shown * source/blender/python/intern/bpy.c: fixed a typo
2010-06-15 04:06:01 +02:00
fw("%s.. literalinclude:: ../examples/%s.%s\n\n" % (ident, example_id, ext))
examples for autogenerated docs are now implicit and used when available. This means adding the file "bpy.props.py" in the examples dir will automatically be used when generating docs, unused examples give warnings.
2010-02-28 14:45:08 +01:00
EXAMPLE_SET_USED.add(example_id)
else:
if bpy.app.debug:
print("\tskipping example:", example_id)
Mathutils doc improvements + other small things - bpy.app moved into PyStructSequence (used by sys.float_info) - added buildinfo into bpy.app.build_* - bpy.ui removed (wasnt used) - include external example files in Mathutils docs (only Mathutils and Vector are currently written) - added support to auto document PyStructSequence's - CMake had "'s inside all its strings.
2010-01-31 22:52:26 +01:00
def write_indented_lines(ident, fn, text, strip=True):
== python api docs == * source/blender/python/doc/sphinx_doc_gen.py: changed the "undocumented" message so that it still links to http://wiki.blender.org/index.php/Dev:2.5/Py/API/Documentation/Contribute but uses flags in the url to help documenting. Example: http://www.blender.org/documentation/250PythonDoc/bpy.ops.node.html#bpy.ops.node.link click on "contribute", the new section has title "bpy.ops.node.link" and a howto message is shown * source/blender/python/intern/bpy.c: fixed a typo
2010-06-15 04:06:01 +02:00
'''
Apply same indentation to all lines in a multilines text.
'''
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
if text is None:
return
for l in text.split("\n"):
Mathutils doc improvements + other small things - bpy.app moved into PyStructSequence (used by sys.float_info) - added buildinfo into bpy.app.build_* - bpy.ui removed (wasnt used) - include external example files in Mathutils docs (only Mathutils and Vector are currently written) - added support to auto document PyStructSequence's - CMake had "'s inside all its strings.
2010-01-31 22:52:26 +01:00
if strip:
fn(ident + l.strip() + "\n")
else:
fn(ident + l + "\n")
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
initial sphinx doc generation support for python and C modules. python modules bpy.app, bpy.utils are now included in docs. C defined python module bpy.props has its docstrings extracted and written directly into sphinx docs since the C methods cant be inspected. added docstrings to bpy.props and improved some in bpy.utils. will update online docs tomorrow.
2010-01-22 03:04:25 +01:00
def pymethod2sphinx(ident, fw, identifier, py_func):
'''
class method to sphinx
'''
arg_str = inspect.formatargspec(*inspect.getargspec(py_func))
if arg_str.startswith("(self, "):
arg_str = "(" + arg_str[7:]
func_type = "method"
elif arg_str.startswith("(cls, "):
arg_str = "(" + arg_str[6:]
func_type = "classmethod"
else:
func_type = "staticmethod"
fw(ident + ".. %s:: %s%s\n\n" % (func_type, identifier, arg_str))
if py_func.__doc__:
write_indented_lines(ident + " ", fw, py_func.__doc__)
fw("\n")
def pyfunc2sphinx(ident, fw, identifier, py_func, is_class=True):
'''
function or class method to sphinx
'''
arg_str = inspect.formatargspec(*inspect.getargspec(py_func))
if not is_class:
func_type = "function"
# ther rest are class methods
elif arg_str.startswith("(self, "):
arg_str = "(" + arg_str[7:]
func_type = "method"
elif arg_str.startswith("(cls, "):
arg_str = "(" + arg_str[6:]
func_type = "classmethod"
else:
func_type = "staticmethod"
fw(ident + ".. %s:: %s%s\n\n" % (func_type, identifier, arg_str))
if py_func.__doc__:
write_indented_lines(ident + " ", fw, py_func.__doc__.strip())
fw("\n")
rna/py/reference doc improvements.. - vectors now respect min/max settings. - keyframing and adding drivers raises an error in an index is set on a non array, keyframing raises an error if it fails. reference docs... - added docstrings for remaining python bpy_struct functions - added fake class for docs, bpy_struct, which is the base class of everything in bpy.types - improved inherictance references for struct classes, include bpy_struct members.
2010-04-10 20:35:50 +02:00
def py_descr2sphinx(ident, fw, descr, module_name, type_name, identifier):
Minor sphinx corrections: * Attributes starting with _ in classes are now ignored * sphinx.blend updated so that it doesn't have to be edited anymore if the script changes
2010-07-19 15:36:10 +02:00
if identifier.startswith("_"):
return
rna/py/reference doc improvements.. - vectors now respect min/max settings. - keyframing and adding drivers raises an error in an index is set on a non array, keyframing raises an error if it fails. reference docs... - added docstrings for remaining python bpy_struct functions - added fake class for docs, bpy_struct, which is the base class of everything in bpy.types - improved inherictance references for struct classes, include bpy_struct members.
2010-04-10 20:35:50 +02:00
doc = descr.__doc__
if not doc:
== python api docs == * source/blender/python/doc/sphinx_doc_gen.py: changed the "undocumented" message so that it still links to http://wiki.blender.org/index.php/Dev:2.5/Py/API/Documentation/Contribute but uses flags in the url to help documenting. Example: http://www.blender.org/documentation/250PythonDoc/bpy.ops.node.html#bpy.ops.node.link click on "contribute", the new section has title "bpy.ops.node.link" and a howto message is shown * source/blender/python/intern/bpy.c: fixed a typo
2010-06-15 04:06:01 +02:00
doc = undocumented_message(module_name, type_name, identifier)
rna/py/reference doc improvements.. - vectors now respect min/max settings. - keyframing and adding drivers raises an error in an index is set on a non array, keyframing raises an error if it fails. reference docs... - added docstrings for remaining python bpy_struct functions - added fake class for docs, bpy_struct, which is the base class of everything in bpy.types - improved inherictance references for struct classes, include bpy_struct members.
2010-04-10 20:35:50 +02:00
if type(descr) == GetSetDescriptorType:
fw(ident + ".. attribute:: %s\n\n" % identifier)
== Sphinx Doc Gen == Workaround to address attribute description issue. In resulting .rst file attribute's descriptions appeared not indented which sphinx considered as anoter blocks.
2010-05-30 02:24:32 +02:00
write_indented_lines(ident + " ", fw, doc, False)
add support for documenting class methods
2010-08-11 19:13:39 +02:00
elif type(descr) in (MethodDescriptorType, ClassMethodDescriptorType):
rna/py/reference doc improvements.. - vectors now respect min/max settings. - keyframing and adding drivers raises an error in an index is set on a non array, keyframing raises an error if it fails. reference docs... - added docstrings for remaining python bpy_struct functions - added fake class for docs, bpy_struct, which is the base class of everything in bpy.types - improved inherictance references for struct classes, include bpy_struct members.
2010-04-10 20:35:50 +02:00
write_indented_lines(ident, fw, doc, False)
else:
add support for documenting class methods
2010-08-11 19:13:39 +02:00
raise TypeError("type was not GetSetDescriptorType, MethodDescriptorType or ClassMethodDescriptorType")
rna/py/reference doc improvements.. - vectors now respect min/max settings. - keyframing and adding drivers raises an error in an index is set on a non array, keyframing raises an error if it fails. reference docs... - added docstrings for remaining python bpy_struct functions - added fake class for docs, bpy_struct, which is the base class of everything in bpy.types - improved inherictance references for struct classes, include bpy_struct members.
2010-04-10 20:35:50 +02:00
write_example_ref(ident, fw, module_name + "." + type_name + "." + identifier)
fw("\n")
== python api docs == * source/blender/python/doc/sphinx_doc_gen.py: changed the "undocumented" message so that it still links to http://wiki.blender.org/index.php/Dev:2.5/Py/API/Documentation/Contribute but uses flags in the url to help documenting. Example: http://www.blender.org/documentation/250PythonDoc/bpy.ops.node.html#bpy.ops.node.link click on "contribute", the new section has title "bpy.ops.node.link" and a howto message is shown * source/blender/python/intern/bpy.c: fixed a typo
2010-06-15 04:06:01 +02:00
def py_c_func2sphinx(ident, fw, module_name, type_name, identifier, py_func, is_class=True):
initial sphinx doc generation support for python and C modules. python modules bpy.app, bpy.utils are now included in docs. C defined python module bpy.props has its docstrings extracted and written directly into sphinx docs since the C methods cant be inspected. added docstrings to bpy.props and improved some in bpy.utils. will update online docs tomorrow.
2010-01-22 03:04:25 +01:00
'''
c defined function to sphinx.
'''
# dump the docstring, assume its formatted correctly
if py_func.__doc__:
Mathutils doc improvements + other small things - bpy.app moved into PyStructSequence (used by sys.float_info) - added buildinfo into bpy.app.build_* - bpy.ui removed (wasnt used) - include external example files in Mathutils docs (only Mathutils and Vector are currently written) - added support to auto document PyStructSequence's - CMake had "'s inside all its strings.
2010-01-31 22:52:26 +01:00
write_indented_lines(ident, fw, py_func.__doc__, False)
initial sphinx doc generation support for python and C modules. python modules bpy.app, bpy.utils are now included in docs. C defined python module bpy.props has its docstrings extracted and written directly into sphinx docs since the C methods cant be inspected. added docstrings to bpy.props and improved some in bpy.utils. will update online docs tomorrow.
2010-01-22 03:04:25 +01:00
fw("\n")
else:
fw(ident + ".. function:: %s()\n\n" % identifier)
== python api docs == * source/blender/python/doc/sphinx_doc_gen.py: changed the "undocumented" message so that it still links to http://wiki.blender.org/index.php/Dev:2.5/Py/API/Documentation/Contribute but uses flags in the url to help documenting. Example: http://www.blender.org/documentation/250PythonDoc/bpy.ops.node.html#bpy.ops.node.link click on "contribute", the new section has title "bpy.ops.node.link" and a howto message is shown * source/blender/python/intern/bpy.c: fixed a typo
2010-06-15 04:06:01 +02:00
fw(ident + " " + undocumented_message(module_name, type_name, identifier))
initial sphinx doc generation support for python and C modules. python modules bpy.app, bpy.utils are now included in docs. C defined python module bpy.props has its docstrings extracted and written directly into sphinx docs since the C methods cant be inspected. added docstrings to bpy.props and improved some in bpy.utils. will update online docs tomorrow.
2010-01-22 03:04:25 +01:00
def pyprop2sphinx(ident, fw, identifier, py_prop):
'''
python property to sphinx
'''
== python api docs == - properties are now listed on alphabetical order - readonly properties use "data" directive, so that we see them in green in the web docs example (after Campbell will rebuild the docs): http://www.blender.org/documentation/250PythonDoc/bpy.types.RenderLayer.html (note that green attributes still need final CSS-ing, but smerch is a bit busy atm) - fixed indentation in http://www.blender.org/documentation/250PythonDoc/bpy.data.html
2010-06-28 02:06:23 +02:00
# readonly properties use "data" directive, variables use "attribute" directive
if py_prop.fset is None:
fw(ident + ".. data:: %s\n\n" % identifier)
else:
fw(ident + ".. attribute:: %s\n\n" % identifier)
initial sphinx doc generation support for python and C modules. python modules bpy.app, bpy.utils are now included in docs. C defined python module bpy.props has its docstrings extracted and written directly into sphinx docs since the C methods cant be inspected. added docstrings to bpy.props and improved some in bpy.utils. will update online docs tomorrow.
2010-01-22 03:04:25 +01:00
write_indented_lines(ident + " ", fw, py_prop.__doc__)
if py_prop.fset is None:
fw(ident + " (readonly)\n\n")
def pymodule2sphinx(BASEPATH, module_name, module, title):
import types
bpy.app was writing members more then once.
2010-04-10 21:06:18 +02:00
attribute_set = set()
initial sphinx doc generation support for python and C modules. python modules bpy.app, bpy.utils are now included in docs. C defined python module bpy.props has its docstrings extracted and written directly into sphinx docs since the C methods cant be inspected. added docstrings to bpy.props and improved some in bpy.utils. will update online docs tomorrow.
2010-01-22 03:04:25 +01:00
filepath = os.path.join(BASEPATH, module_name + ".rst")
file = open(filepath, "w")
* Mathutils attributes documented - http://www.blender.org/documentation/250PythonDoc/Mathutils.html * Vector.difference() needed normalized vectors * bpy.DEUBG -> bpy.app.debug
2010-01-27 22:33:39 +01:00
initial sphinx doc generation support for python and C modules. python modules bpy.app, bpy.utils are now included in docs. C defined python module bpy.props has its docstrings extracted and written directly into sphinx docs since the C methods cant be inspected. added docstrings to bpy.props and improved some in bpy.utils. will update online docs tomorrow.
2010-01-22 03:04:25 +01:00
fw = file.write
fw(title + "\n")
fw(("=" * len(title)) + "\n\n")
fw(".. module:: %s\n\n" % module_name)
if module.__doc__:
# Note, may contain sphinx syntax, dont mangle!
fw(module.__doc__.strip())
fw("\n\n")
examples for autogenerated docs are now implicit and used when available. This means adding the file "bpy.props.py" in the examples dir will automatically be used when generating docs, unused examples give warnings.
2010-02-28 14:45:08 +01:00
write_example_ref("", fw, module_name)
Mathutils refactor & include in sphinx generated docs, (TODO, include getset'ers in docs) - Mathutils.MidpointVecs --> vector.lerp(other, fac) - Mathutils.AngleBetweenVecs --> vector.angle(other) - Mathutils.ProjectVecs --> vector.project(other) - Mathutils.DifferenceQuats --> quat.difference(other) - Mathutils.Slerp --> quat.slerp(other, fac) - Mathutils.Rand: removed, use pythons random module - Mathutils.RotationMatrix(angle, size, axis_flag, axis) --> Mathutils.RotationMatrix(angle, size, axis); merge axis & axis_flag args - Matrix.scalePart --> Matrix.scale_part - Matrix.translationPart --> Matrix.translation_part - Matrix.rotationPart --> Matrix.rotation_part - toMatrix --> to_matrix - toEuler --> to_euler - toQuat --> to_quat - Vector.toTrackQuat --> Vector.to_track_quat
2010-01-25 10:44:04 +01:00
Mathutils doc improvements + other small things - bpy.app moved into PyStructSequence (used by sys.float_info) - added buildinfo into bpy.app.build_* - bpy.ui removed (wasnt used) - include external example files in Mathutils docs (only Mathutils and Vector are currently written) - added support to auto document PyStructSequence's - CMake had "'s inside all its strings.
2010-01-31 22:52:26 +01:00
# write members of the module
# only tested with PyStructs which are not exactly modules
rna/py/reference doc improvements.. - vectors now respect min/max settings. - keyframing and adding drivers raises an error in an index is set on a non array, keyframing raises an error if it fails. reference docs... - added docstrings for remaining python bpy_struct functions - added fake class for docs, bpy_struct, which is the base class of everything in bpy.types - improved inherictance references for struct classes, include bpy_struct members.
2010-04-10 20:35:50 +02:00
for key, descr in sorted(type(module).__dict__.items()):
Mathutils doc improvements + other small things - bpy.app moved into PyStructSequence (used by sys.float_info) - added buildinfo into bpy.app.build_* - bpy.ui removed (wasnt used) - include external example files in Mathutils docs (only Mathutils and Vector are currently written) - added support to auto document PyStructSequence's - CMake had "'s inside all its strings.
2010-01-31 22:52:26 +01:00
if type(descr) == types.MemberDescriptorType:
if descr.__doc__:
rna/py/reference doc improvements.. - vectors now respect min/max settings. - keyframing and adding drivers raises an error in an index is set on a non array, keyframing raises an error if it fails. reference docs... - added docstrings for remaining python bpy_struct functions - added fake class for docs, bpy_struct, which is the base class of everything in bpy.types - improved inherictance references for struct classes, include bpy_struct members.
2010-04-10 20:35:50 +02:00
fw(".. data:: %s\n\n" % key)
Mathutils doc improvements + other small things - bpy.app moved into PyStructSequence (used by sys.float_info) - added buildinfo into bpy.app.build_* - bpy.ui removed (wasnt used) - include external example files in Mathutils docs (only Mathutils and Vector are currently written) - added support to auto document PyStructSequence's - CMake had "'s inside all its strings.
2010-01-31 22:52:26 +01:00
write_indented_lines(" ", fw, descr.__doc__, False)
bpy.app was writing members more then once.
2010-04-10 21:06:18 +02:00
attribute_set.add(key)
Mathutils doc improvements + other small things - bpy.app moved into PyStructSequence (used by sys.float_info) - added buildinfo into bpy.app.build_* - bpy.ui removed (wasnt used) - include external example files in Mathutils docs (only Mathutils and Vector are currently written) - added support to auto document PyStructSequence's - CMake had "'s inside all its strings.
2010-01-31 22:52:26 +01:00
fw("\n")
bpy.app was writing members more then once.
2010-04-10 21:06:18 +02:00
del key, descr
Mathutils doc improvements + other small things - bpy.app moved into PyStructSequence (used by sys.float_info) - added buildinfo into bpy.app.build_* - bpy.ui removed (wasnt used) - include external example files in Mathutils docs (only Mathutils and Vector are currently written) - added support to auto document PyStructSequence's - CMake had "'s inside all its strings.
2010-01-31 22:52:26 +01:00
Mathutils refactor & include in sphinx generated docs, (TODO, include getset'ers in docs) - Mathutils.MidpointVecs --> vector.lerp(other, fac) - Mathutils.AngleBetweenVecs --> vector.angle(other) - Mathutils.ProjectVecs --> vector.project(other) - Mathutils.DifferenceQuats --> quat.difference(other) - Mathutils.Slerp --> quat.slerp(other, fac) - Mathutils.Rand: removed, use pythons random module - Mathutils.RotationMatrix(angle, size, axis_flag, axis) --> Mathutils.RotationMatrix(angle, size, axis); merge axis & axis_flag args - Matrix.scalePart --> Matrix.scale_part - Matrix.translationPart --> Matrix.translation_part - Matrix.rotationPart --> Matrix.rotation_part - toMatrix --> to_matrix - toEuler --> to_euler - toQuat --> to_quat - Vector.toTrackQuat --> Vector.to_track_quat
2010-01-25 10:44:04 +01:00
classes = []
initial sphinx doc generation support for python and C modules. python modules bpy.app, bpy.utils are now included in docs. C defined python module bpy.props has its docstrings extracted and written directly into sphinx docs since the C methods cant be inspected. added docstrings to bpy.props and improved some in bpy.utils. will update online docs tomorrow.
2010-01-22 03:04:25 +01:00
document bpy.types.Struct methods C methods, currently only keyframe_delete() and keyframe_insert() have useful docstrings. http://www.blender.org/documentation/250PythonDoc/bpy.types.Struct.html?highlight=bpy.types.struct#bpy.types.Struct.keyframe_insert
2010-04-06 00:37:09 +02:00
for attribute in sorted(dir(module)):
initial sphinx doc generation support for python and C modules. python modules bpy.app, bpy.utils are now included in docs. C defined python module bpy.props has its docstrings extracted and written directly into sphinx docs since the C methods cant be inspected. added docstrings to bpy.props and improved some in bpy.utils. will update online docs tomorrow.
2010-01-22 03:04:25 +01:00
if not attribute.startswith("_"):
bpy.app was writing members more then once.
2010-04-10 21:06:18 +02:00
if attribute in attribute_set:
continue
if attribute.startswith("n_"): # annoying exception, needed for bpy.app
continue
initial sphinx doc generation support for python and C modules. python modules bpy.app, bpy.utils are now included in docs. C defined python module bpy.props has its docstrings extracted and written directly into sphinx docs since the C methods cant be inspected. added docstrings to bpy.props and improved some in bpy.utils. will update online docs tomorrow.
2010-01-22 03:04:25 +01:00
value = getattr(module, attribute)
value_type = type(value)
Mathutils refactor & include in sphinx generated docs, (TODO, include getset'ers in docs) - Mathutils.MidpointVecs --> vector.lerp(other, fac) - Mathutils.AngleBetweenVecs --> vector.angle(other) - Mathutils.ProjectVecs --> vector.project(other) - Mathutils.DifferenceQuats --> quat.difference(other) - Mathutils.Slerp --> quat.slerp(other, fac) - Mathutils.Rand: removed, use pythons random module - Mathutils.RotationMatrix(angle, size, axis_flag, axis) --> Mathutils.RotationMatrix(angle, size, axis); merge axis & axis_flag args - Matrix.scalePart --> Matrix.scale_part - Matrix.translationPart --> Matrix.translation_part - Matrix.rotationPart --> Matrix.rotation_part - toMatrix --> to_matrix - toEuler --> to_euler - toQuat --> to_quat - Vector.toTrackQuat --> Vector.to_track_quat
2010-01-25 10:44:04 +01:00
initial sphinx doc generation support for python and C modules. python modules bpy.app, bpy.utils are now included in docs. C defined python module bpy.props has its docstrings extracted and written directly into sphinx docs since the C methods cant be inspected. added docstrings to bpy.props and improved some in bpy.utils. will update online docs tomorrow.
2010-01-22 03:04:25 +01:00
if value_type == types.FunctionType:
pyfunc2sphinx("", fw, attribute, value, is_class=False)
elif value_type in (types.BuiltinMethodType, types.BuiltinFunctionType): # both the same at the moment but to be future proof
# note: can't get args from these, so dump the string as is
# this means any module used like this must have fully formatted docstrings.
== python api docs == * source/blender/python/doc/sphinx_doc_gen.py: changed the "undocumented" message so that it still links to http://wiki.blender.org/index.php/Dev:2.5/Py/API/Documentation/Contribute but uses flags in the url to help documenting. Example: http://www.blender.org/documentation/250PythonDoc/bpy.ops.node.html#bpy.ops.node.link click on "contribute", the new section has title "bpy.ops.node.link" and a howto message is shown * source/blender/python/intern/bpy.c: fixed a typo
2010-06-15 04:06:01 +02:00
py_c_func2sphinx("", fw, module_name, module, attribute, value, is_class=False)
Mathutils refactor & include in sphinx generated docs, (TODO, include getset'ers in docs) - Mathutils.MidpointVecs --> vector.lerp(other, fac) - Mathutils.AngleBetweenVecs --> vector.angle(other) - Mathutils.ProjectVecs --> vector.project(other) - Mathutils.DifferenceQuats --> quat.difference(other) - Mathutils.Slerp --> quat.slerp(other, fac) - Mathutils.Rand: removed, use pythons random module - Mathutils.RotationMatrix(angle, size, axis_flag, axis) --> Mathutils.RotationMatrix(angle, size, axis); merge axis & axis_flag args - Matrix.scalePart --> Matrix.scale_part - Matrix.translationPart --> Matrix.translation_part - Matrix.rotationPart --> Matrix.rotation_part - toMatrix --> to_matrix - toEuler --> to_euler - toQuat --> to_quat - Vector.toTrackQuat --> Vector.to_track_quat
2010-01-25 10:44:04 +01:00
elif value_type == type:
classes.append((attribute, value))
document bpy.types.Struct methods C methods, currently only keyframe_delete() and keyframe_insert() have useful docstrings. http://www.blender.org/documentation/250PythonDoc/bpy.types.Struct.html?highlight=bpy.types.struct#bpy.types.Struct.keyframe_insert
2010-04-06 00:37:09 +02:00
elif value_type in (bool, int, float, str, tuple):
# constant, not much fun we can do here except to list it.
# TODO, figure out some way to document these!
fw(".. data:: %s\n\n" % attribute)
write_indented_lines(" ", fw, "constant value %s" % repr(value), False)
fw("\n")
else:
print("\tnot documenting %s.%s" % (module_name, attribute))
bpy.app was writing members more then once.
2010-04-10 21:06:18 +02:00
continue
attribute_set.add(attribute)
initial sphinx doc generation support for python and C modules. python modules bpy.app, bpy.utils are now included in docs. C defined python module bpy.props has its docstrings extracted and written directly into sphinx docs since the C methods cant be inspected. added docstrings to bpy.props and improved some in bpy.utils. will update online docs tomorrow.
2010-01-22 03:04:25 +01:00
# TODO, more types...
rna/py/reference doc improvements.. - vectors now respect min/max settings. - keyframing and adding drivers raises an error in an index is set on a non array, keyframing raises an error if it fails. reference docs... - added docstrings for remaining python bpy_struct functions - added fake class for docs, bpy_struct, which is the base class of everything in bpy.types - improved inherictance references for struct classes, include bpy_struct members.
2010-04-10 20:35:50 +02:00
Mathutils refactor & include in sphinx generated docs, (TODO, include getset'ers in docs) - Mathutils.MidpointVecs --> vector.lerp(other, fac) - Mathutils.AngleBetweenVecs --> vector.angle(other) - Mathutils.ProjectVecs --> vector.project(other) - Mathutils.DifferenceQuats --> quat.difference(other) - Mathutils.Slerp --> quat.slerp(other, fac) - Mathutils.Rand: removed, use pythons random module - Mathutils.RotationMatrix(angle, size, axis_flag, axis) --> Mathutils.RotationMatrix(angle, size, axis); merge axis & axis_flag args - Matrix.scalePart --> Matrix.scale_part - Matrix.translationPart --> Matrix.translation_part - Matrix.rotationPart --> Matrix.rotation_part - toMatrix --> to_matrix - toEuler --> to_euler - toQuat --> to_quat - Vector.toTrackQuat --> Vector.to_track_quat
2010-01-25 10:44:04 +01:00
# write collected classes now
rna/py/reference doc improvements.. - vectors now respect min/max settings. - keyframing and adding drivers raises an error in an index is set on a non array, keyframing raises an error if it fails. reference docs... - added docstrings for remaining python bpy_struct functions - added fake class for docs, bpy_struct, which is the base class of everything in bpy.types - improved inherictance references for struct classes, include bpy_struct members.
2010-04-10 20:35:50 +02:00
for (type_name, value) in classes:
Mathutils refactor & include in sphinx generated docs, (TODO, include getset'ers in docs) - Mathutils.MidpointVecs --> vector.lerp(other, fac) - Mathutils.AngleBetweenVecs --> vector.angle(other) - Mathutils.ProjectVecs --> vector.project(other) - Mathutils.DifferenceQuats --> quat.difference(other) - Mathutils.Slerp --> quat.slerp(other, fac) - Mathutils.Rand: removed, use pythons random module - Mathutils.RotationMatrix(angle, size, axis_flag, axis) --> Mathutils.RotationMatrix(angle, size, axis); merge axis & axis_flag args - Matrix.scalePart --> Matrix.scale_part - Matrix.translationPart --> Matrix.translation_part - Matrix.rotationPart --> Matrix.rotation_part - toMatrix --> to_matrix - toEuler --> to_euler - toQuat --> to_quat - Vector.toTrackQuat --> Vector.to_track_quat
2010-01-25 10:44:04 +01:00
# May need to be its own function
rna/py/reference doc improvements.. - vectors now respect min/max settings. - keyframing and adding drivers raises an error in an index is set on a non array, keyframing raises an error if it fails. reference docs... - added docstrings for remaining python bpy_struct functions - added fake class for docs, bpy_struct, which is the base class of everything in bpy.types - improved inherictance references for struct classes, include bpy_struct members.
2010-04-10 20:35:50 +02:00
fw(".. class:: %s\n\n" % type_name)
Mathutils refactor & include in sphinx generated docs, (TODO, include getset'ers in docs) - Mathutils.MidpointVecs --> vector.lerp(other, fac) - Mathutils.AngleBetweenVecs --> vector.angle(other) - Mathutils.ProjectVecs --> vector.project(other) - Mathutils.DifferenceQuats --> quat.difference(other) - Mathutils.Slerp --> quat.slerp(other, fac) - Mathutils.Rand: removed, use pythons random module - Mathutils.RotationMatrix(angle, size, axis_flag, axis) --> Mathutils.RotationMatrix(angle, size, axis); merge axis & axis_flag args - Matrix.scalePart --> Matrix.scale_part - Matrix.translationPart --> Matrix.translation_part - Matrix.rotationPart --> Matrix.rotation_part - toMatrix --> to_matrix - toEuler --> to_euler - toQuat --> to_quat - Vector.toTrackQuat --> Vector.to_track_quat
2010-01-25 10:44:04 +01:00
if value.__doc__:
Mathutils doc improvements + other small things - bpy.app moved into PyStructSequence (used by sys.float_info) - added buildinfo into bpy.app.build_* - bpy.ui removed (wasnt used) - include external example files in Mathutils docs (only Mathutils and Vector are currently written) - added support to auto document PyStructSequence's - CMake had "'s inside all its strings.
2010-01-31 22:52:26 +01:00
write_indented_lines(" ", fw, value.__doc__, False)
* Mathutils attributes documented - http://www.blender.org/documentation/250PythonDoc/Mathutils.html * Vector.difference() needed normalized vectors * bpy.DEUBG -> bpy.app.debug
2010-01-27 22:33:39 +01:00
fw("\n")
rna/py/reference doc improvements.. - vectors now respect min/max settings. - keyframing and adding drivers raises an error in an index is set on a non array, keyframing raises an error if it fails. reference docs... - added docstrings for remaining python bpy_struct functions - added fake class for docs, bpy_struct, which is the base class of everything in bpy.types - improved inherictance references for struct classes, include bpy_struct members.
2010-04-10 20:35:50 +02:00
write_example_ref(" ", fw, module_name + "." + type_name)
Mathutils refactor & include in sphinx generated docs, (TODO, include getset'ers in docs) - Mathutils.MidpointVecs --> vector.lerp(other, fac) - Mathutils.AngleBetweenVecs --> vector.angle(other) - Mathutils.ProjectVecs --> vector.project(other) - Mathutils.DifferenceQuats --> quat.difference(other) - Mathutils.Slerp --> quat.slerp(other, fac) - Mathutils.Rand: removed, use pythons random module - Mathutils.RotationMatrix(angle, size, axis_flag, axis) --> Mathutils.RotationMatrix(angle, size, axis); merge axis & axis_flag args - Matrix.scalePart --> Matrix.scale_part - Matrix.translationPart --> Matrix.translation_part - Matrix.rotationPart --> Matrix.rotation_part - toMatrix --> to_matrix - toEuler --> to_euler - toQuat --> to_quat - Vector.toTrackQuat --> Vector.to_track_quat
2010-01-25 10:44:04 +01:00
rna/py/reference doc improvements.. - vectors now respect min/max settings. - keyframing and adding drivers raises an error in an index is set on a non array, keyframing raises an error if it fails. reference docs... - added docstrings for remaining python bpy_struct functions - added fake class for docs, bpy_struct, which is the base class of everything in bpy.types - improved inherictance references for struct classes, include bpy_struct members.
2010-04-10 20:35:50 +02:00
descr_items = [(key, descr) for key, descr in sorted(value.__dict__.items()) if not key.startswith("__")]
add support for documenting class methods
2010-08-11 19:13:39 +02:00
for key, descr in descr_items:
- possibly bugfix /w uninitialized vars [#23270] Long directory name segmentation fault in File brower. - in exceptional cases vertcos_to_key() could return with KeyBlock pointing to freed memory. - invalid use of realloc() in BLI_builddir()
2010-08-12 00:36:43 +02:00
if type(descr) == ClassMethodDescriptorType:
add support for documenting class methods
2010-08-11 19:13:39 +02:00
py_descr2sphinx(" ", fw, descr, module_name, type_name, key)
rna/py/reference doc improvements.. - vectors now respect min/max settings. - keyframing and adding drivers raises an error in an index is set on a non array, keyframing raises an error if it fails. reference docs... - added docstrings for remaining python bpy_struct functions - added fake class for docs, bpy_struct, which is the base class of everything in bpy.types - improved inherictance references for struct classes, include bpy_struct members.
2010-04-10 20:35:50 +02:00
for key, descr in descr_items:
- possibly bugfix /w uninitialized vars [#23270] Long directory name segmentation fault in File brower. - in exceptional cases vertcos_to_key() could return with KeyBlock pointing to freed memory. - invalid use of realloc() in BLI_builddir()
2010-08-12 00:36:43 +02:00
if type(descr) == MethodDescriptorType:
rna/py/reference doc improvements.. - vectors now respect min/max settings. - keyframing and adding drivers raises an error in an index is set on a non array, keyframing raises an error if it fails. reference docs... - added docstrings for remaining python bpy_struct functions - added fake class for docs, bpy_struct, which is the base class of everything in bpy.types - improved inherictance references for struct classes, include bpy_struct members.
2010-04-10 20:35:50 +02:00
py_descr2sphinx(" ", fw, descr, module_name, type_name, key)
for key, descr in descr_items:
if type(descr) == GetSetDescriptorType:
py_descr2sphinx(" ", fw, descr, module_name, type_name, key)
Mathutils refactor & include in sphinx generated docs, (TODO, include getset'ers in docs) - Mathutils.MidpointVecs --> vector.lerp(other, fac) - Mathutils.AngleBetweenVecs --> vector.angle(other) - Mathutils.ProjectVecs --> vector.project(other) - Mathutils.DifferenceQuats --> quat.difference(other) - Mathutils.Slerp --> quat.slerp(other, fac) - Mathutils.Rand: removed, use pythons random module - Mathutils.RotationMatrix(angle, size, axis_flag, axis) --> Mathutils.RotationMatrix(angle, size, axis); merge axis & axis_flag args - Matrix.scalePart --> Matrix.scale_part - Matrix.translationPart --> Matrix.translation_part - Matrix.rotationPart --> Matrix.rotation_part - toMatrix --> to_matrix - toEuler --> to_euler - toQuat --> to_quat - Vector.toTrackQuat --> Vector.to_track_quat
2010-01-25 10:44:04 +01:00
fw("\n\n")
initial sphinx doc generation support for python and C modules. python modules bpy.app, bpy.utils are now included in docs. C defined python module bpy.props has its docstrings extracted and written directly into sphinx docs since the C methods cant be inspected. added docstrings to bpy.props and improved some in bpy.utils. will update online docs tomorrow.
2010-01-22 03:04:25 +01:00
file.close()
Mathutils doc improvements + other small things - bpy.app moved into PyStructSequence (used by sys.float_info) - added buildinfo into bpy.app.build_* - bpy.ui removed (wasnt used) - include external example files in Mathutils docs (only Mathutils and Vector are currently written) - added support to auto document PyStructSequence's - CMake had "'s inside all its strings.
2010-01-31 22:52:26 +01:00
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
def rna2sphinx(BASEPATH):
structs, funcs, ops, props = rna_info.BuildRNAInfo()
try:
os.mkdir(BASEPATH)
except:
pass
# conf.py - empty for now
filepath = os.path.join(BASEPATH, "conf.py")
file = open(filepath, "w")
fw = file.write
parts of the Python API are unstable, big discalmer in API docs main page, API Docs title and interactive console banner.
2010-03-01 11:34:54 +01:00
Mathutils doc improvements + other small things - bpy.app moved into PyStructSequence (used by sys.float_info) - added buildinfo into bpy.app.build_* - bpy.ui removed (wasnt used) - include external example files in Mathutils docs (only Mathutils and Vector are currently written) - added support to auto document PyStructSequence's - CMake had "'s inside all its strings.
2010-01-31 22:52:26 +01:00
version_string = bpy.app.version_string.split("(")[0]
if bpy.app.build_revision != "Unknown":
version_string = version_string + " r" + bpy.app.build_revision
sphinx doc gen - use 3 column lists for inherited props, funcs and for references to save on vertical space. - use the blender version string for the upload path and PDF name.
2010-09-03 11:21:40 +02:00
# for use with files
version_string_fp = "_".join(str(v) for v in bpy.app.version)
api reference docs: include bpy.data in the main page since its used everywhere. since this isnt a module its self its a little odd to do this but toctree cant make arbitrary cross-references. Also added some usage examples: http://www.blender.org/documentation/250PythonDoc/bpy.data.html
2010-06-27 20:34:27 +02:00
fw("project = 'Blender'\n")
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
# fw("master_doc = 'index'\n")
fw("copyright = u'Blender Foundation'\n")
parts of the Python API are unstable, big discalmer in API docs main page, API Docs title and interactive console banner.
2010-03-01 11:34:54 +01:00
fw("version = '%s - UNSTABLE API'\n" % version_string)
fw("release = '%s - UNSTABLE API'\n" % version_string)
Sphinx theme from Alex Sytnik (smerch) for API Docs You wouldnt know its not blender.org :D http://www.blender.org/documentation/250PythonDoc/mathutils.html from revision 39 of https://svn.blender.org/svnroot/blend-doc/trunk/python/doc
2010-05-14 12:21:57 +02:00
fw("html_theme = 'blender-org'\n")
fw("html_theme_path = ['../']\n")
fw("html_favicon = 'favicon.ico'\n")
parts of the Python API are unstable, big discalmer in API docs main page, API Docs title and interactive console banner.
2010-03-01 11:34:54 +01:00
# not helpful since the source us generated, adds to upload size.
fw("html_copy_source = False\n")
minor changes needed for PDF generation
2010-01-28 11:48:17 +01:00
fw("\n")
# needed for latex, pdf gen
fw("latex_documents = [ ('contents', 'contents.tex', 'Blender Index', 'Blender Foundation', 'manual'), ]\n")
fw("latex_paper_size = 'a4paper'\n")
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
file.close()
filepath = os.path.join(BASEPATH, "contents.rst")
file = open(filepath, "w")
fw = file.write
nicer start page for sphinx docs
2010-01-27 23:17:27 +01:00
fw("%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\n")
fw(" Blender Documentation contents\n")
fw("%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\n")
fw("\n")
Mathutils doc improvements + other small things - bpy.app moved into PyStructSequence (used by sys.float_info) - added buildinfo into bpy.app.build_* - bpy.ui removed (wasnt used) - include external example files in Mathutils docs (only Mathutils and Vector are currently written) - added support to auto document PyStructSequence's - CMake had "'s inside all its strings.
2010-01-31 22:52:26 +01:00
fw("This document is an API reference for Blender %s. built %s.\n" % (version_string, bpy.app.build_date))
nicer start page for sphinx docs
2010-01-27 23:17:27 +01:00
fw("\n")
api reference docs: include bpy.data in the main page since its used everywhere. since this isnt a module its self its a little odd to do this but toctree cant make arbitrary cross-references. Also added some usage examples: http://www.blender.org/documentation/250PythonDoc/bpy.data.html
2010-06-27 20:34:27 +02:00
fw("An introduction to Blender and Python can be found at <http://wiki.blender.org/index.php/Dev:2.5/Py/API/Intro>\n")
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
fw("\n")
sphinx doc gen - use 3 column lists for inherited props, funcs and for references to save on vertical space. - use the blender version string for the upload path and PDF name.
2010-09-03 11:21:40 +02:00
fw("`A PDF version of this document is also available <blender_python_reference_%s.pdf>`__\n" % version_string_fp)
merge own commits into render branch into trunk since 27560 27562, 27570, 27571, 27574, 27576, 27577, 27579, 27590, 27591, 27594, 27595, 27596, 27599, 27605, 27611, 27612, 27613, 27614, 27623
2010-03-20 17:41:01 +01:00
fw("\n")
parts of the Python API are unstable, big discalmer in API docs main page, API Docs title and interactive console banner.
2010-03-01 11:34:54 +01:00
fw(".. warning:: The Python API in Blender is **UNSTABLE**, It should only be used for testing, any script written now may break in future releases.\n")
fw(" \n")
fw(" The following areas are subject to change.\n")
fw(" * operator names and arguments\n")
- module for reading blend start/end frames and scene name (useful for finding the total frame count without loading a blend file) - added render api as unstable to the docs.
2010-06-15 14:06:30 +02:00
fw(" * render api\n")
parts of the Python API are unstable, big discalmer in API docs main page, API Docs title and interactive console banner.
2010-03-01 11:34:54 +01:00
fw(" * function calls with the data api (any function calls with values accessed from bpy.data), including functions for importing and exporting meshes\n")
fw(" * class registration (Operator, Panels, Menus, Headers)\n")
fw(" * modules: bpy.props, blf)\n")
fw(" * members in the bpy.context have to be reviewed\n")
fw(" * python defined modal operators, especially drawing callbacks are highly experemental\n")
fw(" \n")
fw(" These parts of the API are relatively stable and are unlikely to change significantly\n")
fw(" * data API, access to attributes of blender data such as mesh verts, material color, timeline frames and scene objects\n")
fw(" * user interface functions for defining buttons, creation of menus, headers, panels\n")
PyAPI - added new mathutils.Color() type, use with rna so we can do for eg: material.diffuse_color.r = 1.0 # also has hsv access material.diffuse_color.s = 0.6 - made Mathutils and Geometry module names lowercase.
2010-04-11 16:22:27 +02:00
fw(" * modules: bgl, mathutils and geometry\n")
apply UserPrefs and Theme rna naming changes.
2010-08-17 15:14:41 +02:00
fw(" * game engine modules\n")
parts of the Python API are unstable, big discalmer in API docs main page, API Docs title and interactive console banner.
2010-03-01 11:34:54 +01:00
fw("\n")
include game engine docs in sphinx doc generation: bge.events, logic, render & types (others still need work) Updated http://www.blender.org/documentation/250PythonDoc
2010-05-17 22:38:54 +02:00
fw("===================\n")
fw("Application Modules\n")
fw("===================\n")
fw("\n")
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
fw(".. toctree::\n")
nicer start page for sphinx docs
2010-01-27 23:17:27 +01:00
fw(" :maxdepth: 1\n\n")
api reference docs: include bpy.data in the main page since its used everywhere. since this isnt a module its self its a little odd to do this but toctree cant make arbitrary cross-references. Also added some usage examples: http://www.blender.org/documentation/250PythonDoc/bpy.data.html
2010-06-27 20:34:27 +02:00
fw(" bpy.data.rst\n\n") # note: not actually a module
nicer start page for sphinx docs
2010-01-27 23:17:27 +01:00
fw(" bpy.ops.rst\n\n")
fw(" bpy.types.rst\n\n")
initial sphinx doc generation support for python and C modules. python modules bpy.app, bpy.utils are now included in docs. C defined python module bpy.props has its docstrings extracted and written directly into sphinx docs since the C methods cant be inspected. added docstrings to bpy.props and improved some in bpy.utils. will update online docs tomorrow.
2010-01-22 03:04:25 +01:00
# py modules
nicer start page for sphinx docs
2010-01-27 23:17:27 +01:00
fw(" bpy.utils.rst\n\n")
bugfix [#23194] export UVs miss the extension file also made all other exporters do this. Made some internal changes. - moved path functions from bpy.utils to bpy.path (similar to os.path) - added functions... bpy.path.ensure_ext(path, ".ext", case_sensitive=False) # simple function to ensure the extension is set. bpy.path.resolve_ncase(path) # useful for importing scenes made on windows where the path case doesnt match the files.
2010-08-06 03:40:54 +02:00
fw(" bpy.path.rst\n\n")
nicer start page for sphinx docs
2010-01-27 23:17:27 +01:00
fw(" bpy.app.rst\n\n")
initial sphinx doc generation support for python and C modules. python modules bpy.app, bpy.utils are now included in docs. C defined python module bpy.props has its docstrings extracted and written directly into sphinx docs since the C methods cant be inspected. added docstrings to bpy.props and improved some in bpy.utils. will update online docs tomorrow.
2010-01-22 03:04:25 +01:00
# C modules
nicer start page for sphinx docs
2010-01-27 23:17:27 +01:00
fw(" bpy.props.rst\n\n")
include game engine docs in sphinx doc generation: bge.events, logic, render & types (others still need work) Updated http://www.blender.org/documentation/250PythonDoc
2010-05-17 22:38:54 +02:00
fw("==================\n")
fw("Standalone Modules\n")
fw("==================\n")
fw("\n")
fw(".. toctree::\n")
fw(" :maxdepth: 1\n\n")
PyAPI - added new mathutils.Color() type, use with rna so we can do for eg: material.diffuse_color.r = 1.0 # also has hsv access material.diffuse_color.s = 0.6 - made Mathutils and Geometry module names lowercase.
2010-04-11 16:22:27 +02:00
fw(" mathutils.rst\n\n")
parts of the Python API are unstable, big discalmer in API docs main page, API Docs title and interactive console banner.
2010-03-01 11:34:54 +01:00
fw(" blf.rst\n\n")
BGE Py API: * Sphinx autorun file. * bge modules are now autogenerated * added aud module
2010-07-16 23:42:20 +02:00
fw(" aud.rst\n\n")
include game engine docs in sphinx doc generation: bge.events, logic, render & types (others still need work) Updated http://www.blender.org/documentation/250PythonDoc
2010-05-17 22:38:54 +02:00
# game engine
fw("===================\n")
fw("Game Engine Modules\n")
fw("===================\n")
fw("\n")
fw(".. toctree::\n")
fw(" :maxdepth: 1\n\n")
fw(" bge.types.rst\n\n")
fw(" bge.logic.rst\n\n")
fw(" bge.render.rst\n\n")
fw(" bge.events.rst\n\n")
nicer start page for sphinx docs
2010-01-27 23:17:27 +01:00
file.close()
# internal modules
filepath = os.path.join(BASEPATH, "bpy.ops.rst")
file = open(filepath, "w")
fw = file.write
api reference docs: include bpy.data in the main page since its used everywhere. since this isnt a module its self its a little odd to do this but toctree cant make arbitrary cross-references. Also added some usage examples: http://www.blender.org/documentation/250PythonDoc/bpy.data.html
2010-06-27 20:34:27 +02:00
fw("Operators (bpy.ops)\n")
fw("===================\n\n")
nicer start page for sphinx docs
2010-01-27 23:17:27 +01:00
fw(".. toctree::\n")
fw(" :glob:\n\n")
fw(" bpy.ops.*\n\n")
file.close()
Mathutils refactor & include in sphinx generated docs, (TODO, include getset'ers in docs) - Mathutils.MidpointVecs --> vector.lerp(other, fac) - Mathutils.AngleBetweenVecs --> vector.angle(other) - Mathutils.ProjectVecs --> vector.project(other) - Mathutils.DifferenceQuats --> quat.difference(other) - Mathutils.Slerp --> quat.slerp(other, fac) - Mathutils.Rand: removed, use pythons random module - Mathutils.RotationMatrix(angle, size, axis_flag, axis) --> Mathutils.RotationMatrix(angle, size, axis); merge axis & axis_flag args - Matrix.scalePart --> Matrix.scale_part - Matrix.translationPart --> Matrix.translation_part - Matrix.rotationPart --> Matrix.rotation_part - toMatrix --> to_matrix - toEuler --> to_euler - toQuat --> to_quat - Vector.toTrackQuat --> Vector.to_track_quat
2010-01-25 10:44:04 +01:00
nicer start page for sphinx docs
2010-01-27 23:17:27 +01:00
filepath = os.path.join(BASEPATH, "bpy.types.rst")
file = open(filepath, "w")
fw = file.write
api reference docs: include bpy.data in the main page since its used everywhere. since this isnt a module its self its a little odd to do this but toctree cant make arbitrary cross-references. Also added some usage examples: http://www.blender.org/documentation/250PythonDoc/bpy.data.html
2010-06-27 20:34:27 +02:00
fw("Types (bpy.types)\n")
fw("=================\n\n")
nicer start page for sphinx docs
2010-01-27 23:17:27 +01:00
fw(".. toctree::\n")
fw(" :glob:\n\n")
fw(" bpy.types.*\n\n")
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
file.close()
nicer start page for sphinx docs
2010-01-27 23:17:27 +01:00
api reference docs: include bpy.data in the main page since its used everywhere. since this isnt a module its self its a little odd to do this but toctree cant make arbitrary cross-references. Also added some usage examples: http://www.blender.org/documentation/250PythonDoc/bpy.data.html
2010-06-27 20:34:27 +02:00
# not actually a module, only write this file so we
# can reference in the TOC
filepath = os.path.join(BASEPATH, "bpy.data.rst")
file = open(filepath, "w")
fw = file.write
fw("Data Access (bpy.data)\n")
fw("======================\n\n")
fw(".. module:: bpy\n")
fw("\n")
fw("This module is used for all blender/python access.\n")
fw("\n")
== python api docs == - properties are now listed on alphabetical order - readonly properties use "data" directive, so that we see them in green in the web docs example (after Campbell will rebuild the docs): http://www.blender.org/documentation/250PythonDoc/bpy.types.RenderLayer.html (note that green attributes still need final CSS-ing, but smerch is a bit busy atm) - fixed indentation in http://www.blender.org/documentation/250PythonDoc/bpy.data.html
2010-06-28 02:06:23 +02:00
fw(".. literalinclude:: ../examples/bpy.data.py\n")
api reference docs: include bpy.data in the main page since its used everywhere. since this isnt a module its self its a little odd to do this but toctree cant make arbitrary cross-references. Also added some usage examples: http://www.blender.org/documentation/250PythonDoc/bpy.data.html
2010-06-27 20:34:27 +02:00
fw("\n")
== python api docs == - properties are now listed on alphabetical order - readonly properties use "data" directive, so that we see them in green in the web docs example (after Campbell will rebuild the docs): http://www.blender.org/documentation/250PythonDoc/bpy.types.RenderLayer.html (note that green attributes still need final CSS-ing, but smerch is a bit busy atm) - fixed indentation in http://www.blender.org/documentation/250PythonDoc/bpy.data.html
2010-06-28 02:06:23 +02:00
fw(".. data:: data\n")
api reference docs: include bpy.data in the main page since its used everywhere. since this isnt a module its self its a little odd to do this but toctree cant make arbitrary cross-references. Also added some usage examples: http://www.blender.org/documentation/250PythonDoc/bpy.data.html
2010-06-27 20:34:27 +02:00
fw("\n")
fw(" Access to blenders internal data\n")
fw("\n")
rna api - move: material.add_texture(tex, coords, mapto) --> material.texture_slots.add() - added material.texture_slots.create(index), material.texture_slots.clear(index) - texture slot functions also work for lamp and world now. Other minor changes - allow rna functions to set FUNC_NO_SELF and FUNC_USE_SELF_ID at once. - [#23317] Changed some operators' RNA to accept lengths, a modification I made to this patch made it not work as intended, removed this edit so unit buttons appier in the UI for certain operators. - Sphinx doc gen, 2 columns rather then 3, didnt quite fit in some cases.
2010-09-03 16:53:54 +02:00
fw(" :type: :class:`bpy.types.BlendData`\n")
api reference docs: include bpy.data in the main page since its used everywhere. since this isnt a module its self its a little odd to do this but toctree cant make arbitrary cross-references. Also added some usage examples: http://www.blender.org/documentation/250PythonDoc/bpy.data.html
2010-06-27 20:34:27 +02:00
file.close()
EXAMPLE_SET_USED.add("bpy.data")
initial sphinx doc generation support for python and C modules. python modules bpy.app, bpy.utils are now included in docs. C defined python module bpy.props has its docstrings extracted and written directly into sphinx docs since the C methods cant be inspected. added docstrings to bpy.props and improved some in bpy.utils. will update online docs tomorrow.
2010-01-22 03:04:25 +01:00
# python modules
from bpy import utils as module
nicer start page for sphinx docs
2010-01-27 23:17:27 +01:00
pymodule2sphinx(BASEPATH, "bpy.utils", module, "Utilities (bpy.utils)")
Mathutils doc improvements + other small things - bpy.app moved into PyStructSequence (used by sys.float_info) - added buildinfo into bpy.app.build_* - bpy.ui removed (wasnt used) - include external example files in Mathutils docs (only Mathutils and Vector are currently written) - added support to auto document PyStructSequence's - CMake had "'s inside all its strings.
2010-01-31 22:52:26 +01:00
bugfix [#23194] export UVs miss the extension file also made all other exporters do this. Made some internal changes. - moved path functions from bpy.utils to bpy.path (similar to os.path) - added functions... bpy.path.ensure_ext(path, ".ext", case_sensitive=False) # simple function to ensure the extension is set. bpy.path.resolve_ncase(path) # useful for importing scenes made on windows where the path case doesnt match the files.
2010-08-06 03:40:54 +02:00
from bpy import path as module
pymodule2sphinx(BASEPATH, "bpy.path", module, "Path Utilities (bpy.path)")
Mathutils doc improvements + other small things - bpy.app moved into PyStructSequence (used by sys.float_info) - added buildinfo into bpy.app.build_* - bpy.ui removed (wasnt used) - include external example files in Mathutils docs (only Mathutils and Vector are currently written) - added support to auto document PyStructSequence's - CMake had "'s inside all its strings.
2010-01-31 22:52:26 +01:00
# C modules
initial sphinx doc generation support for python and C modules. python modules bpy.app, bpy.utils are now included in docs. C defined python module bpy.props has its docstrings extracted and written directly into sphinx docs since the C methods cant be inspected. added docstrings to bpy.props and improved some in bpy.utils. will update online docs tomorrow.
2010-01-22 03:04:25 +01:00
from bpy import app as module
nicer start page for sphinx docs
2010-01-27 23:17:27 +01:00
pymodule2sphinx(BASEPATH, "bpy.app", module, "Application Data (bpy.app)")
initial sphinx doc generation support for python and C modules. python modules bpy.app, bpy.utils are now included in docs. C defined python module bpy.props has its docstrings extracted and written directly into sphinx docs since the C methods cant be inspected. added docstrings to bpy.props and improved some in bpy.utils. will update online docs tomorrow.
2010-01-22 03:04:25 +01:00
from bpy import props as module
nicer start page for sphinx docs
2010-01-27 23:17:27 +01:00
pymodule2sphinx(BASEPATH, "bpy.props", module, "Property Definitions (bpy.props)")
Mathutils refactor & include in sphinx generated docs, (TODO, include getset'ers in docs) - Mathutils.MidpointVecs --> vector.lerp(other, fac) - Mathutils.AngleBetweenVecs --> vector.angle(other) - Mathutils.ProjectVecs --> vector.project(other) - Mathutils.DifferenceQuats --> quat.difference(other) - Mathutils.Slerp --> quat.slerp(other, fac) - Mathutils.Rand: removed, use pythons random module - Mathutils.RotationMatrix(angle, size, axis_flag, axis) --> Mathutils.RotationMatrix(angle, size, axis); merge axis & axis_flag args - Matrix.scalePart --> Matrix.scale_part - Matrix.translationPart --> Matrix.translation_part - Matrix.rotationPart --> Matrix.rotation_part - toMatrix --> to_matrix - toEuler --> to_euler - toQuat --> to_quat - Vector.toTrackQuat --> Vector.to_track_quat
2010-01-25 10:44:04 +01:00
PyAPI - added new mathutils.Color() type, use with rna so we can do for eg: material.diffuse_color.r = 1.0 # also has hsv access material.diffuse_color.s = 0.6 - made Mathutils and Geometry module names lowercase.
2010-04-11 16:22:27 +02:00
import mathutils as module
pymodule2sphinx(BASEPATH, "mathutils", module, "Math Types & Utilities (mathutils)")
initial sphinx doc generation support for python and C modules. python modules bpy.app, bpy.utils are now included in docs. C defined python module bpy.props has its docstrings extracted and written directly into sphinx docs since the C methods cant be inspected. added docstrings to bpy.props and improved some in bpy.utils. will update online docs tomorrow.
2010-01-22 03:04:25 +01:00
del module
parts of the Python API are unstable, big discalmer in API docs main page, API Docs title and interactive console banner.
2010-03-01 11:34:54 +01:00
import blf as module
api reference docs: include bpy.data in the main page since its used everywhere. since this isnt a module its self its a little odd to do this but toctree cant make arbitrary cross-references. Also added some usage examples: http://www.blender.org/documentation/250PythonDoc/bpy.data.html
2010-06-27 20:34:27 +02:00
pymodule2sphinx(BASEPATH, "blf", module, "Font Drawing (blf)")
include BLF in automated doc generation http://www.blender.org/documentation/250PythonDoc/BLF.html
2010-02-28 12:54:48 +01:00
del module
BGE Py API: * Sphinx autorun file. * bge modules are now autogenerated * added aud module
2010-07-16 23:42:20 +02:00
import aud as module
pymodule2sphinx(BASEPATH, "aud", module, "Audio System (aud)")
del module
nicer start page for sphinx docs
2010-01-27 23:17:27 +01:00
include game engine docs in sphinx doc generation: bge.events, logic, render & types (others still need work) Updated http://www.blender.org/documentation/250PythonDoc
2010-05-17 22:38:54 +02:00
# game engine
import shutil
# copy2 keeps time/date stamps
shutil.copy2(os.path.join(BASEPATH, "../../../../gameengine/PyDoc/bge.types.rst"), BASEPATH)
shutil.copy2(os.path.join(BASEPATH, "../../../../gameengine/PyDoc/bge.logic.rst"), BASEPATH)
shutil.copy2(os.path.join(BASEPATH, "../../../../gameengine/PyDoc/bge.render.rst"), BASEPATH)
shutil.copy2(os.path.join(BASEPATH, "../../../../gameengine/PyDoc/bge.events.rst"), BASEPATH)
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
if 0:
filepath = os.path.join(BASEPATH, "bpy.rst")
file = open(filepath, "w")
fw = file.write
fw("\n")
title = ":mod:`bpy` --- Blender Python Module"
fw("%s\n%s\n\n" % (title, "=" * len(title)))
fw(".. module:: bpy.types\n\n")
file.close()
* sphinx docgen * py_function_args wasnt working right (was using function namespace for function args), use pythons inspect module instead. move the function to get a type description into rna_info
2009-12-26 17:47:25 +01:00
def write_param(ident, fw, prop, is_return=False):
if is_return:
id_name = "return"
id_type = "rtype"
reference docs: include type info with function return values
2010-01-18 11:45:54 +01:00
kwargs = {"as_ret": True, "class_fmt": ":class:`%s`"}
identifier = ""
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
else:
* sphinx docgen * py_function_args wasnt working right (was using function namespace for function args), use pythons inspect module instead. move the function to get a type description into rna_info
2009-12-26 17:47:25 +01:00
id_name = "arg"
id_type = "type"
reference docs: include type info with function return values
2010-01-18 11:45:54 +01:00
kwargs = {"as_arg": True, "class_fmt": ":class:`%s`"}
identifier = " %s" % prop.identifier
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
reference docs: include type info with function return values
2010-01-18 11:45:54 +01:00
type_descr = prop.get_type_description(**kwargs)
* sphinx docgen * py_function_args wasnt working right (was using function namespace for function args), use pythons inspect module instead. move the function to get a type description into rna_info
2009-12-26 17:47:25 +01:00
if prop.name or prop.description:
reference docs: include type info with function return values
2010-01-18 11:45:54 +01:00
fw(ident + ":%s%s: %s\n" % (id_name, identifier, ", ".join([val for val in (prop.name, prop.description) if val])))
fw(ident + ":%s%s: %s\n" % (id_type, identifier, type_descr))
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
def write_struct(struct):
#if not struct.identifier.startswith("Sc") and not struct.identifier.startswith("I"):
# return
fix for mistake in last commit. also forgot to call RNA_parameter_list_end() in some places, (ok the function does nothing now, but some day it might do)
2010-01-02 20:01:19 +01:00
#if not struct.identifier == "Object":
# return
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
filepath = os.path.join(BASEPATH, "bpy.types.%s.rst" % struct.identifier)
file = open(filepath, "w")
fw = file.write
rna/py/reference doc improvements.. - vectors now respect min/max settings. - keyframing and adding drivers raises an error in an index is set on a non array, keyframing raises an error if it fails. reference docs... - added docstrings for remaining python bpy_struct functions - added fake class for docs, bpy_struct, which is the base class of everything in bpy.types - improved inherictance references for struct classes, include bpy_struct members.
2010-04-10 20:35:50 +02:00
base_id = getattr(struct.base, "identifier", "")
if _BPY_STRUCT_FAKE:
if not base_id:
base_id = _BPY_STRUCT_FAKE
if base_id:
title = "%s(%s)" % (struct.identifier, base_id)
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
else:
title = struct.identifier
fw("%s\n%s\n\n" % (title, "=" * len(title)))
fw(".. module:: bpy.types\n\n")
rna/py/reference doc improvements.. - vectors now respect min/max settings. - keyframing and adding drivers raises an error in an index is set on a non array, keyframing raises an error if it fails. reference docs... - added docstrings for remaining python bpy_struct functions - added fake class for docs, bpy_struct, which is the base class of everything in bpy.types - improved inherictance references for struct classes, include bpy_struct members.
2010-04-10 20:35:50 +02:00
base_ids = [base.identifier for base in struct.get_bases()]
if _BPY_STRUCT_FAKE:
base_ids.append(_BPY_STRUCT_FAKE)
base_ids.reverse()
if base_ids:
if len(base_ids) > 1:
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
fw("base classes --- ")
else:
fw("base class --- ")
rna/py/reference doc improvements.. - vectors now respect min/max settings. - keyframing and adding drivers raises an error in an index is set on a non array, keyframing raises an error if it fails. reference docs... - added docstrings for remaining python bpy_struct functions - added fake class for docs, bpy_struct, which is the base class of everything in bpy.types - improved inherictance references for struct classes, include bpy_struct members.
2010-04-10 20:35:50 +02:00
fw(", ".join([(":class:`%s`" % base_id) for base_id in base_ids]))
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
fw("\n\n")
rna/py/reference doc improvements.. - vectors now respect min/max settings. - keyframing and adding drivers raises an error in an index is set on a non array, keyframing raises an error if it fails. reference docs... - added docstrings for remaining python bpy_struct functions - added fake class for docs, bpy_struct, which is the base class of everything in bpy.types - improved inherictance references for struct classes, include bpy_struct members.
2010-04-10 20:35:50 +02:00
subclass_ids = [s.identifier for s in structs.values() if s.base is struct if not rna_info.rna_id_ignore(s.identifier)]
if subclass_ids:
fw("subclasses --- \n" + ", ".join([(":class:`%s`" % s) for s in subclass_ids]) + "\n\n")
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
rna/py/reference doc improvements.. - vectors now respect min/max settings. - keyframing and adding drivers raises an error in an index is set on a non array, keyframing raises an error if it fails. reference docs... - added docstrings for remaining python bpy_struct functions - added fake class for docs, bpy_struct, which is the base class of everything in bpy.types - improved inherictance references for struct classes, include bpy_struct members.
2010-04-10 20:35:50 +02:00
base_id = getattr(struct.base, "identifier", "")
if _BPY_STRUCT_FAKE:
if not base_id:
base_id = _BPY_STRUCT_FAKE
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
rna/py/reference doc improvements.. - vectors now respect min/max settings. - keyframing and adding drivers raises an error in an index is set on a non array, keyframing raises an error if it fails. reference docs... - added docstrings for remaining python bpy_struct functions - added fake class for docs, bpy_struct, which is the base class of everything in bpy.types - improved inherictance references for struct classes, include bpy_struct members.
2010-04-10 20:35:50 +02:00
if base_id:
fw(".. class:: %s(%s)\n\n" % (struct.identifier, base_id))
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
else:
fw(".. class:: %s\n\n" % struct.identifier)
fw(" %s\n\n" % struct.description)
== python api docs == - properties are now listed on alphabetical order - readonly properties use "data" directive, so that we see them in green in the web docs example (after Campbell will rebuild the docs): http://www.blender.org/documentation/250PythonDoc/bpy.types.RenderLayer.html (note that green attributes still need final CSS-ing, but smerch is a bit busy atm) - fixed indentation in http://www.blender.org/documentation/250PythonDoc/bpy.data.html
2010-06-28 02:06:23 +02:00
# properties sorted in alphabetical order
change some references to .B.blend, .Blog to new names
2010-07-15 13:51:43 +02:00
sorted_struct_properties = struct.properties[:]
sorted_struct_properties.sort(key=lambda prop: prop.identifier)
== python api docs == - properties are now listed on alphabetical order - readonly properties use "data" directive, so that we see them in green in the web docs example (after Campbell will rebuild the docs): http://www.blender.org/documentation/250PythonDoc/bpy.types.RenderLayer.html (note that green attributes still need final CSS-ing, but smerch is a bit busy atm) - fixed indentation in http://www.blender.org/documentation/250PythonDoc/bpy.data.html
2010-06-28 02:06:23 +02:00
for prop in sorted_struct_properties:
type_descr = prop.get_type_description(class_fmt=":class:`%s`")
# readonly properties use "data" directive, variables properties use "attribute" directive
if 'readonly' in type_descr:
fw(" .. data:: %s\n\n" % prop.identifier)
else:
fw(" .. attribute:: %s\n\n" % prop.identifier)
* sphinx docgen * py_function_args wasnt working right (was using function namespace for function args), use pythons inspect module instead. move the function to get a type description into rna_info
2009-12-26 17:47:25 +01:00
if prop.description:
fw(" %s\n\n" % prop.description)
== python api docs == * source/blender/python/doc/sphinx_doc_gen.py changed syntax for declating attributes type to use :type: instead of *type* os it * source/gameengine/Ketsji/KX_PythonInit.cpp While documenting I've found that we have two naming conventions for constraints in BGE python api, example: KX_CONSTRAINTACT_DIRPZ and KX_ACT_CONSTRAINT_FHPX: the right convention is KX_CONSTRAINTACT_xxx After talking with dalai and cambpell we agreed that this kind of change is better suited for NExyon GSoC so I marked as TODO Also, found 2 duplicate rows, fixed after askin nexyon * source/gameengine/PyDoc/bge.logic.rst there were 2 blocks for constraints, I've put them together in docs and fixed some other lines * source/gameengine/PyDoc/bge.types.rst first cleanup: mainly started using ":type:", it was mixed usage of *type* and **type** started cleaning some bullet list in a way that varibles link to the constant in appropriate page I'll continue later
2010-06-02 23:28:17 +02:00
fw(" :type: %s\n\n" % type_descr)
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
# python attributes
py_properties = struct.get_py_properties()
py_prop = None
for identifier, py_prop in py_properties:
initial sphinx doc generation support for python and C modules. python modules bpy.app, bpy.utils are now included in docs. C defined python module bpy.props has its docstrings extracted and written directly into sphinx docs since the C methods cant be inspected. added docstrings to bpy.props and improved some in bpy.utils. will update online docs tomorrow.
2010-01-22 03:04:25 +01:00
pyprop2sphinx(" ", fw, identifier, py_prop)
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
del py_properties, py_prop
for func in struct.functions:
args_str = ", ".join([prop.get_arg_default(force=False) for prop in func.args])
document rna functions that have the no_self flag set as classmethods
2010-08-17 16:32:14 +02:00
fw(" .. %s:: %s(%s)\n\n" % ("classmethod" if func.is_classmethod else "method", func.identifier, args_str))
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
fw(" %s\n\n" % func.description)
for prop in func.args:
* sphinx docgen * py_function_args wasnt working right (was using function namespace for function args), use pythons inspect module instead. move the function to get a type description into rna_info
2009-12-26 17:47:25 +01:00
write_param(" ", fw, prop)
sphinx support for documenting multiple return values
2010-01-02 19:55:07 +01:00
if len(func.return_values) == 1:
write_param(" ", fw, func.return_values[0], is_return=True)
fixed sphinx doc generator - arguments, return values indentation means they get correctly interpreted by sphinx - functions with no return values were displaying return as () - return values were getting the '(optional)' added in some cases. Example: http://www.blender.org/documentation/250PythonDoc/bpy.ops.object.html
2010-01-17 21:59:35 +01:00
elif func.return_values: # multiple return values
fw(" :return (%s):\n" % ", ".join([prop.identifier for prop in func.return_values]))
sphinx support for documenting multiple return values
2010-01-02 19:55:07 +01:00
for prop in func.return_values:
fixed sphinx doc generator - arguments, return values indentation means they get correctly interpreted by sphinx - functions with no return values were displaying return as () - return values were getting the '(optional)' added in some cases. Example: http://www.blender.org/documentation/250PythonDoc/bpy.ops.object.html
2010-01-17 21:59:35 +01:00
type_descr = prop.get_type_description(as_ret=True, class_fmt=":class:`%s`")
sphinx support for documenting multiple return values
2010-01-02 19:55:07 +01:00
descr = prop.description
if not descr:
descr = prop.name
fixed sphinx doc generator - arguments, return values indentation means they get correctly interpreted by sphinx - functions with no return values were displaying return as () - return values were getting the '(optional)' added in some cases. Example: http://www.blender.org/documentation/250PythonDoc/bpy.ops.object.html
2010-01-17 21:59:35 +01:00
fw(" `%s`, %s, %s\n\n" % (prop.identifier, descr, type_descr))
sphinx support for documenting multiple return values
2010-01-02 19:55:07 +01:00
* sphinx docgen * py_function_args wasnt working right (was using function namespace for function args), use pythons inspect module instead. move the function to get a type description into rna_info
2009-12-26 17:47:25 +01:00
fw("\n")
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
# python methods
py_funcs = struct.get_py_functions()
py_func = None
for identifier, py_func in py_funcs:
initial sphinx doc generation support for python and C modules. python modules bpy.app, bpy.utils are now included in docs. C defined python module bpy.props has its docstrings extracted and written directly into sphinx docs since the C methods cant be inspected. added docstrings to bpy.props and improved some in bpy.utils. will update online docs tomorrow.
2010-01-22 03:04:25 +01:00
pyfunc2sphinx(" ", fw, identifier, py_func, is_class=True)
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
del py_funcs, py_func
rna reference docs, list inherited properties and functions at the bottom of each type.
2010-04-09 22:43:58 +02:00
lines = []
rna/py/reference doc improvements.. - vectors now respect min/max settings. - keyframing and adding drivers raises an error in an index is set on a non array, keyframing raises an error if it fails. reference docs... - added docstrings for remaining python bpy_struct functions - added fake class for docs, bpy_struct, which is the base class of everything in bpy.types - improved inherictance references for struct classes, include bpy_struct members.
2010-04-10 20:35:50 +02:00
if struct.base or _BPY_STRUCT_FAKE:
rna reference docs, list inherited properties and functions at the bottom of each type.
2010-04-09 22:43:58 +02:00
bases = list(reversed(struct.get_bases()))
rna/py/reference doc improvements.. - vectors now respect min/max settings. - keyframing and adding drivers raises an error in an index is set on a non array, keyframing raises an error if it fails. reference docs... - added docstrings for remaining python bpy_struct functions - added fake class for docs, bpy_struct, which is the base class of everything in bpy.types - improved inherictance references for struct classes, include bpy_struct members.
2010-04-10 20:35:50 +02:00
rna reference docs, list inherited properties and functions at the bottom of each type.
2010-04-09 22:43:58 +02:00
# props
lines[:] = []
rna/py/reference doc improvements.. - vectors now respect min/max settings. - keyframing and adding drivers raises an error in an index is set on a non array, keyframing raises an error if it fails. reference docs... - added docstrings for remaining python bpy_struct functions - added fake class for docs, bpy_struct, which is the base class of everything in bpy.types - improved inherictance references for struct classes, include bpy_struct members.
2010-04-10 20:35:50 +02:00
if _BPY_STRUCT_FAKE:
descr_items = [(key, descr) for key, descr in sorted(bpy.types.Struct.__bases__[0].__dict__.items()) if not key.startswith("__")]
if _BPY_STRUCT_FAKE:
for key, descr in descr_items:
if type(descr) == GetSetDescriptorType:
sphinx doc gen - use 3 column lists for inherited props, funcs and for references to save on vertical space. - use the blender version string for the upload path and PDF name.
2010-09-03 11:21:40 +02:00
lines.append(" * :class:`%s.%s`\n" % (_BPY_STRUCT_FAKE, key))
rna/py/reference doc improvements.. - vectors now respect min/max settings. - keyframing and adding drivers raises an error in an index is set on a non array, keyframing raises an error if it fails. reference docs... - added docstrings for remaining python bpy_struct functions - added fake class for docs, bpy_struct, which is the base class of everything in bpy.types - improved inherictance references for struct classes, include bpy_struct members.
2010-04-10 20:35:50 +02:00
rna reference docs, list inherited properties and functions at the bottom of each type.
2010-04-09 22:43:58 +02:00
for base in bases:
for prop in base.properties:
sphinx doc gen - use 3 column lists for inherited props, funcs and for references to save on vertical space. - use the blender version string for the upload path and PDF name.
2010-09-03 11:21:40 +02:00
lines.append(" * :class:`%s.%s`\n" % (base.identifier, prop.identifier))
rna reference docs, list inherited properties and functions at the bottom of each type.
2010-04-09 22:43:58 +02:00
for identifier, py_prop in base.get_py_properties():
sphinx doc gen - use 3 column lists for inherited props, funcs and for references to save on vertical space. - use the blender version string for the upload path and PDF name.
2010-09-03 11:21:40 +02:00
lines.append(" * :class:`%s.%s`\n" % (base.identifier, identifier))
rna/py/reference doc improvements.. - vectors now respect min/max settings. - keyframing and adding drivers raises an error in an index is set on a non array, keyframing raises an error if it fails. reference docs... - added docstrings for remaining python bpy_struct functions - added fake class for docs, bpy_struct, which is the base class of everything in bpy.types - improved inherictance references for struct classes, include bpy_struct members.
2010-04-10 20:35:50 +02:00
for identifier, py_prop in base.get_py_properties():
sphinx doc gen - use 3 column lists for inherited props, funcs and for references to save on vertical space. - use the blender version string for the upload path and PDF name.
2010-09-03 11:21:40 +02:00
lines.append(" * :class:`%s.%s`\n" % (base.identifier, identifier))
rna reference docs, list inherited properties and functions at the bottom of each type.
2010-04-09 22:43:58 +02:00
if lines:
fw(".. rubric:: Inherited Properties\n\n")
sphinx doc gen - use 3 column lists for inherited props, funcs and for references to save on vertical space. - use the blender version string for the upload path and PDF name.
2010-09-03 11:21:40 +02:00
fw(".. hlist::\n")
rna api - move: material.add_texture(tex, coords, mapto) --> material.texture_slots.add() - added material.texture_slots.create(index), material.texture_slots.clear(index) - texture slot functions also work for lamp and world now. Other minor changes - allow rna functions to set FUNC_NO_SELF and FUNC_USE_SELF_ID at once. - [#23317] Changed some operators' RNA to accept lengths, a modification I made to this patch made it not work as intended, removed this edit so unit buttons appier in the UI for certain operators. - Sphinx doc gen, 2 columns rather then 3, didnt quite fit in some cases.
2010-09-03 16:53:54 +02:00
fw(" :columns: 2\n\n")
sphinx doc gen - use 3 column lists for inherited props, funcs and for references to save on vertical space. - use the blender version string for the upload path and PDF name.
2010-09-03 11:21:40 +02:00
rna reference docs, list inherited properties and functions at the bottom of each type.
2010-04-09 22:43:58 +02:00
for line in lines:
fw(line)
fw("\n")
# funcs
lines[:] = []
rna/py/reference doc improvements.. - vectors now respect min/max settings. - keyframing and adding drivers raises an error in an index is set on a non array, keyframing raises an error if it fails. reference docs... - added docstrings for remaining python bpy_struct functions - added fake class for docs, bpy_struct, which is the base class of everything in bpy.types - improved inherictance references for struct classes, include bpy_struct members.
2010-04-10 20:35:50 +02:00
if _BPY_STRUCT_FAKE:
for key, descr in descr_items:
if type(descr) == MethodDescriptorType:
sphinx doc gen - use 3 column lists for inherited props, funcs and for references to save on vertical space. - use the blender version string for the upload path and PDF name.
2010-09-03 11:21:40 +02:00
lines.append(" * :class:`%s.%s`\n" % (_BPY_STRUCT_FAKE, key))
rna/py/reference doc improvements.. - vectors now respect min/max settings. - keyframing and adding drivers raises an error in an index is set on a non array, keyframing raises an error if it fails. reference docs... - added docstrings for remaining python bpy_struct functions - added fake class for docs, bpy_struct, which is the base class of everything in bpy.types - improved inherictance references for struct classes, include bpy_struct members.
2010-04-10 20:35:50 +02:00
rna reference docs, list inherited properties and functions at the bottom of each type.
2010-04-09 22:43:58 +02:00
for base in bases:
for func in base.functions:
sphinx doc gen - use 3 column lists for inherited props, funcs and for references to save on vertical space. - use the blender version string for the upload path and PDF name.
2010-09-03 11:21:40 +02:00
lines.append(" * :class:`%s.%s`\n" % (base.identifier, func.identifier))
rna reference docs, list inherited properties and functions at the bottom of each type.
2010-04-09 22:43:58 +02:00
for identifier, py_func in base.get_py_functions():
sphinx doc gen - use 3 column lists for inherited props, funcs and for references to save on vertical space. - use the blender version string for the upload path and PDF name.
2010-09-03 11:21:40 +02:00
lines.append(" * :class:`%s.%s`\n" % (base.identifier, identifier))
rna reference docs, list inherited properties and functions at the bottom of each type.
2010-04-09 22:43:58 +02:00
if lines:
fw(".. rubric:: Inherited Functions\n\n")
sphinx doc gen - use 3 column lists for inherited props, funcs and for references to save on vertical space. - use the blender version string for the upload path and PDF name.
2010-09-03 11:21:40 +02:00
fw(".. hlist::\n")
rna api - move: material.add_texture(tex, coords, mapto) --> material.texture_slots.add() - added material.texture_slots.create(index), material.texture_slots.clear(index) - texture slot functions also work for lamp and world now. Other minor changes - allow rna functions to set FUNC_NO_SELF and FUNC_USE_SELF_ID at once. - [#23317] Changed some operators' RNA to accept lengths, a modification I made to this patch made it not work as intended, removed this edit so unit buttons appier in the UI for certain operators. - Sphinx doc gen, 2 columns rather then 3, didnt quite fit in some cases.
2010-09-03 16:53:54 +02:00
fw(" :columns: 2\n\n")
sphinx doc gen - use 3 column lists for inherited props, funcs and for references to save on vertical space. - use the blender version string for the upload path and PDF name.
2010-09-03 11:21:40 +02:00
rna reference docs, list inherited properties and functions at the bottom of each type.
2010-04-09 22:43:58 +02:00
for line in lines:
fw(line)
fw("\n")
lines[:] = []
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
if struct.references:
# use this otherwise it gets in the index for a normal heading.
fw(".. rubric:: References\n\n")
sphinx doc gen - use 3 column lists for inherited props, funcs and for references to save on vertical space. - use the blender version string for the upload path and PDF name.
2010-09-03 11:21:40 +02:00
fw(".. hlist::\n")
rna api - move: material.add_texture(tex, coords, mapto) --> material.texture_slots.add() - added material.texture_slots.create(index), material.texture_slots.clear(index) - texture slot functions also work for lamp and world now. Other minor changes - allow rna functions to set FUNC_NO_SELF and FUNC_USE_SELF_ID at once. - [#23317] Changed some operators' RNA to accept lengths, a modification I made to this patch made it not work as intended, removed this edit so unit buttons appier in the UI for certain operators. - Sphinx doc gen, 2 columns rather then 3, didnt quite fit in some cases.
2010-09-03 16:53:54 +02:00
fw(" :columns: 2\n\n")
sphinx doc gen - use 3 column lists for inherited props, funcs and for references to save on vertical space. - use the blender version string for the upload path and PDF name.
2010-09-03 11:21:40 +02:00
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
for ref in struct.references:
ref_split = ref.split(".")
if len(ref_split) > 2:
ref = ref_split[-2] + "." + ref_split[-1]
sphinx doc gen - use 3 column lists for inherited props, funcs and for references to save on vertical space. - use the blender version string for the upload path and PDF name.
2010-09-03 11:21:40 +02:00
fw(" * :class:`%s`\n" % ref)
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
fw("\n")
for struct in structs.values():
update for missing docs & dont include operator classes in sphinx docs.
2010-02-16 16:01:34 +01:00
# TODO, rna_info should filter these out!
if "_OT_" in struct.identifier:
continue
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
write_struct(struct)
rna/py/reference doc improvements.. - vectors now respect min/max settings. - keyframing and adding drivers raises an error in an index is set on a non array, keyframing raises an error if it fails. reference docs... - added docstrings for remaining python bpy_struct functions - added fake class for docs, bpy_struct, which is the base class of everything in bpy.types - improved inherictance references for struct classes, include bpy_struct members.
2010-04-10 20:35:50 +02:00
# special case, bpy_struct
if _BPY_STRUCT_FAKE:
filepath = os.path.join(BASEPATH, "bpy.types.%s.rst" % _BPY_STRUCT_FAKE)
file = open(filepath, "w")
fw = file.write
fw("%s\n" % _BPY_STRUCT_FAKE)
fw("=" * len(_BPY_STRUCT_FAKE) + "\n")
fw("\n")
fw(".. module:: bpy.types\n")
fw("\n")
subclass_ids = [s.identifier for s in structs.values() if s.base is None if not rna_info.rna_id_ignore(s.identifier)]
if subclass_ids:
fw("subclasses --- \n" + ", ".join([(":class:`%s`" % s) for s in sorted(subclass_ids)]) + "\n\n")
== python api docs == * source/gameengine/PyDoc/bge.types.rst: KX_PolygonMaterial was missing the parent class indication (PyObjectPlus) * source/blender/python/doc/sphinx_doc_gen.py: * unified all the "undocumented" descriptions, like http://www.blender.org/documentation/250PythonDoc/bpy.ops.anim.html#bpy.ops.anim.keyframe_delete_button so that it will be easy for Alex to CCS 'em and also now people will have a link to contribute descriptions, see http://wiki.blender.org/index.php/Dev:2.5/Py/API/Documentation/Contribute * moved the note about bpy_struct not being available in the api in a proper note directive, so that it's more evident (I didn't see it at first)
2010-06-12 00:41:13 +02:00
fw(".. class:: %s\n\n" % _BPY_STRUCT_FAKE)
fw(" built-in base class for all classes in bpy.types.\n\n")
fw(" .. note::\n\n")
fw(" Note that bpy.types.%s is not actually available from within blender, it only exists for the purpose of documentation.\n\n" % _BPY_STRUCT_FAKE)
rna/py/reference doc improvements.. - vectors now respect min/max settings. - keyframing and adding drivers raises an error in an index is set on a non array, keyframing raises an error if it fails. reference docs... - added docstrings for remaining python bpy_struct functions - added fake class for docs, bpy_struct, which is the base class of everything in bpy.types - improved inherictance references for struct classes, include bpy_struct members.
2010-04-10 20:35:50 +02:00
descr_items = [(key, descr) for key, descr in sorted(bpy.types.Struct.__bases__[0].__dict__.items()) if not key.startswith("__")]
for key, descr in descr_items:
if type(descr) == MethodDescriptorType: # GetSetDescriptorType, GetSetDescriptorType's are not documented yet
py_descr2sphinx(" ", fw, descr, "bpy.types", _BPY_STRUCT_FAKE, key)
for key, descr in descr_items:
if type(descr) == GetSetDescriptorType:
py_descr2sphinx(" ", fw, descr, "bpy.types", _BPY_STRUCT_FAKE, key)
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
== python api docs == - small change to indicate the source file we use the proper :file: directive and we link to proper file in svn check for example http://www.blender.org/documentation/250PythonDoc/bpy.ops.cloth.html#bpy.ops.cloth.preset_add after you rebuild the docs
2010-06-04 15:47:56 +02:00
# operators
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
def write_ops():
== python api docs == - small change to indicate the source file we use the proper :file: directive and we link to proper file in svn check for example http://www.blender.org/documentation/250PythonDoc/bpy.ops.cloth.html#bpy.ops.cloth.preset_add after you rebuild the docs
2010-06-04 15:47:56 +02:00
API_BASEURL='https://svn.blender.org/svnroot/bf-blender/trunk/blender/release/scripts'
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
fw = None
last_mod = ''
for op_key in sorted(ops.keys()):
op = ops[op_key]
if last_mod != op.module_name:
filepath = os.path.join(BASEPATH, "bpy.ops.%s.rst" % op.module_name)
file = open(filepath, "w")
fw = file.write
title = "%s Operators" % (op.module_name[0].upper() + op.module_name[1:])
fw("%s\n%s\n\n" % (title, "=" * len(title)))
fw(".. module:: bpy.ops.%s\n\n" % op.module_name)
last_mod = op.module_name
rna/py/reference doc improvements.. - vectors now respect min/max settings. - keyframing and adding drivers raises an error in an index is set on a non array, keyframing raises an error if it fails. reference docs... - added docstrings for remaining python bpy_struct functions - added fake class for docs, bpy_struct, which is the base class of everything in bpy.types - improved inherictance references for struct classes, include bpy_struct members.
2010-04-10 20:35:50 +02:00
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
args_str = ", ".join([prop.get_arg_default(force=True) for prop in op.args])
fw(".. function:: %s(%s)\n\n" % (op.func_name, args_str))
== python api docs == * source/gameengine/PyDoc/bge.types.rst: KX_PolygonMaterial was missing the parent class indication (PyObjectPlus) * source/blender/python/doc/sphinx_doc_gen.py: * unified all the "undocumented" descriptions, like http://www.blender.org/documentation/250PythonDoc/bpy.ops.anim.html#bpy.ops.anim.keyframe_delete_button so that it will be easy for Alex to CCS 'em and also now people will have a link to contribute descriptions, see http://wiki.blender.org/index.php/Dev:2.5/Py/API/Documentation/Contribute * moved the note about bpy_struct not being available in the api in a proper note directive, so that it's more evident (I didn't see it at first)
2010-06-12 00:41:13 +02:00
# if the description isn't valid, we output the standard warning
# with a link to the wiki so that people can help
if not op.description or op.description == "(undocumented operator)":
== python api docs == * source/blender/python/doc/sphinx_doc_gen.py: changed the "undocumented" message so that it still links to http://wiki.blender.org/index.php/Dev:2.5/Py/API/Documentation/Contribute but uses flags in the url to help documenting. Example: http://www.blender.org/documentation/250PythonDoc/bpy.ops.node.html#bpy.ops.node.link click on "contribute", the new section has title "bpy.ops.node.link" and a howto message is shown * source/blender/python/intern/bpy.c: fixed a typo
2010-06-15 04:06:01 +02:00
operator_description = undocumented_message('bpy.ops',op.module_name,op.func_name)
== python api docs == * source/gameengine/PyDoc/bge.types.rst: KX_PolygonMaterial was missing the parent class indication (PyObjectPlus) * source/blender/python/doc/sphinx_doc_gen.py: * unified all the "undocumented" descriptions, like http://www.blender.org/documentation/250PythonDoc/bpy.ops.anim.html#bpy.ops.anim.keyframe_delete_button so that it will be easy for Alex to CCS 'em and also now people will have a link to contribute descriptions, see http://wiki.blender.org/index.php/Dev:2.5/Py/API/Documentation/Contribute * moved the note about bpy_struct not being available in the api in a proper note directive, so that it's more evident (I didn't see it at first)
2010-06-12 00:41:13 +02:00
else:
operator_description = op.description
fw(" %s\n\n" % operator_description)
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
for prop in op.args:
fixed sphinx doc generator - arguments, return values indentation means they get correctly interpreted by sphinx - functions with no return values were displaying return as () - return values were getting the '(optional)' added in some cases. Example: http://www.blender.org/documentation/250PythonDoc/bpy.ops.object.html
2010-01-17 21:59:35 +01:00
write_param(" ", fw, prop)
* sphinx docgen * py_function_args wasnt working right (was using function namespace for function args), use pythons inspect module instead. move the function to get a type description into rna_info
2009-12-26 17:47:25 +01:00
if op.args:
fw("\n")
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
location = op.get_location()
if location != (None, None):
== python api docs == - small change to indicate the source file we use the proper :file: directive and we link to proper file in svn check for example http://www.blender.org/documentation/250PythonDoc/bpy.ops.cloth.html#bpy.ops.cloth.preset_add after you rebuild the docs
2010-06-04 15:47:56 +02:00
fw(" :file: `%s <%s/%s>`_:%d\n\n" % (location[0],API_BASEURL,location[0],location[1]))
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
write_ops()
file.close()
Minor sphinx corrections: * Attributes starting with _ in classes are now ignored * sphinx.blend updated so that it doesn't have to be edited anymore if the script changes
2010-07-19 15:36:10 +02:00
def main():
import bpy
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
if 'bpy' not in dir():
print("\nError, this script must run from inside blender2.5")
print(script_help_msg)
else:
Mathutils doc improvements + other small things - bpy.app moved into PyStructSequence (used by sys.float_info) - added buildinfo into bpy.app.build_* - bpy.ui removed (wasnt used) - include external example files in Mathutils docs (only Mathutils and Vector are currently written) - added support to auto document PyStructSequence's - CMake had "'s inside all its strings.
2010-01-31 22:52:26 +01:00
import shutil
path_in = 'source/blender/python/doc/sphinx-in'
sphinx doc generation - include default values as well as min/max. - partial rebuilds, so we dont have to build all docs each time, only the changed files.
2010-05-03 17:52:15 +02:00
path_out = 'source/blender/python/doc/sphinx-out'
examples for autogenerated docs are now implicit and used when available. This means adding the file "bpy.props.py" in the examples dir will automatically be used when generating docs, unused examples give warnings.
2010-02-28 14:45:08 +01:00
path_examples = 'source/blender/python/doc/examples'
sphinx doc generation - include default values as well as min/max. - partial rebuilds, so we dont have to build all docs each time, only the changed files.
2010-05-03 17:52:15 +02:00
# only for partial updates
path_in_tmp = path_in + "-tmp"
Mathutils doc improvements + other small things - bpy.app moved into PyStructSequence (used by sys.float_info) - added buildinfo into bpy.app.build_* - bpy.ui removed (wasnt used) - include external example files in Mathutils docs (only Mathutils and Vector are currently written) - added support to auto document PyStructSequence's - CMake had "'s inside all its strings.
2010-01-31 22:52:26 +01:00
building docs failed when the output directory didnt alredy exist.
2010-05-09 19:18:57 +02:00
if not os.path.exists(path_in):
os.mkdir(path_in)
examples for autogenerated docs are now implicit and used when available. This means adding the file "bpy.props.py" in the examples dir will automatically be used when generating docs, unused examples give warnings.
2010-02-28 14:45:08 +01:00
for f in os.listdir(path_examples):
if f.endswith(".py"):
EXAMPLE_SET.add(os.path.splitext(f)[0])
Mathutils doc improvements + other small things - bpy.app moved into PyStructSequence (used by sys.float_info) - added buildinfo into bpy.app.build_* - bpy.ui removed (wasnt used) - include external example files in Mathutils docs (only Mathutils and Vector are currently written) - added support to auto document PyStructSequence's - CMake had "'s inside all its strings.
2010-01-31 22:52:26 +01:00
sphinx doc generation - include default values as well as min/max. - partial rebuilds, so we dont have to build all docs each time, only the changed files.
2010-05-03 17:52:15 +02:00
# only for full updates
if _BPY_FULL_REBUILD:
shutil.rmtree(path_in, True)
shutil.rmtree(path_out, True)
else:
# write here, then move
shutil.rmtree(path_in_tmp, True)
rna2sphinx(path_in_tmp)
if not _BPY_FULL_REBUILD:
import filecmp
# now move changed files from 'path_in_tmp' --> 'path_in'
file_list_path_in = set(os.listdir(path_in))
file_list_path_in_tmp = set(os.listdir(path_in_tmp))
# remove deprecated files that have been removed.
for f in sorted(file_list_path_in):
if f not in file_list_path_in_tmp:
print("\tdeprecated: %s" % f)
os.remove(os.path.join(path_in, f))
# freshen with new files.
for f in sorted(file_list_path_in_tmp):
f_from = os.path.join(path_in_tmp, f)
f_to = os.path.join(path_in, f)
do_copy = True
if f in file_list_path_in:
if filecmp.cmp(f_from, f_to):
do_copy = False
if do_copy:
print("\tupdating: %s" % f)
shutil.copy(f_from, f_to)
'''else:
print("\tkeeping: %s" % f) # eh, not that useful'''
examples for autogenerated docs are now implicit and used when available. This means adding the file "bpy.props.py" in the examples dir will automatically be used when generating docs, unused examples give warnings.
2010-02-28 14:45:08 +01:00
EXAMPLE_SET_UNUSED = EXAMPLE_SET - EXAMPLE_SET_USED
if EXAMPLE_SET_UNUSED:
print("\nUnused examples found in '%s'..." % path_examples)
for f in EXAMPLE_SET_UNUSED:
print(" %s.py" % f)
print(" %d total\n" % len(EXAMPLE_SET_UNUSED))
sphinx rna api documentation generator to replace epydocs - view docs menu item opens sphinx URL - can be searched (even when local) - uses rna_info module for introspection - also documents python defined functions and decorator properties (defined in bpy_types.py) - experemental python file:line references for python operators.
2009-12-25 16:50:53 +01:00
import sys
sys.exit()
Minor sphinx corrections: * Attributes starting with _ in classes are now ignored * sphinx.blend updated so that it doesn't have to be edited anymore if the script changes
2010-07-19 15:36:10 +02:00
if __name__ == '__main__':
main()