Merge pull request #447 from peuter/vscode-rst

add Makefile to allow `make html`...

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+    "restructuredtext.confPath" : "doc/manual/de/conf.py",
+    "restructuredtext.builtDocumentationPath" : "out/preview/de",
+    "restructuredtext.updateOnTextChanged" : "true"
+}

cv

@@ -18,12 +18,13 @@
 # 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA
 import sys
 import json
+import os
 from argparse import ArgumentParser
 from utils.commands.doc import DocGenerator
 from utils.commands.scaffolding import Scaffolder
 from utils.commands.translation import TranslationHandler
 
-with open("package.json") as data_file:
+with open(os.path.join(os.path.dirname(os.path.abspath(__file__)), "package.json")) as data_file:
     data = json.load(data_file)
     VERSION = data['version']
 

doc/manual/de/Makefile

@@ -0,0 +1,13 @@
+# Makefile for Sphinx documentation
+#
+
+.PHONY: help
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+
+.PHONY: html
+html:
+	../../../cv doc -l de --target out/preview/de
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

doc/manual/de/colab/index.rst

@@ -119,6 +119,28 @@ Mit dem Wissen dieses Abschnitts sollte es möglich sein, eigene Beiträge für
 
     * Lokales Erzeugen der HTML-Doku, inkl. Screenshots
 
+Dokumentation schreiben mit VisualStudio Code
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Der Editor `Visual Studio Code <https://code.visualstudio.com>`__ bietet ein Plugin, mit dessen Hilfe man sich eine
+Live Preview der geschriebenen Dokumentation anzeigen lassen kann. Dazu muss zunächst der Editor installiert werden und
+darin die Extension ``restructuredtext`` (über den Menüpunkt Anzeigen -> Extensions suchen nach rst) installiert werden.
+Nach einmaligem Neuladen des Editors steht diese zur Verfügung. 
+
+
+Damit die Live Preview funktioniert muss Python installiert sein.
+Eine Anleitung um die nötigen Vorraussetzungen zu schaffen findet man hier: 
+`Install Sphinx <https://github.com/vscode-restructuredtext/vscode-restructuredtext/blob/master/docs/sphinx.md>`__
+
+
+Ist alles korrekt eingerichtet, kann man eine RST-Datei aus der Dokumentation öffnen und mit ``Strg+Shift r`` das Live-Preview Fenster öffnen.
+Änderungen an der RST-Datei, sollten dann mit kurzer Verzögerung automatisch in Preview Fenster zu sehen sein.
+
+.. figure:: doc/_static/visual_studio_live_preview.png
+
+   Ansicht des Editors mit Live-Preview
+
+
 Mithilfe bei der Entwicklung
 ----------------------------
 

utils/commands/__init__.py

@@ -32,8 +32,8 @@ class Command(object):
 
     def __init__(self):
         self.config = ConfigParser.ConfigParser()
-        self.config.read(os.path.join('utils', 'config.ini'))
         self.root_dir = os.path.abspath(os.path.join(os.path.realpath(os.path.dirname(__file__)), '..', '..'))
+        self.config.read(os.path.join(self.root_dir, 'utils', 'config.ini'))
 
     def init_locale(self, lang):
         t = gettext.translation('messages', localedir=self.config.get("DEFAULT", "locale"), languages=[lang])

utils/commands/doc.py

@@ -33,6 +33,9 @@
 from . import Command
 from scaffolding import Scaffolder
 
