Meta:Tools/Sphinx/Theme

提供: wiki
移動先: 案内、 検索

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 Inprogress100.jpg 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


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

  • 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)


Sphinx specific bugs

  • none yet
「https://wiki.blender.jp/index.php?title=Meta:Tools/Sphinx/Theme&oldid=97763」から取得