Merge pull request #440 from peuter/english-doc

introducing automatic english doc generation...

doc/manual/_templates/en/plugin-template.rst

@@ -0,0 +1,86 @@
+.. _%%%WIDGET_NAME_LOWER%%%:
+
+%%%HEADLINE%%%
+
+.. api-doc:: %%%WIDGET_NAME%%%
+
+Description
+-----------
+
+.. ###START-WIDGET-DESCRIPTION#### Please do not change the following content. Changes will be overwritten
+
+.. ###END-WIDGET-DESCRIPTION####
+
+
+Settings
+--------
+
+For a general understanding of how the configuration files are structured and what elements and attributes are
+it is recommended to read this section first: :ref:`visu-config-details`.
+
+The behaviour and appearance of the %%%WIDGET_NAME%%% plugins can be influenced by using certain attributes and elements.
+The following tables show the allowed attributes and elements and their possible values.
+The screenshots show, how both can be edited in the :ref:`editor <editor>`.
+
+Attributes underlined by ..... are mandatory, all the others are optional and be omitted.
+
+Allowed attributes in the %%%WIDGET_NAME%%%-element
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. parameter-information:: %%%WIDGET_NAME_LOWER%%%
+
+.. widget-example::
+    :editor: attributes
+    :scale: 75
+    :align: center
+
+    <caption>Attributes in the editor (simple view) [#f1]_</caption>
+    <meta>
+        <plugins>
+            <plugin name="%%%WIDGET_NAME_LOWER%%%" />
+        </plugins>
+    </meta>
+    <%%%WIDGET_NAME_LOWER%%%>
+        <layout colspan="4" />
+    </%%%WIDGET_NAME_LOWER%%%>
+
+
+Allowed child-elements und their attributes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. elements-information:: %%%WIDGET_NAME_LOWER%%%
+
+.. widget-example::
+    :editor: elements
+    :scale: 75
+    :align: center
+
+    <caption>Elements in the editor</caption>
+    <meta>
+        <plugins>
+            <plugin name="%%%WIDGET_NAME_LOWER%%%" />
+        </plugins>
+    </meta>
+    <%%%WIDGET_NAME_LOWER%%%>
+        <layout colspan="4" />
+        <label>%%%WIDGET_NAME%%%</label>
+        <address transform="DPT:1.001" mode="readwrite">1/1/0</address>
+    </%%%WIDGET_NAME_LOWER%%%>
+
+Examples
+--------
+
+It is possible to manually edit the :doc:`visu_config.xml <../../../xml-format>` and add an entry
+for the %%%WIDGET_NAME%%% plugin.
+
+.. CAUTION::
+    Make sure that you only use UTF-8 encoded characters by settings the encoding in your
+    XML-editor to UTF-8 mode!
+
+.. ###START-WIDGET-EXAMPLES#### Please do not change the following content. Changes will be overwritten
+
+.. ###END-WIDGET-EXAMPLES####
+
+.. rubric:: Footnotes
+
+.. [#f1] The simple view might not show everything. To see all elements/attributes use the expert view.

doc/manual/_templates/en/widget-template.rst

@@ -0,0 +1,75 @@
+.. _%%%WIDGET_NAME_LOWER%%%:
+
+%%%HEADLINE%%%
+
+.. api-doc:: %%%WIDGET_NAME%%%
+
+Description
+-----------
+
+.. ###START-WIDGET-DESCRIPTION#### Please do not change the following content. Changes will be overwritten
+
+.. ###END-WIDGET-DESCRIPTION####
+
+Settings
+--------
+
+For a general understanding of how the configuration files are structured and what elements and attributes are
+it is recommended to read this section first: :ref:`visu-config-details`.
+
+The behaviour and appearance of the %%%WIDGET_NAME%%% widget can be influenced by using certain attributes and elements.
+The following tables show the allowed attributes and elements and their possible values.
+The screenshots show, how both can be edited in the :ref:`editor <editor>`.
+
+Attributes underlined by ..... are mandatory, all the others are optional and be omitted.
+
+Allowed attributes in the %%%WIDGET_NAME%%%-element
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. parameter-information:: %%%WIDGET_NAME_LOWER%%%
+
+.. widget-example::
+    :editor: attributes
+    :scale: 75
+    :align: center
+
+    <caption>Attributes in the editor (simple view) [#f1]_</caption>
+    <%%%WIDGET_NAME_LOWER%%%>
+        <layout colspan="4" />
+    </%%%WIDGET_NAME_LOWER%%%>
+
+
+Allowed child-elements und their attributes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. elements-information:: %%%WIDGET_NAME_LOWER%%%
+
+.. widget-example::
+    :editor: elements
+    :scale: 75
+    :align: center
+
+    <caption>Elements in the editor</caption>
+    <%%%WIDGET_NAME_LOWER%%%>
+        <layout colspan="4" />
+        <label>%%%WIDGET_NAME%%%</label>
+        <address transform="DPT:1.001" mode="readwrite">1/1/0</address>
+    </%%%WIDGET_NAME_LOWER%%%>
+
+Examples
+--------
+
+It is possible to manually edit the :doc:`visu_config.xml <../../../xml-format>` and add an entry
+for the %%%WIDGET_NAME%%% widget.
+
+.. CAUTION::
+    Make sure that you only use UTF-8 encoded characters by settings the encoding in your
+    XML-editor to UTF-8 mode!
+
+.. ###START-WIDGET-EXAMPLES#### Please do not change the following content. Changes will be overwritten
+
+.. ###END-WIDGET-EXAMPLES####
+
+.. rubric:: Footnotes
+
+.. [#f1] The simple view might not show everything. To see all elements/attributes use the expert view.

doc/manual/de/config/widgets/index.rst

@@ -18,7 +18,7 @@ Bedienbare Widgets
 ==================
 
 Diese Widgets können in irgendeiner Weise bedient werden um so Daten an das Backend zu senden oder andere
-Aktionen auszulösen, z.B. kann man mit einem Switch durch anklicken einen Lampe schalten, oder mit einem Pagejumo
+Aktionen auszulösen, z.B. kann man mit einem Switch durch anklicken einen Lampe schalten, oder mit einem Pagejump
 kann innerhalb der Visu navigiert werden.
 
 +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

doc/manual/en/_static/theme_override.css

@@ -0,0 +1,32 @@
+.wy-table-responsive table tr td, .wy-table-responsive table tr th {
+    white-space: normal;
+}
+img + p.caption {
+    font-style: italic;
+}
+img.align-center + p.caption {
+    text-align: center;
+}
+img.align-right + p.caption {
+    text-align: right;
+}
+img.align-left + p.caption {
+    text-align: left;
+}
+table.schema-table td dl dt {
+    font-weight: normal;
+}
+table.schema-table td dl dd ul {
+    line-height: normal !important;
+}
+table.schema-table td dl dd > ul {
+    margin-left: -24px; /* override surrounding dd padding */
+    margin-bottom: 0px !important;
+}
+table.schema-table td dl dd blockquote {
+    line-height: normal;
+}
+table.schema-table td dl dd blockquote ul {
+    margin-left: -24px; /* override surrounding blockquote padding */
+    line-height: normal;
+}

doc/manual/en/conf.py

@@ -0,0 +1,183 @@
+# -*- coding: utf-8 -*-
+import json
+
+import sphinx_rtd_theme
+import sys, os
+
+root_dir = os.path.abspath(os.path.join('..', '..', '..'))
+
+extensions_path = os.path.join(root_dir, 'utils', 'docutils', 'directives')
+
+sys.path.insert(0, extensions_path)
+
+extensions = ['sphinx.ext.todo',
+              'sphinx.ext.coverage',
+              'sphinx.ext.ifconfig',
+              'sphinxcontrib.plantuml',
+              'cometvisu']
+
+todo_include_todos = True
+templates_path = ['_templates']
+source_suffix = '.rst'
+master_doc = 'index'
+exclude_patterns = []
+add_function_parentheses = True
+#add_module_names = True
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+language = 'en'
+locale_dirs = ["locale/"]
+
+project = 'CometVisu'
+copyright = '2010-2016 Christian Mayer and the CometVisu contributers'
+
+with open(os.path.join(root_dir, "package.json")) as data_file:
+    data = json.load(data_file)
+    version = data['version']
+
+releaselevel = 'dev' if version[-4:] == '-dev' else 'release'
+release = ''
+
+# -- Options for HTML output ---------------------------------------------------
+
+html_theme = 'sphinx_rtd_theme'
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+html_title = "CometVisu"
+#html_short_title = None
+html_logo = os.path.join(root_dir, "src", "icon", "comet_webapp_icon_android_48.png")
+#html_favicon = None
+html_static_path = ['_static']
+html_domain_indices = False
+html_use_index = True
+html_show_sphinx = False
+htmlhelp_basename = 'CometVisu'
+html_show_sourcelink = False
+
+# -- Options for LaTeX output --------------------------------------------------
+
+latex_elements = {
+    'papersize': '',
+    'fontpkg': '',
+    'fncychap': '',
+    'maketitle': '\\cover',
+    'pointsize': '',
+    'preamble': '',
+    'releasename': "",
+    'babel': '',
+    'printindex': '',
+    'fontenc': '',
+    'inputenc': '',
+    'classoptions': '',
+    'utf8extra': '',
+
+}
+
+#latex_additional_files = ["mfgan-bw.sty", "mfgan.sty", "_static/cover.png"]
+
+latex_documents = [
+    ('index', 'music-for-geeks-and-nerds.tex', u'Music for Geeks and Nerds',
+     u'Pedro Kroger', 'manual'),
+]
+
+latex_show_pagerefs = False
+latex_domain_indices = False
+latex_use_modindex = False
+#latex_logo = None
+#latex_show_urls = False
+
+# -- Options for Epub output ---------------------------------------------------
+
+epub_title = project
+epub_copyright = copyright
+
+epub_theme = 'epub2'
+
+# The scheme of the identifier. Typical schemes are ISBN or URL.
+#epub_scheme = ''
+
+# The unique identifier of the text. This can be a ISBN number
+# or the project homepage.
+#epub_identifier = ''
+
+# A unique identification for the text.
+#epub_uid = ''
+
+# A tuple containing the cover image and cover page html template filenames.
+epub_cover = ("_static/cover.png", "epub-cover.html")
+
+# HTML files that should be inserted before the pages created by sphinx.
+# The format is a list of tuples containing the path and title.
+#epub_pre_files = []
+
+# HTML files shat should be inserted after the pages created by sphinx.
+# The format is a list of tuples containing the path and title.
+#epub_post_files = []
+
+# A list of files that should not be packed into the epub file.
+epub_exclude_files = []
+
+# The depth of the table of contents in toc.ncx.
+epub_tocdepth = 2
+
+# Allow duplicate toc entries.
+epub_tocdup = False
+
+
+# -- Options for Mobi output ---------------------------------------------------
+
+mobi_theme = "mobi"
+mobi_title = project
+mobi_copyright = copyright
+
+# The scheme of the identifier. Typical schemes are ISBN or URL.
+#mobi_scheme = ''
+
+# The unique identifier of the text. This can be a ISBN number
+# or the project homepage.
+#mobi_identifier = ''
+
+# A unique identification for the text.
+#mobi_uid = ''
+
+mobi_cover = "_static/cover.png"
+
+# HTML files that should be inserted before the pages created by sphinx.
+# The format is a list of tuples containing the path and title.
+#mobi_pre_files = []
+
+# HTML files shat should be inserted after the pages created by sphinx.
+# The format is a list of tuples containing the path and title.
+#mobi_post_files = []
+
+# A list of files that should not be packed into the mobi file.
+mobi_exclude_files = []
+
+# The depth of the table of contents in toc.ncx.
+mobi_tocdepth = 2
+
+# Allow duplicate toc entries.
+mobi_tocdup = False
+
+mobi_add_visible_links = False
+
+
+# -- Options for Code Examples output ---------------------------------------------------
+
+
+code_example_dir = "code-example"
+code_add_python_path = ["../py"]
+
+
+################################################################################
+
+
+def setup(app):
+    app.add_stylesheet('theme_override.css')
+    app.add_config_value('releaselevel', '', 'env')
+
+    from sphinx.util.texescape import tex_replacements
+    tex_replacements += [(u'♮', u'$\\natural$'),
+                         (u'ē', u'\=e'),
+                         (u'♩', u'\quarternote'),
+                         (u'↑', u'$\\uparrow$'),
+                         ]