Merge pull request #148 from ev3dev/rtfd

Setup readthedocs.org documentation

README.rst

@@ -0,0 +1,28 @@
+ev3dev language bindings
+========================
+
+This repository stores the utilities and metadata information for the
+ev3dev-lang family of libraries. These libraries are easy-to-use interfaces for
+the APIs that are available on `ev3dev`_-based devices.
+
+The complete documentation is hosted at http://ev3dev-lang.readthedocs.org.
+
+We support multiple libraries for various programming languages using a
+centralized "specification" which we keep updated as kernel changes are made.
+We don't have the actual library code here (see below) -- instead we use this
+repo to facilitate the maintenance of our bindings.
+
+We currently support libraries for the following languages:
+
+- `C++`_
+- `Node.js`_
+- `Python`_
+
+Each binding is written based on our central spec, so each has a uniform
+interface which is kept close to the ev3dev API surface while still encouraging
+language-specific enhancements.
+
+.. _ev3dev: http://www.ev3dev.org
+.. _C++: https://github.com/ddemidov/ev3dev-lang-cpp
+.. _Node.js: https://github.com/wasabifan/ev3dev-lang-js
+.. _Python: https://github.com/rhempel/ev3dev-lang-python

autogen/README.rst

@@ -0,0 +1,90 @@
+Autogen scripts for ev3dev language bindings
+============================================
+
+To help us maintain our language bindings, we have written a script to
+automatically update sections of code according to changes in our API
+specification. We define code templates using Liquid_, which are stored in the
+``templates`` folder with the ``.liquid`` extension.
+
+.. _Liquid: http://liquidmarkup.org
+
+Usage
+-----
+
+Prerequisites
+#############
+
+- Make sure that you have cloned the repo (including submodules) and ``cd``'d
+  into the autogen directory
+- You must have Node.JS and ``npm`` installed
+- If you have not yet done so yet, run ``npm install`` to install the
+  dependencies for auto-generation
+
+Running from the command line
+#############################
+
+If you run the script without any parameters, it will look for an
+``autogen-config.json`` file in your current working directory. The
+autogen-config file specifies the locations to look for templates and source
+files.
+
+.. code-block:: bash
+
+    $ node path/to/autogen.js
+
+If you want to specify a config file manually, you can include use a full file
+path for the target JSON config file.
+
+.. code-block:: bash
+
+    $ node path/to/autogen.js other/path/to/config.json
+
+How it works
+------------
+
+Our script searches code files for comments that define blocks of code that it
+should automatically generate. The inline comment tags are formatted as follows
+(C-style comments):
+
+.. code-block:: cpp
+
+    //~autogen test-template foo.bar>tmp
+    ...
+    //~autogen
+
+After the initial declaration (``~autogen``), the rest of the comment defines
+parameters for the generation script. The first block of text up to the space
+is the file name of the template to use. The ``.liquid`` extension is
+automatically appended to the given name, and then the file is loaded and
+parsed.
+
+The rest of the comment is a space-separated list of contextual variables. The
+section before the ``>`` defines the source, and the section after defines the
+destination. The value from the source is copied to the destination, in the
+global Liquid context. This makes it possible to use a single template file to
+generate multiple classes.
+
+Implementation Notes
+--------------------
+
+.. todo::
+
+    fill this up
+
+Contributing to the autogen script
+----------------------------------
+
+Just as we welcome contributions to the language bindings in this repo, we love
+to have people update our infrastructure. If you want to make a contribution,
+here are some quick tips to get started developing.
+
+- After making a change, you should run the script and tell it to re-generate
+  some files to make sure that your changes work as expected.
+- If you are making more extensive changes, it may be helpful to create a
+  temporary regen group with some test files to be able to manually test any
+  new features or modifications.
+- Although you can use any text editor, we recommend using
+  `Visual Studio Code`_ to edit the autogen scripts. It has great autocomplete,
+  and their debug GUI works well with node.
+
+.. _Visual Studio Code: https://code.visualstudio.com

autogen/autogen.js

@@ -51,26 +51,26 @@ for (var fileIndex = 0; fileIndex < targetInfo.files.length; fileIndex++) {
 
 function getTargetFileInfo() {
     var pathCandidates = argv._.concat(process.cwd());
-    
+
     var configFilePath = pathCandidates.map(function(possiblePath) {
         var stat = fs.statSync(possiblePath);
-        
+
         if(stat.isFile())
             return path.resolve(possiblePath);
         else if (stat.isDirectory())
             return path.resolve(possiblePath, config.defaultConfigFileName);
         else
             return null;
-        
+
     }).filter(function(configPath) {
         return !!configPath && fs.existsSync(configPath);
     })[0];
-    
+
     if(!configFilePath)
         return null;
-    
+
     var loadedTargetFileInfo = JSON.parse(fs.readFileSync(configFilePath).toString());
-    
+
     return {
         templateDir: path.resolve(path.dirname(configFilePath), loadedTargetFileInfo.templateDir),
         files: loadedTargetFileInfo.files.map(function(configRelativePath) {

autogen/config.js

@@ -13,7 +13,8 @@ exports.autogenFenceComments = {
     '.java': { start: cStyleAutogenStart, end: cStyleAutogenEnd },
     '.md': { start: /<!--\s*~autogen *(.+)-->/, end: "<!-- ~autogen -->" },
     '.lua': { start: /--\s*~autogen *(.+)/, end: "-- ~autogen" },
-    '.py': { start: /#\s*~autogen *(.+)/, end: "# ~autogen" }
+    '.py': { start: /#\s*~autogen *(.+)/, end: "# ~autogen" },
+    '.rst': { start: /\.\. ~autogen *(.+)/, end: "\.\. ~autogen" }
 }
 
 exports.extraLiquidFilters = {
@@ -24,7 +25,7 @@ exports.extraLiquidFilters = {
             return group1.toUpperCase();
         });
         }
-        
+
         if(typeof input == 'string')
             return camelCaseSingle(input);
         else
@@ -66,7 +67,7 @@ exports.extraLiquidFilters = {
     },
     select: function(array, property) {
         return array.map(function(item) {
-            return utils.getProp(item, property); 
+            return utils.getProp(item, property);
         });
     },
     //filters the given collection using the provided condition statement, which is
@@ -84,4 +85,4 @@ exports.extraLiquidFilters = {
         var vm = require('vm');
         return vm.runInNewContext(expression, context || {});
     }
-};
+};

docs/_static/custom.css

@@ -0,0 +1,14 @@
+pre {
+    box-shadow: 0px 1px 6px 0px lightgray;
+}
+
+dl.class {
+    padding: 5px;
+    box-shadow: 0px 1px 6px 0px lightgray;
+}
+
+pre {
+    overflow: auto;
+    word-wrap: normal;
+    white-space: pre;
+}

docs/_templates/page.html

@@ -0,0 +1,5 @@
+{# Import the theme's layout. #}
+{% extends "!page.html" %}
+
+{# Custom CSS overrides #}
+{% set bootswatch_css_custom = ['_static/custom.css'] %}

docs/autogen.rst

@@ -0,0 +1 @@
+.. include:: ../autogen/README.rst