How to become a dojo doc ninja

Status:Draft
Version:1.2
Dojo Doc ninja

Joining the Dojo doc team is easy, all you need to do is write and get familiar with a few basics you will master fast.

Dojo Doc Syntax (reST)

Dojo doc uses the reST syntax to describe all docs, we have implemented a few features of the great reST Sphinx extension and implemented dojo-specific ones to provide cool stuff like inline code demos (Yah, you won’t believe it, but your code will just work).

Visit the official reST Quick reference.

Please note the following topics

Sections

Each new section (<h2>) should marked with:

===========
Sectionname
===========

Subsections (<h3>) should marked with:

Subsection
----------

The syntax for Subsubsections (<h4>) is:

Subsubsection
~~~~~~~~~~~~~

Code examples

Non executed code

If you need to give a simple source code example without it being executed use the ".. code-block ::" directive and put the code right into the next line indented by two spaces. If you want to display line numbers, use the "linenos" attribute.

1
2
3
4
.. code-block :: javascript
  :linenos:

  <script type="text/javascript">alert("Your code");</script>

Executed code

You can add a real example to the documentation by using the ".. codeviewer::" directive. The code you show can include JavaScript, CSS and HTML

1
2
3
4
5
6
.. codeviewer::

  <script type="text/javascript">dojo.require("dijit.form.Button");</script>
  <div class="nihilo">
     <div dojoType="dijit.form.Button">whatever</div>
  </div>

This will result in the following

<script type="text/javascript">dojo.require("dijit.form.Button");</script>
<div class="nihilo">
   <div dojoType="dijit.form.Button">whatever</div>
</div>

Executed code compounds

Sometimes your examples need separation between CSS, JavaScript and HTML. Use the ".. cv-compound::" directive for that. Each compound can include several ".. code-viewer::" directives

The valid reST syntax has to look like following markup:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
.. cv-compound::

  First we declare the CSS

  .. cv:: css
    :label: The CSS

     <style type="text/css">
     </style>

  The HTML snippet simply defines the markup of your code. Dojo will then parse the DOM nodes and create the widgets programatically.

    * Programmatic code generation
    * Dom manipulation

  .. cv:: html
    :label: This is the HTML of the example

    <div id="fohooo" class="fohooo">Click Me</div>
    <div id="fohooooooo" class="fohooo">Don't click Me</div>
    <div dojoType="foohooo" class="fohooo">Or Me</div>

  This is the JavaScript code of your example. Simply paste both HMTL and JavaScript into the browser.

  .. cv:: javascript
    :label: And the JavaScript code

    <script type="text/javascript">
    dojo.declare("foohooo", [dijit._Widget,dijit._Templated], {
       templateString: '<div dojoAttachEvent="onclick: _foo">Example: <span dojoAttachPoint="containerNode"></span></div>',
       _foo: function(){
          alert("foo");
       }
    });
    dojo.addOnLoad(function(){
      var widget = new foohooo({id: "test_foohooo"}, dojo.byId("fohooo"));
    });
    </script>

Images

To attach images, use the AttachFile option you have at the bottom of each page. Once your image is uploaded you can include it on you page using following syntax:

.. image:: yourimage.gif

Tips and Tricks, the edge cases

Many times you will encounter some question on a forum or the #dojo channel and you just want to keep a note about it with the respective answer. Those cases should be put into subpages suffixed with -tricks. So, if someone posts something interesting to know about the dijit.Dialog, and you just want to note this for other people, post it in the dijit/Dialog-tricks page. If such a page doesn't exist, feel free to create one.

Url conventions

when you find an undocumented dojo module, use the dojo namespace as the guide:

dojo.declare

should become:

dojo/declare

Or:

dijit.Tree

should become:

dijit/Tree

So be aware of case-sensitivity.

Url conventions outside the namespace

For any other part of the documentation we use lowerCamelCase:

quickstart/dataPaging