Add Documentation support to the JS command

diff --git a/README.md b/README.md
index 0348522..9c47937 100644 (file)
--- a/README.md
+++ b/README.md
@@ -250,6 +250,11 @@ Compile the JS modules in Atto
     mdk js shift --plugin editor_atto
 
 
+Generate the complete YUI API documentation
+
+    mdk js doc
+
+
 phpunit
 -------
 

diff --git a/config-dist.json b/config-dist.json
index 352a93e..1f6aa55 100644 (file)
--- a/config-dist.json
+++ b/config-dist.json
@@ -157,6 +157,8 @@
     "dataDir": "moodledata",
     // The name of the www directory
     "wwwDir": "moodle",
+    // The name of the js documentation directory
+    "jsDocDir": "yuidocs",
 
     // The default engine to use when not specified
     "defaultEngine": "mysqli",
@@ -173,6 +175,8 @@
     "lessc": "/usr/local/bin/lessc",
     // Path to shifter
     "shifter": "/usr/bin/shifter",
+    // Path to yuidoc
+    "yuidoc": "/usr/bin/yuidoc",
     // Path to your favourite editor. Set to null to guess it from the System environment.
     "editor": null,
 

diff --git a/lib/commands/js.py b/lib/commands/js.py
index e60fdb6..d2d0a3f 100644 (file)
--- a/lib/commands/js.py
+++ b/lib/commands/js.py
@@ -82,6 +82,22 @@ class JsCommand(Command):
                                     }
                                 )
                             ]
+                        ),
+                        'doc': (
+                            {
+                                'help': 'keen to generate documentation?'
+                            },
+                            [
+                                (
+                                    ['names'],
+                                    {
+                                        'default': None,
+                                        'help': 'name of the instances',
+                                        'metavar': 'names',
+                                        'nargs': '*'
+                                    }
+                                )
+                            ]
                         )
                     }
             }
@@ -92,6 +108,8 @@ class JsCommand(Command):
     def run(self, args):
         if args.mode == 'shift':
             self.shift(args)
+        if args.mode == 'doc':
+            self.document(args)
 
 
     def shift(self, args):
@@ -155,6 +173,24 @@ class JsCommand(Command):
             finally:
                 observer.join()
 
+    def document(self, args):
+        """The docmentation mode"""
+
+        Mlist = self.Wp.resolveMultiple(args.names)
+        if len(Mlist) < 1:
+            raise Exception('No instances to work on. Exiting...')
+
+        cwd = os.path.realpath(os.path.abspath(os.getcwd()))
+        mpath = Mlist[0].get('path')
+        relpath = cwd.replace(mpath, '').strip('/')
+
+        for M in Mlist:
+            if len(Mlist) > 1:
+                logging.info('Let\'s document everything you wanted on \'%s\'' % (M.get('identifier')))
+
+            processor = js.Js(M)
+            processor.document(self.Wp.getPath(M.get('identifier'), 'jsdocdir'))
+
 
 class JsShiftWatcher(watchdog.events.FileSystemEventHandler):
 

diff --git a/lib/js.py b/lib/js.py
index ba1b381..29630a9 100644 (file)
--- a/lib/js.py
+++ b/lib/js.py
@@ -62,6 +62,13 @@ class Js(object):
             shifter.setCwd(path)
             shifter.compile()
 
+    def document(self, outdir=None):
+        """Runs documentator"""
+
+        path = self._M.get('path')
+        documentor = Documentor(path, outdir)
+        documentor.compile();
+
     def getYUISrcPath(self, subsystemOrPlugin, module=None):
         """Returns the path to the module, or the component"""
 
@@ -101,6 +108,40 @@ class Shifter(object):
     def setCwd(self, cwd):
         self._cwd = cwd
 
+class Documentor(object):
+
+    _cwd = None
+
+    _outdir = None
+
+    def __init__(self, cwd=None, outdir=None):
+        self.setCwd(cwd)
+        self.setOutdir(outdir)
+
+    def compile(self):
+        """Runs the yuidoc command in cwd"""
+        executable = C.get('yuidoc')
+        if not executable or not os.path.isfile(executable):
+            raise Exception('Could not find executable path %s' % (executable))
+
+        cmd = [executable, '--outdir', self._outdir]
+
+        logging.info("Generating YUI documentation to %s. This may take a while" % self._outdir)
+        (code, out, err) = process(cmd, cwd=self._cwd)
+        if code != 0:
+            raise YuidocCompileFailed('Error whilst generating documentation')
+        else:
+            logging.info('Documentation generation complete. Take a peek at %s'
+                    % self._outdir)
+
+    def setCwd(self, cwd):
+        self._cwd = cwd
+
+    def setOutdir(self, outdir):
+        self._outdir = outdir
 
+
+class YuidocCompileFailed(Exception):
+    pass
 class ShifterCompileFailed(Exception):
     pass

diff --git a/lib/workplace.py b/lib/workplace.py
index b598f12..95ad6cc 100644 (file)
--- a/lib/workplace.py
+++ b/lib/workplace.py
@@ -36,13 +36,15 @@ C = Conf()
 
 class Workplace(object):
 
-    def __init__(self, path=None, wwwDir=None, dataDir=None):
+    def __init__(self, path=None, wwwDir=None, dataDir=None, jsDocDir=None):
         if path == None:
             path = C.get('dirs.storage')
         if wwwDir == None:
             wwwDir = C.get('wwwDir')
         if dataDir == None:
             dataDir = C.get('dataDir')
+        if jsDocDir == None:
+            jsDocDir = C.get('jsDocDir')
 
         # Directory paths
         self.path = os.path.abspath(os.path.realpath(os.path.expanduser(path)))
@@ -55,6 +57,7 @@ class Workplace(object):
         # Directory names
         self.wwwDir = wwwDir
         self.dataDir = dataDir
+        self.jsDocDir = jsDocDir
 
     def checkCachedClones(self, stable=True, integration=True):
         """Clone the official repository in a local cache"""
@@ -97,6 +100,7 @@ class Workplace(object):
         installDir = os.path.join(self.path, name)
         wwwDir = os.path.join(installDir, self.wwwDir)
         dataDir = os.path.join(installDir, self.dataDir)
+        jsDocDir = os.path.join(installDir, self.jsDocDir)
         linkDir = os.path.join(self.www, name)
 
         if self.isMoodle(name):
@@ -109,6 +113,7 @@ class Workplace(object):
         mkdir(installDir, 0755)
         mkdir(wwwDir, 0755)
         mkdir(dataDir, 0777)
+        mkdir(jsDocDir, 0777)
 
         repository = self.getCachedRemote(integration)
 
@@ -236,6 +241,8 @@ class Workplace(object):
             return os.path.join(base, self.wwwDir)
         elif mode == 'data':
             return os.path.join(base, self.dataDir)
+        elif mode == 'jsdocdir':
+            return os.path.join(base, self.jsDocDir)
         else:
             return base