+root_dir = os.path.abspath(os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", ".."))
+
+
 class DocParser:
     """
     Parse an existing rst file, recognize placeholder section and allow
@@ -41,7 +44,7 @@ class DocParser:
 
     def __init__(self, widget=None, plugin=None):
         self.config = ConfigParser.ConfigParser()
-        self.config.read(os.path.join('utils', 'config.ini'))
+        self.config.read(os.path.join(root_dir, 'utils', 'config.ini'))
         self.sections = {}
         self.lines = []
         self.replacements = {}
@@ -132,7 +135,7 @@ def _get_doc_version(self):
 
     def _get_source_version(self):
         if self._source_version is None:
-            with open("package.json") as data_file:
+            with open(os.path.join(self.root_dir, "package.json")) as data_file:
                 data = json.load(data_file)
                 self._source_version = data['version']
         return self._source_version

utils/docutils/directives/__init__.py

@@ -22,11 +22,12 @@
 import os
 import ConfigParser
 
+root_dir = os.path.abspath(os.path.join(os.path.realpath(os.path.dirname(__file__)), '..', '..', '..'))
 
 class Version:
     _source_version = None
     config = ConfigParser.ConfigParser()
-    config.read(os.path.join('utils', 'config.ini'))
+    config.read(os.path.join(root_dir, 'utils', 'config.ini'))
 
     @classmethod
     def get_doc_version(cls):
@@ -43,7 +44,7 @@ def get_doc_version(cls):
     @classmethod
     def get_source_version(cls):
         if cls._source_version is None:
-            with open("package.json") as data_file:
+            with open(os.path.join(root_dir, "package.json")) as data_file:
                 data = json.load(data_file)
                 cls._source_version = data['version']
         return cls._source_version

utils/docutils/directives/api_doc.py

@@ -22,7 +22,7 @@
 from docutils.parsers.rst import Directive, nodes
 from docutils import statemachine
 import gettext
-from settings import config
+from settings import config, root_dir
 
 kwargs = {}
 if sys.version_info[0] < 3:
@@ -57,7 +57,7 @@ def init_part_translations(self):
 
     def init_locale(self):
         self.locale = self.state.document.settings.env.config.language
-        t = gettext.translation('messages', localedir=config.get("DEFAULT", "locale"), languages=[self.locale], codeset='utf-8')
+        t = gettext.translation('messages', localedir=os.path.join(root_dir, config.get("DEFAULT", "locale")), languages=[self.locale], codeset='utf-8')
         t.install(**kwargs)
 
         self.init_part_translations()
@@ -76,10 +76,10 @@ def run(self):
             doc_parts = [self.arguments[1]]
 
         # find widget
-        widget_path = os.path.join("src", "structure", "pure", "%s.js" % widget_name)
+        widget_path = os.path.join(root_dir, "src", "structure", "pure", "%s.js" % widget_name)
         if not os.path.exists(widget_path):
             # try plugin
-            widget_path = os.path.join("src", "plugins", widget_name, "structure_plugin.js")
+            widget_path = os.path.join(root_dir, "src", "plugins", widget_name, "structure_plugin.js")
 
         if not os.path.exists(widget_path):
             print("No widget or plugin named '%s' found" % widget_name)

utils/docutils/directives/cometvisu.py

@@ -25,13 +25,13 @@
 from parameter_information import ParameterInformationDirective
 from elements_information import ElementsInformationDirective
 from api_doc import ApiDocDirective
-from settings import config
+from settings import config, root_dir
 from __init__ import Version
 
 references = {"_base": "http://test.cometvisu.org/CometVisu/"}
 reference_prefix = config.get("references", "prefix").replace("<version>", Version.get_doc_version())
-references_file = config.get("references", "target")
-redirect_file = config.get("redirect", "target")
+references_file = os.path.join(root_dir, config.get("references", "target"))
+redirect_file = os.path.join(root_dir, config.get("redirect", "target"))
 
 default_ref = re.compile("^index-[0-9]+$")
 redirect_map = {}

utils/docutils/directives/common.py

@@ -22,15 +22,16 @@
 import gettext
 import sys
 import re
-from settings import config
+import os
+from settings import config, root_dir
 
 kwargs = {}
 if sys.version_info[0] < 3:
     kwargs['unicode'] = True
 
 gettext.install('messages', **kwargs)
 
-schema = Schema(config.get("DEFAULT", "schema-file"))
+schema = Schema(os.path.join(root_dir, config.get("DEFAULT", "schema-file")))
 
 
 class BaseDirective(Directive):
@@ -50,7 +51,7 @@ def init_type_mapping(self):
 
     def init_locale(self):
         self.locale = self.state.document.settings.env.config.language
-        t = gettext.translation('messages', localedir=config.get("DEFAULT", "locale"), languages=[self.locale])
+        t = gettext.translation('messages', localedir=os.path.join(root_dir, config.get("DEFAULT", "locale")), languages=[self.locale])
         t.install(**kwargs)
 
         self.init_type_mapping()

utils/docutils/directives/settings.py

@@ -19,5 +19,7 @@
 import os
 import configparser
 
+root_dir = os.path.abspath(os.path.join(os.path.realpath(os.path.dirname(__file__)), '..', '..', '..'))
+
 config = configparser.ConfigParser()
-config.read(os.path.join('utils', 'config.ini'))
+config.read(os.path.join(root_dir, 'utils', 'config.ini'))

utils/docutils/directives/widget_example.py

@@ -18,7 +18,7 @@
 
 
 import json
-
+import os
 from lxml import etree
 from docutils import nodes, statemachine
 from sphinx.util.nodes import set_source_info
@@ -27,11 +27,11 @@
 from docutils.utils.code_analyzer import Lexer, LexerError, NumberLines
 from os import path, makedirs
 from io import open
-from settings import config
+from settings import config, root_dir
 
 counters = {}
 
-xsd = etree.XMLSchema(etree.parse(config.get("DEFAULT", "schema-file")))
+xsd = etree.XMLSchema(etree.parse(os.path.join(root_dir, config.get("DEFAULT", "schema-file"))))
 parser = etree.XMLParser(schema=xsd)