Meta:Tools/Sphinx/Theme

Blender-org - theme for sphinx

The idea

The idea of creating this theme is to make look and feel of bpy.api docs more like blender.org to make things nice and consistent.

Since this project is in progress any comments and suggestions are welcome.

Things already done are here

Main to-do list

	TASK ( descending order )	STATUS
6	make sphinx_doc_gen.py produce correct .rst files.	on hold
5	decide a color layout for things	in progress 90%
4	adjust css indentation for funcs and methods etc.	done
3	add a link to PyAPI as you see in Dev:2.5/Source in the 1st blu bar, on the right, but with "PyAPI" in orange as the "current" link	done
2	when 1 is done, change the css to point at contents in a "_static" folder in svn	done
1	where to put the static css in our svn in order to commit it together with the blender-org folder (1 commit)	done

Content to add (manually/automatic) in rst files

• list of exceptions, like for example http://www.blender.org/documentation/250PythonDoc/mathutils.html#mathutils.Matrix.invert seems there is not way to automate this (according to campbell); then, cross-link to them properly,using exception directive
• after cambo adds deprecation data, add "added in ver X" using versionchanged and versionadded directives

Enhancements

readers feedback

• we already had a bug report after this commit (but it's not public because the user is not subscribed I guess (the mail came in to me as I'm subscribed, no idea why)

the thing is: we should add a link in the sidebar with a link to this page itself, so users can report bugs in here --mindrones 17:29, 7 June 2010 (UTC)

links' css

• in these cases bge.types.html#bge.types.SCA_KeyboardSensor.events

it might not be obvious that "keycode" is a link because it is the same as the parameters (italic, blue), or from the other side, one could try to click on parameters as they were links, and they not. Confusing. --mindrones 17:29, 7 June 2010 (UTC)

undocumented fields

• if feasible with css or js, when we have "(undocumented operator)" put it in RED, this would help maintenance

see also another case here mathutils.html#mathutils.Vector.ww for things to be put in RED

TOC

• table of contents as discussed, see mockup

elements types, inheritance, etc

• readonly attributes could have some background color to quickly see you can't set them up
• constants would be better if not indented, see blf.html#blf.CLIPPING

that woul be best as "blf.CLIPPING = 4" stop instead of another line with text

if we give constants a color code, there's no need to say it's a constant

• when a classe inherits from another one, to put the parent class name as link to the parent class: Example: bpy.types.ActionActuator.html#bpy.types.ActionActuator shows

class bpy.types.Actuator(bpy_struct)

in this case I'd like to have "bpy_struct" as a link to

bpy.types.bpy_struct.html#bpy.types.bpy_struct

instead of searching manually, or hunting in links in the list at the top of the page

so that I can navigate just by linking

maybe like this we can avoid to put the line "base class — bpy_struct" (example from bpy.types.Actuator.html#bpy.types.Actuator)

• see bpy.types.Actuator.html#bpy.types.Actuator: instead of showing a list of inherited fucntions, I'd like to see those functions as they were normal functions, but with a different color, so in this example, I'd see:
  • "name", "expanded" and "type" blocks as usual, (in orange, with functions parameters in blu, return type in grey etc)
  • "as_pointer","driver_add", "driver_remove", etc blocks exactly as I see them in
    • bpy.types.bpy_struct.html#bpy.types.bpy_struct.as_pointer
    • bpy.types.bpy_struct.html#bpy.types.bpy_struct.driver_add
    • bpy.types.bpy_struct.html#bpy.types.bpy_struct.driver_remove
    • ...etc

  but with other colors, say green instead of orange and pink insted of blue :), whatever

  MOCKUP: http://www.pasteall.org/pic/show.php?id=3693

anchors

• put the anchor ("¶") at the left of each class/method/etc, after we indented the variables it became difficult to click in a function anchor.

• in the main TOC clicking on anchors should give samae background color are normal api pages.

