1 files changed, 210 insertions, 0 deletions
diff --git a/tools/addon-sdk-1.12/python-lib/cuddlefish/docs/renderapi.readme.md b/tools/addon-sdk-1.12/python-lib/cuddlefish/docs/renderapi.readme.md
new file mode 100644
index 0000000..627c2a6
--- /dev/null
+++ b/tools/addon-sdk-1.12/python-lib/cuddlefish/docs/renderapi.readme.md
@@ -0,0 +1,210 @@
+<!-- This Source Code Form is subject to the terms of the Mozilla Public
+   - License, v. 2.0. If a copy of the MPL was not distributed with this
+   - file, You can obtain one at http://mozilla.org/MPL/2.0/. -->
+
+
+This document describes the structure of the HTML generated by the renderapi.py
+tool, both for use in the API docs shown by "cfx docs" and as exported by
+"cfx sdocs". The particular HTML id and class attributes embedded in the files,
+as well as their organization, represent the interface between the tool and any
+front-end code wanting to style the docs in some particular way.
+
+renderapi generates two sorts of files:
+
+- a file called "<module-name>.div": this is the contents of the parsed
+Markdown file rendered inside a well-defined DIV tag
+
+- a file called "<module-name>.html": this is the DIV from above inserted into
+a simple HTML template that references a sample CSS file which styles the
+contents of the DIV. This CSS file is the same as the one used by the SDK
+itself.
+
+DIV tags
+--------
+The following class and id attributes are used in the DIV:
+
+renderapi uses a number of class attributes and a single id attribute in the DIV:
+
+id attribute    <module_name>"_module_api_docs"
+class attribute "api_reference"
+class attribute "module_api_docs"
+class attribute "api_header"
+class attribute "api_name"
+class attribute "api_component_group"
+class attribute "api_component"
+class attribute "datatype"
+class attribute "returns"
+class attribute "parameter_set"
+class attribute "module_description"
+
+DIV structure
+-------------
+The top level DIV is marked with the id attribute and the "module_api_docs" class
+attribute:
+
+      <div id='tabs_module_api_docs' class='module_api_docs'>
+        //module doc contents
+      </div>
+
+
+Inside this:
+
+- the first item is an <h1> heading containing the name of the module:
+
+- all "markdown" hunks (that is, all descriptive text not occurring
+inside <api></api> tags) are rendered inside a DIV marked with the
+"module-description" class attribute
+
+- all <api></api> content is rendered, enclosed in a single tag marked
+with the "api_reference" class attribute:
+
+    <div id='tabs_module_api_docs' class='module_api_docs'>
+      <div class='module_description'>
+        //descriptions
+      </div>
+        <div class='api_reference'>
+        //api reference
+      </div>
+    </div>
+
+If there is no <api></api> content, then the "api-reference" section is absent.
+
+### API Reference structure ###
+
+The first item in API reference is an <h2> heading title marked with the
+"api_header" attribute. This might have the text content "API Reference"
+(but you should not rely on that):
+
+      <div class='api_reference'>
+
+        <h2 class='api_header'>API Reference</h2>
+
+        //api contents
+
+      </div>
+
+After the title come one or more component groups.
+
+#### Component Group ####
+
+A component group is marked with the "api_component_group" attribute. The
+component group is a collection of some sort of component: for example, a group
+of classes, a group of functions, or a group of events.
+
+Each component group starts off with a header marked with the
+"api_header" attribute and is followed by one or more sections marked with the
+"api_component" attribute.
+At the top level (that is, when they are directly under the "API Reference"
+heading), the "api_header" items are <h3> headings, otherwise they are divs.
+
+    <div class='api_reference'>
+
+      <h2 class='api_header'>API Reference</h2>
+
+      <div class='api_component_group'>
+
+        <h3 class='api_header'>Classes</h3>
+
+        <div class='api_component'>
+          // the first class
+        </div>
+
+        <div class='api_component'>
+          // another class
+        </div>
+
+      </div>
+
+      <div class='api_component_group'>
+        //some different components
+
+        <h3 class='api_header'>Functions</h3>
+
+        <div class='api_component'>
+          the first function
+        </div>
+
+        <div class='api_component'>
+          another function
+        </div>
+
+      </div>
+
+    </div>
+
+#### Component ####
+
+API components represent actual objects in the API like classes, functions,
+properties and events.
+
+Each component starts with a section marked with the
+"api_name" tag, which includes the name of the component in the API: for
+example "postMessage(message)".
+
+Components at the top level (i.e., directly under h3 headings) are <h4>
+headings, otherwise they are divs.
+
+After the name, the component's contents are listed. Different sorts of
+components may have different sorts of contents: for example, a function might
+have parameters. If the component is composite then it may contain its own
+component group. For example, a class may contain methods and properties,
+which might be grouped together.
+
+    <div class='api_component'>
+
+      <h4 class='api_name'>Panel</h4>
+
+      <div class='api_component_group'>
+
+        <div class='api_header'>
+          Methods
+        </div>
+
+        <div class='api_component'>
+          show()
+        </div>
+
+      </div>
+
+    </div>
+
+Other attributes
+-----------------------------
+
+### Datatype ###
+All primitive data types, like "string" and "number", are marked with the
+"datatype" class attribute:
+
+    <div class="api_component">
+
+    <div class="api_name">
+      label : <span class="datatype">string</span>
+    </div>
+
+    <p>A required string description of the widget used for accessibility,
+    title bars, and error reporting.</p>
+
+    </div>
+
+### Returns ###
+
+Functions mark return values with the "returns" class attribute.
+
+    <div class="api_component">
+
+      <div class="api_name">
+        get()
+      </div>
+
+      Make a `GET` request.
+
+      <div class="returns">
+        Returns: <span class="datatype">Request</span>
+      </div>
+
+    </div>
+
+### Parameter_set ###
+
+Functions that take parameters mark them with the parameter_set class
+attribute.