User manual including toolchain for auto-generation

.doc/README.md

@@ -0,0 +1,48 @@
+Setup documentation build system
+--------------------------------
+
+Source docs
+-----------
+Install required packages
+```
+npm install jsdoc libxmljs-mt libxml-xsd easyimage
+```
+
+generate doc with
+```
+grunt apt-doc
+```
+
+User Manual
+-----------
+Install libxml2, libxslt development files and plantuml (e.g. `apt-get install libxml2-dev libxslt-dev plantuml`)
+Install required python3 packages specified in .doc/docutils/requirements.txt
+Note: pip install sh must be installed as root `sudo pip install sh`
+(and python3 if it is not installed on your system)
+
+generate doc with: 
+```
+sphinx-build -b html doc/manual/de/rst/ doc/manual/de/html
+```
+
+Translation
+-----------
+```
+# update po files
+pygettext -d cv -p locale/ .doc/docutils/directives/*.py
+# translate with poedit + save
+```
+
+TODOs
+-----
+
+TODO: possibility to map attribute names to links
+TODO: improve element description retrieval from XSD, possibility to extend
+TODO: transfer content from wiki
+TODO: establish structure for manual (done for widgets)
+TODO: cleanup, doc
+
+Optional
+--------
+
+ * auto-generate english widget descriptions from jsdoc

.doc/browser-setup.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+
+if [ "$CV_BROWSER" = "" ]; then
+    exit 0
+fi
+
+if [ $CV_BROWSER = Firefox ]; then
+    wget -O /tmp/firefox.tar.bz2 "https://download.mozilla.org/?product=firefox-${CV_VERSION}&lang=en-US&os=linux64"
+    tar xf /tmp/firefox.tar.bz2
+else
+    wget -O /tmp/chrome.deb https://dl.google.com/linux/direct/google-chrome-${CV_VERSION}_current_amd64.deb
+    dpkg --extract /tmp/chrome.deb chrome-x
+    if [ $CV_VERSION = stable ]; then
+        mv chrome-x/opt/google/chrome chrome
+        mv chrome/google-chrome chrome/google-chrome-stable
+    else
+        mv chrome-x/opt/google/chrome-$CV_VERSION chrome
+        rm chrome/google-chrome
+    fi
+    ln -s google-chrome-$CV_VERSION chrome/google-chrome
+fi

.doc/deploy.sh