this is because now we link from 2.5 manual index to anchor not anymore to a specific GE page like before (see Doc:Manual#Game_Engine, link to GE api), hence when we land to GE anchor would be useful see we are at GE]

• smart anchor names, like instead of "bpy.ops.graph.html#bpy.ops.graph.smooth" I'd prefer "bpy.ops.graph.html#smooth" because it recalls "bpy.ops.graph.smooth()", has a sense when reading the URL

python code

• python css, add an autoindent as in wiki so we don't have horizontal scroll bars (see bge.render.html), this has to be discussed, maybe it is desirable

"collapsible" ideas

• making all the sections collapsible, in order to read only like (in here)

bpy.ops.anim.change_frame

bpy.ops.anim.channels_click

bpy.ops.anim.channels_collapse

etc, and clicking in them opens them, so one has a quick look and opens what he needs

• very big python panels like here bge.types.html#bge.types.KX_PolygonMaterial would be better in a collapsible area
• list of subclasses in a collapsible div to be shown in some efficient way. Some idea:
  • put a "+" symbol or a triangle or whaterver, that once clicked opens the "subclasses" div, under the description of the class

editing collaboration

• add a small "edit icon" to each field, so that one can click and go to a wiki page and sugggest editing, especially true when the field is "undocumented"

There people can add suggestions and help, and can be a revision tool for us.

example: bpy.ops.armature.html#bpy.ops.armature.extrude

the small (and unobtrusive) icon would point to http://wiki.blender.org/index.php/Meta:Sandbox/PyAPI/bpy.ops.armature

error codes

• ERROR CODES, see mathutils.html#mathutils.Matrix.invert, would be cool to add in docs a page with errors types, we should do a .rst file for this

if we do, things like "ValueError" in that note should become a link to that error code doc

Bugs or not yet implemented

sphinx_doc_gen.py specific bugs

• in here look at location=(0.0, 0.0, 0.0) is badly indented, it's desirable that we keep vectors in a line

even worse case is "layer=(False, False,.......False)

the case location=(0.0, 0.0) is possible: only 2 elements in the vector, see bpy.ops.uv.html#bpy.ops.uv.select_loop

• bpy.ops.wm.html#bpy.ops.wm.context_cycle_int: description not css-ed
• notes, warnings and "see also"s should be after everything and in this order: notes, warnings, see also
• methods, functions, lists of constants etc should be listed in alphabetical order to help scrolling them quickly

sdg.py speed up! right now sdg.py regenerates all files hence sphinx rebuilds it completely, which is SLOW: solution is to generate rst files, check them against the existing ones and update only if they're different, this way sphinx will rebuild only the needed rst and also will rebuild only needed html files

BGE specific (handwritten)

• bge.types.html needs work in general....
• second python block at bge.events.html not css-ed
• bge.render.html first 3 rows not css-ed, see bge.render.html#bge.render.KX_TEXFACE_MATERIAL
• bge.logic.html#constants non css-ed
• bge.types.html#bge.types.SCA_ISensor.status partly not css-ed
• bge.types.html#bge.types.CListValue bad css
• bge.types.html#bge.types.KX_BlenderMaterial.setBlending is weird , maybe just need proper edits in GE .rst files
• bge.types.html#bge.types.KX_ConstraintActuator.option not css-ed text, same as bge.types.html#bge.types.KX_ConstraintActuator.limit
• bge.types.html#bge.types.KX_GameObject need work
• bge.types.html#bge.types.KX_GameObject.reinstancePhysicsMesh not css-ed, same as bge.types.html#bge.types.SCA_MouseSensor.mode
• bge.types.html#bge.types.KX_MouseFocusSensor.hitUV what's this grey text?
• bge.types.html#bge.types.KX_ParentActuator.ghost not css-ed
• so elements miss a parameter explanation: see bge.types.html#bge.types.CListValue.append

Theme specific bugs

• buggy: http://www.blender.org/documentation/blender_python_api_2_55_0/bpy.types.Object.html?highlight=ray_cast#bpy.types.Object.ray_cast

• bge.types.html#bge.types.KX_PolygonMaterial.activate : more indentation to ordered lists, as in bullet lists would be better --mindrones 23:15, 7 June 2010 (UTC)

• ideasman42 reported problems here http://www.blender.org/documentation/250PythonDoc/bge.types.html#bge.types.KX_BlenderMaterial.getShader but in my local sphinx I have no problems. --mindrones 13:31, 26 June 2010 (UTC)

Sphinx specific bugs

• none yet