利用者:Mindrones/Wiki/Proposals/2012/Reference

Reference project

Team

• Mindrones
• Mont29
• Ideasman42 (hopefully, after reviewing this document :)

Reference contents

• GUI Reference
• RNA Reference

GUI Reference

For each GUI item (panels, menus, buttons, ...), we list all the related data.

With "data" we intend every kind of information, be it automatic (a tooltip) or human (an example usage).

More about the GUI reference layout

Automatic information

• Context

  (necessary conditions for this ui element to work)

  this is valid especially for properties editor menus/buttons

  • object type
  • editing mode
  • editor type
• Type
  Examples: Toggle, Expanding toggle, Radio, Checkbox, Layers, ...
• Label
• Tooltips
• Shortcut
• RNA Operator(s) called by the GUI element, with link to the API documentation.
  Example: duplicate object
  OR RNA Property affected by the GUI element.
• Position of the GUI item in the parent area (where applicable).
  Examples: position of a button in the panel, position of a panel in the toolbar, position of the toolbar in the area/editor.

Human information

• mini tutorial/example
• python snippet
• faq
• gotchas
• used algorithms/formulas
• ...

RNA Reference

This information is basically already provided in the sphinx Python API documentation.

• Item in the API doc.
  Example: duplicate object
• Python snippet

Reference deployment

Wiki

Usage

Reference wiki pages would be transcluded into other wiki pages, namely Manual pages, Tutorials pages, or other Reference pages and development pages.

Examples

• In a manual page, we want to mention the shortcut to duplicate an object. Typing "press {{Ref:GUI/Object/3DView/Object_mode/Shortcuts/Duplicate}}" would return "press ⇧ ShiftD"

• In a manual page, hovering over the words "scroll the header" might show a little popup showing how to do it (for current versions of blender, it would be "drag the header with the MMB ").

Note well By doing this, if shortcuts and commands will change, we won't need to update manual pages anymore, because mediawiki will update every page which transcludes the now modified reference pages.

Tools for writers

Very probably, reference will contain hundreds of pages. How to find a desidered reference page?

1. we would show them in the navtree:
   • when reading reference pages, as usual
   • but also when editing pages in wiki, in the sidebar on the right
2. we add the chance to copy a button reference wikitext in blender:
   • hovering on a blender GUI item. right click, choose "copy wiki reference url"
   • this would put the text {{Ref:GUI/Object/3DView/Object_mode/Shortcuts/Duplicate}} in the clipboard, so that we can mention that button in the wikitext

Blender

Usage

Reference information is served in blender itself using Helpers.

Examples

• Helper to communicate how to scroll a header
• Helper to communicate how to split an area.

Reference versioning (tbd)

Reference would be versioned per series (so 2.6, not 2.62), and each series would show the current release:

• when releasing Blender 2.63, the Reference "2.6" would be overwritten by the Reference "2.62"
• when releasing Blender 2.70, the Reference "2.69" would stay and a new Reference "2.7" would start