@@ -0,0 +1,70 @@
+#!/bin/bash
+set -e # Exit with nonzero exit code if anything fails
+
+SOURCE_BRANCH="develop"
+TARGET_BRANCH="gh-pages"
+
+function createDocs {
+  sphinx-build -b html doc/manual/de out/de/manual
+  grunt jsdoc:html --targetDir=out/api
+  grunt screenshots --browserName=chrome
+  sphinx-build -b html doc/manual/de out/de/manual
+}
+
+# Pull requests and commits to other branches shouldn't try to deploy, just build to verify
+if [ "$TRAVIS_PULL_REQUEST" != "false" -o "$TRAVIS_BRANCH" != "$SOURCE_BRANCH" ]; then
+    echo "Skipping deploy;"
+    exit 0
+fi
+
+if [ "$SOURCE_BRANCH" != "master" ]; then
+    echo "ATTENTION! Deploying docs from non master branch. Please change this!!!"
+fi
+
+
+# Save some useful information
+REPO=`git config remote.origin.url`
+SSH_REPO=${REPO/https:\/\/github.com\//git@github.com:}
+SHA=`git rev-parse --verify HEAD`
+
+# Clone the existing gh-pages for this repo into out/
+# Create a new empty branch if gh-pages doesn't exist yet (should only happen on first deply)
+git clone $REPO out
+cd out
+git checkout $TARGET_BRANCH || git checkout --orphan $TARGET_BRANCH
+cd ..
+
+# Clean out existing contents
+rm -rf out/**/* || exit 0
+
+# Run our creation script
+createDocs
+
+# Now let's go have some fun with the cloned repo
+cd out
+git config user.name "Travis CI"
+git config user.email "$COMMIT_AUTHOR_EMAIL"
+
+# If there are no changes to the compiled out (e.g. this is a README update) then just bail.
+if [ -z `git diff --exit-code` ]; then
+    echo "No changes to the output on this push; exiting."
+    exit 0
+fi
+
+# Commit the "changes", i.e. the new version.
+# The delta will show diffs between new and old versions.
+git add --all .
+git commit -m "Deploy to GitHub Pages: ${SHA}"
+
+# Get the deploy key by using Travis's stored variables to decrypt deploy_key.enc
+ENCRYPTED_KEY_VAR="encrypted_${ENCRYPTION_LABEL}_key"
+ENCRYPTED_IV_VAR="encrypted_${ENCRYPTION_LABEL}_iv"
+ENCRYPTED_KEY=${!ENCRYPTED_KEY_VAR}
+ENCRYPTED_IV=${!ENCRYPTED_IV_VAR}
+openssl aes-256-cbc -K $ENCRYPTED_KEY -iv $ENCRYPTED_IV -in ../.doc/deploy_key.enc -out deploy_key -d
+chmod 600 deploy_key
+eval `ssh-agent -s`
+ssh-add deploy_key
+
+# Now that we're all set up, we can push.
+git push $SSH_REPO $TARGET_BRANCH

.doc/docutils/__init__.py

@@ -0,0 +1,15 @@
+# copyright (c) 2010-2016, Christian Mayer and the CometVisu contributers.
+#
+# This program is free software; you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by the Free
+# Software Foundation; either version 3 of the License, or (at your option)
+# any later version.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+# more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA

.doc/docutils/directives/common.py

@@ -0,0 +1,99 @@
+# -*- coding: utf-8 -*-
+
+# copyright (c) 2010-2016, Christian Mayer and the CometVisu contributers.
+#
+# This program is free software; you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by the Free
+# Software Foundation; either version 3 of the License, or (at your option)
+# any later version.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+# more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA
+
+from docutils import statemachine
+from docutils.parsers.rst import Directive
+from os import path
+from helper.schema import *
+import gettext
+gettext.install('messages', localedir='locale')
+
+type_mapping = {
+    'boolean': "true %s false" % _('or'),
+    'string': _('string'),
+    'decimal': _('decimal')
+}
+
+schema = Schema(path.join("src", "visu_config.xsd"))
+
+
+class BaseDirective(Directive):
+    locale = 'en'
+
+    def init_locale(self):
+        #locale = self.state_machine.document.settings.language_code
+        # this is a hack, but as language_code settings returns 'en' its the only known way to get the locale
+        self.locale = self.state_machine.document.settings._source.split(path.sep +"manual" + path.sep, 1)[1].split(path.sep)[0]
+        t = gettext.translation('messages', localedir='locale', languages=[self.locale])
+        t.install()
+
+
+class BaseXsdDirective(BaseDirective):
+
+    def get_cell_data(self, content):
+        return 0, 0, 0, statemachine.StringList( content.splitlines())
+
+    def normalize_values(self, values):
+        if len(values) <= 1:
+            return (" %s " % _("or")).join(values)
+        else:
+            return " ".join([", ".join(values[0:-1]), _("or"), values[-1]])
+
+    def normalize_type(self, type):
+        if type[0:4] == "xsd:":
+            type = type[4:]
+        return type_mapping[type] if type in type_mapping else type
+
+    def generate_table(self, element_name):
+        table_body = []
+        for attr in schema.get_widget_attributes(element_name):
+            if 'name' in attr.attrib:
+                name = attr.get('name')
+                atype, values = schema.get_attribute_type(attr)
+                description = schema.get_node_documentation(attr, self.locale)
+                if description is not None:
+                    description = description.text
+                else:
+                    description = ''
+            elif 'ref' in attr.attrib:
+                name = attr.get('ref')
+                type_def = schema.get_attribute(name)
+                atype, values = schema.get_attribute_type(type_def)
+                description = schema.get_node_documentation(type_def, self.locale)
+                if description is not None:
+                    description = description.text
+                else:
+                    description = ''
+
+            if attr.get('use', 'optional') == "required":
+                name += "*"
+
+            atype = self.normalize_type(atype) if len(values) == 0 else self.normalize_values(values)
+            row = [self.get_cell_data(name), self.get_cell_data(atype), self.get_cell_data(description)]
+            table_body.append(row)
+
+        if len(table_body) == 0:
+            return None
+
+        table_head = [[self.get_cell_data(_('Name')), self.get_cell_data(_('Type')), self.get_cell_data(_('Description'))]]
+        table = ([20, 20, 60], table_head, table_body)
+
+        table_node = self.state.build_table(table, self.content_offset)
+        table_node['classes'] += self.options.get('class', [])
+
+        return table_node

.doc/docutils/directives/elements_information.py

@@ -0,0 +1,73 @@
+# -*- coding: utf-8 -*-
+
+# copyright (c) 2010-2016, Christian Mayer and the CometVisu contributers.
+#
+# This program is free software; you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by the Free
+# Software Foundation; either version 3 of the License, or (at your option)
+# any later version.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+# more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA
+
+from docutils import nodes
+from docutils.parsers.rst import directives
+from common import BaseXsdDirective, schema
+import gettext
+gettext.install('cv', localedir='locale')
+
+
+class ElementsInformationDirective(BaseXsdDirective):
+    """
+    reStructuredText directive for information about allowed child elements. Extracts information for the given element from
+    the visu_config.xsd file and adds it to the document.
+
+    ..elements_information:: <element-name>
+
+    @author Tobias Bräutigam
+    @since 0.10.0
+    """
+    required_arguments = 1
+    optional_arguments = 0
+    final_argument_whitespace = True
+    option_spec = {}
+    has_content = False
+
+    def make_title(self, element):
+        if element.get("name", None) is not None:
+            name = element.get("name")
+            if element.get("minOccurs") is not None and int(element.get("minOccurs")) > 0:
+                name += "*"
+            text_nodes, messages = self.state.inline_text(name,
+                                                          self.lineno)
+            title = nodes.title(name, '', *text_nodes)
+        else:
+            title = None
+            messages = []
+        return title, messages
+
+    def run(self):
+        self.init_locale()
+
+        element_name = self.arguments[0]
+        res_nodes = []
+
+        for element in schema.get_widget_elements(element_name):
+            title, messages = self.make_title(element)
+
+            table_node = self.generate_table(element.get("name"))
+            if table_node is not None:
+                if title is not None:
+                    table_node.insert(0, title)
+
+                res_nodes.append(table_node)
+
+        return res_nodes
+
+directives.register_directive("elements_information", ElementsInformationDirective)