From cd7e8070107670a6b1138deb3c5b672292c1c612 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tobias=20Br=C3=A4utigam?= Date: Tue, 18 Oct 2016 22:01:35 +0200 Subject: [PATCH] change doc structure to //(manual|api). Where the develop branch always builds to version = latest and the master branch to the version set in package.json. With this structure it is possible to host the documentation in different versions (including older ones). refs #416 --- .doc/commands/doc.py | 23 +++++++- .doc/config.ini | 7 ++- .doc/docutils/directives/__init__.py | 31 ++++++++++- .doc/docutils/directives/cometvisu.py | 9 ++- .doc/plugins/widget_example.js | 9 ++- src/editor/lib/DocumentationMapping.json | 70 ++++++++++++------------ 6 files changed, 105 insertions(+), 44 deletions(-) diff --git a/.doc/commands/doc.py b/.doc/commands/doc.py index d370fb41431..bfcb5003cc6 100644 --- a/.doc/commands/doc.py +++ b/.doc/commands/doc.py @@ -21,17 +21,35 @@ import logging import sh import shutil +import json from argparse import ArgumentParser from . import Command class DocGenerator(Command): + _source_version = None def __init__(self): super(DocGenerator, self).__init__() self.log = logging.getLogger("doc") logging.basicConfig(level=logging.INFO, format='%(levelname)s: %(message)s') + def _get_doc_version(self): + git = sh.Command("git") + branch = git("rev-parse", "--abbrev-ref", "HEAD").strip() + if branch == "develop": + return self.config.get("DEFAULT", "develop-version-mapping") + else: + # read version + return self._get_source_version() + + def _get_source_version(self): + if self._source_version is None: + with open("package.json") as data_file: + data = json.load(data_file) + self._source_version = data['version'] + return self._source_version + def _run(self, language, target_dir, browser, skip_screenshots=True, force=False): sphinx_build = sh.Command("sphinx-build") @@ -45,6 +63,8 @@ def _run(self, language, target_dir, browser, skip_screenshots=True, force=False target_dir = os.path.join(self.root_dir, self.config.get(section, "target")) else: target_dir = os.path.join(self.root_dir, target_dir) + target_dir = target_dir.replace("", self._get_doc_version()) + print("generating doc to %s" % target_dir) if not os.path.exists(source_dir): self.log.error("no sources found for manual (%s) in language '%s'" % (source_dir, language)) @@ -97,7 +117,8 @@ def run(self, args): if options.target is not None: grunt("api-doc", "--subDir=jsdoc", "--browserName=%s" % options.browser, "--targetDir=%s" % options.target, _out=self.process_output, _err=self.process_output) else: - grunt("api-doc", "--subDir=jsdoc", "--browserName=%s" % options.browser, _out=self.process_output, _err=self.process_output) + target_dir = self.config.get("api", "target").replace("", self._get_doc_version()) + grunt("api-doc", "--subDir=jsdoc", "--browserName=%s" % options.browser, "--targetDir=%s" % target_dir, _out=self.process_output, _err=self.process_output) else: self.log.error("generation of '%s' documentation is not available" % options.type) exit(1) \ No newline at end of file diff --git a/.doc/config.ini b/.doc/config.ini index 475084cc057..06a07fb4d23 100644 --- a/.doc/config.ini +++ b/.doc/config.ini @@ -4,9 +4,10 @@ manual-basedir=doc/manual manual-templates=doc/manual/_templates cachedir=cache/ schema-file=src/visu_config.xsd +develop-version-mapping=latest [references] -prefix=/manual/ +prefix=//manual/ target=src/editor/lib/DocumentationMapping.json [redirect] @@ -16,7 +17,7 @@ target=out/redirect-structure.map source=%(manual-basedir)s/de widgets=%(manual-basedir)s/de/config/widgets plugins=%(manual-basedir)s/de/config/widgets/plugins -target=out/docs/de/manual +target=out/de//manual source-type=rst target-type=html @@ -26,4 +27,4 @@ plugin-template=%(manual-templates)s/de/plugin-template.rst header-file=%(manual-basedir)s/de/parts/header.rst [api] -target=out/docs/api \ No newline at end of file +target=out/en//api \ No newline at end of file diff --git a/.doc/docutils/directives/__init__.py b/.doc/docutils/directives/__init__.py index 7dc0332c809..31b9e976f0e 100644 --- a/.doc/docutils/directives/__init__.py +++ b/.doc/docutils/directives/__init__.py @@ -15,4 +15,33 @@ # # 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 \ No newline at end of file +# 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA + +import sh +import json +import os +import ConfigParser + + +class Version: + _source_version = None + config = ConfigParser.ConfigParser() + config.read(os.path.join('.doc', 'config.ini')) + + @classmethod + def get_doc_version(cls): + git = sh.Command("git") + branch = git("rev-parse", "--abbrev-ref", "HEAD").strip() + if branch == "develop": + return cls.config.get("DEFAULT", "develop-version-mapping") + else: + # read version + return cls.get_source_version() + + @classmethod + def get_source_version(cls): + if cls._source_version is None: + with open("package.json") as data_file: + data = json.load(data_file) + cls._source_version = data['version'] + return cls._source_version \ No newline at end of file diff --git a/.doc/docutils/directives/cometvisu.py b/.doc/docutils/directives/cometvisu.py index 5e223597cbb..b70d31c4dba 100644 --- a/.doc/docutils/directives/cometvisu.py +++ b/.doc/docutils/directives/cometvisu.py @@ -26,9 +26,10 @@ from elements_information import ElementsInformationDirective from api_doc import ApiDocDirective from settings import config +from __init__ import Version references = {"_base": "http://test.cometvisu.org/CometVisu/"} -reference_prefix = config.get("references", "prefix") +reference_prefix = config.get("references", "prefix").replace("", Version.get_doc_version()) references_file = config.get("references", "target") redirect_file = config.get("redirect", "target") @@ -63,8 +64,10 @@ def process_references(app, doctree, fromdocname): def store_references(): - with open(references_file, "w") as f: - f.write(dumps(references, indent=2, sort_keys=True)) + # only update references when we build from develop branch + if Version.get_doc_version() == config.get("DEFAULT", "develop-version-mapping"): + with open(references_file, "w") as f: + f.write(dumps(references, indent=2, sort_keys=True)) def store_redirect_map(): diff --git a/.doc/plugins/widget_example.js b/.doc/plugins/widget_example.js index 4201023f8b4..09e517ef7c2 100644 --- a/.doc/plugins/widget_example.js +++ b/.doc/plugins/widget_example.js @@ -9,6 +9,13 @@ var fs = require('fs'); var path = require('path'); var xsd = require('libxml-xsd'); var libxmljs = require('libxml-xsd').libxmljs; +var ini = require('ini'); +var execSync = require('child_process').execSync; + +var branch = execSync('git rev-parse --abbrev-ref HEAD').toString().trim(); +var config = ini.parse(fs.readFileSync(path.join(".doc", "config.ini"), 'utf-8')); +var manifest = JSON.parse(fs.readFileSync('./package.json')); +var version = (branch == "develop") ? config.DEFAULT['develop-version-mapping'] : manifest.version; var configParts = { start : '', @@ -45,7 +52,7 @@ var createDir = function(dir) { }; var cacheDir = path.join("cache", "widget_examples", "jsdoc"); -var screenshotDir = path.join("out", "api", "examples"); +var screenshotDir = path.join(config.api.target.replace("", version), "examples"); createDir(cacheDir); var schemaString = fs.readFileSync(path.join("src", "visu_config.xsd"), "utf-8"); diff --git a/src/editor/lib/DocumentationMapping.json b/src/editor/lib/DocumentationMapping.json index 167c391dc4c..9bd779ee9d0 100644 --- a/src/editor/lib/DocumentationMapping.json +++ b/src/editor/lib/DocumentationMapping.json @@ -1,38 +1,38 @@ { "_base": "http://test.cometvisu.org/CometVisu/", - "audio": "/manual/config/widgets/audio/index.html#audio", - "break": "/manual/config/widgets/break/index.html#break", - "colorchooser": "/manual/config/widgets/plugins/colorchooser/index.html#colorchooser", - "designtoggle": "/manual/config/widgets/designtoggle/index.html#designtoggle", - "diagram": "/manual/config/widgets/plugins/diagram/index.html#diagram", - "flavour": "/manual/config/flavour.html#flavour", - "gauge": "/manual/config/widgets/plugins/gauge/index.html#gauge", - "image": "/manual/config/widgets/image/index.html#image", - "imagetrigger": "/manual/config/widgets/imagetrigger/index.html#imagetrigger", - "include": "/manual/config/widgets/include/index.html#include", - "info": "/manual/config/widgets/info/index.html#info", - "infotrigger": "/manual/config/widgets/infotrigger/index.html#infotrigger", - "install-no-pakets": "/manual/install/install-dev.html#install-no-pakets", - "line": "/manual/config/widgets/line/index.html#line", - "mapping": "/manual/config/mapping.html#mapping", - "multitrigger": "/manual/config/widgets/multitrigger/index.html#multitrigger", - "page": "/manual/config/widgets/page/index.html#page", - "powerspectrum": "/manual/config/widgets/plugins/powerspectrum/index.html#powerspectrum", - "pushbutton": "/manual/config/widgets/pushbutton/index.html#pushbutton", - "refresh": "/manual/config/widgets/refresh/index.html#refresh", - "reload": "/manual/config/widgets/reload/index.html#reload", - "rgb": "/manual/config/widgets/rgb/index.html#rgb", - "slide": "/manual/config/widgets/slide/index.html#slide", - "strftime": "/manual/config/widgets/plugins/strftime/index.html#strftime", - "styling": "/manual/config/styling.html#styling", - "switch": "/manual/config/widgets/switch/index.html#switch", - "system-voraussetzungen": "/manual/#system-voraussetzungen", - "text": "/manual/config/widgets/text/index.html#text", - "toggle": "/manual/config/widgets/toggle/index.html#toggle", - "trigger": "/manual/config/widgets/trigger/index.html#trigger", - "urltrigger": "/manual/config/widgets/urltrigger/index.html#urltrigger", - "video": "/manual/config/widgets/video/index.html#video", - "visu-config-details": "/manual/config/index.html#visu-config-details", - "web": "/manual/config/widgets/web/index.html#web", - "widgets": "/manual/config/widgets/index.html#widgets" + "audio": "/latest/manual/config/widgets/audio/index.html#audio", + "break": "/latest/manual/config/widgets/break/index.html#break", + "colorchooser": "/latest/manual/config/widgets/plugins/colorchooser/index.html#colorchooser", + "designtoggle": "/latest/manual/config/widgets/designtoggle/index.html#designtoggle", + "diagram": "/latest/manual/config/widgets/plugins/diagram/index.html#diagram", + "flavour": "/latest/manual/config/flavour.html#flavour", + "gauge": "/latest/manual/config/widgets/plugins/gauge/index.html#gauge", + "image": "/latest/manual/config/widgets/image/index.html#image", + "imagetrigger": "/latest/manual/config/widgets/imagetrigger/index.html#imagetrigger", + "include": "/latest/manual/config/widgets/include/index.html#include", + "info": "/latest/manual/config/widgets/info/index.html#info", + "infotrigger": "/latest/manual/config/widgets/infotrigger/index.html#infotrigger", + "install-no-pakets": "/latest/manual/install/install-dev.html#install-no-pakets", + "line": "/latest/manual/config/widgets/line/index.html#line", + "mapping": "/latest/manual/config/mapping.html#mapping", + "multitrigger": "/latest/manual/config/widgets/multitrigger/index.html#multitrigger", + "page": "/latest/manual/config/widgets/page/index.html#page", + "powerspectrum": "/latest/manual/config/widgets/plugins/powerspectrum/index.html#powerspectrum", + "pushbutton": "/latest/manual/config/widgets/pushbutton/index.html#pushbutton", + "refresh": "/latest/manual/config/widgets/refresh/index.html#refresh", + "reload": "/latest/manual/config/widgets/reload/index.html#reload", + "rgb": "/latest/manual/config/widgets/rgb/index.html#rgb", + "slide": "/latest/manual/config/widgets/slide/index.html#slide", + "strftime": "/latest/manual/config/widgets/plugins/strftime/index.html#strftime", + "styling": "/latest/manual/config/styling.html#styling", + "switch": "/latest/manual/config/widgets/switch/index.html#switch", + "system-voraussetzungen": "/latest/manual/#system-voraussetzungen", + "text": "/latest/manual/config/widgets/text/index.html#text", + "toggle": "/latest/manual/config/widgets/toggle/index.html#toggle", + "trigger": "/latest/manual/config/widgets/trigger/index.html#trigger", + "urltrigger": "/latest/manual/config/widgets/urltrigger/index.html#urltrigger", + "video": "/latest/manual/config/widgets/video/index.html#video", + "visu-config-details": "/latest/manual/config/index.html#visu-config-details", + "web": "/latest/manual/config/widgets/web/index.html#web", + "widgets": "/latest/manual/config/widgets/index.html#widgets" } \ No newline at end of file