Merge pull request #8 from wallento/master

Render from file and generate images if needed

.gitignore

@@ -23,6 +23,7 @@ var/
 *.egg-info/
 .installed.cfg
 *.egg
+sphinxcontrib/version.py
 
 # PyInstaller
 #  Usually these files are written by a python script from a template

.travis.yml

@@ -1,28 +1,32 @@
 language: python
+
+addons:
+  apt:
+    packages:
+    - latexmk
+    - texlive-latex-recommended
+    - texlive-fonts-recommended
+    - texlive-latex-extra
+
 python:
-- '2.7'
-install: pip install -q -r requirements.txt
-script: cd example && make clean && make html && cd ..
-notifications:
-  email:
-    on_success: never
-    on_failure: always
-deploy:
-  - provider: pypi
-    distributions: sdist
-    server: https://test.pypi.org/legacy/
-    user: bavo.van.achte
-    password:
-      secure: eTU2xAyjwVyYrpX8A4H64a6NNrDdVw4p45h0ZWzxD0Fb+4MQ6P/S6td/vn7tZGoBIbWVwzsOAaKNQLs+V2D03jtehxf12pkTw7I21B/hDgsp2DuTFM2GI/xOCcA7VoBEuEBZiMJiUGFbg7hoa/cHqHd3s97IowZ2+WaIzZoL28D0sSknyRTva63sG/oQfMWXCZ5SH4DthoFCsB3+jXhC4HKZbJzYOw2xeHHemkKmXo65a/whwsya++UuCqpo+/n+jWycjFun00sy2nE1CecQ4l0F4EpWPZgSR/a3mu4qVFW5YuZ9N1scorzZwryCREGwWRmNRRMtqNnfBcyrYvoDIRWcC1vkqv5511Qdu6ZlnHeh5FPNDMJefzzaOokpGlCLmTWcwjCprUyjXPW9xyHoHU/kdDiw5TUMmtkDvK/EgVoUNbNsCkmywbPaWzDimF3ghC0BbV2vfMCWUlBeO+C5/4HIRKJ5VKcTW9FfbuQe61tf1mN9af8j1VGXZSB6Y/aPSGQkrt0Aq+LbzMAn4Hf9z42/UGVS2/lHb7X0/p2dVEl3RG4mr8l/DtpZ5ilzF4EmFx2By+1eN24CYDshrc7momuZ+8JFUf/ECuMCi9Dv7L0UpwbQyYyoJmjyBAcCAXyZ2Db5sPuFuTm4mBeIbPe3RWmMApD8bdPq503K8g/siN4=
-    on:
-      branch: master
-      tags: false
-  - provider: pypi
-    distributions: sdist
-    user: bavo.van.achte
-    password:
-      secure: eTU2xAyjwVyYrpX8A4H64a6NNrDdVw4p45h0ZWzxD0Fb+4MQ6P/S6td/vn7tZGoBIbWVwzsOAaKNQLs+V2D03jtehxf12pkTw7I21B/hDgsp2DuTFM2GI/xOCcA7VoBEuEBZiMJiUGFbg7hoa/cHqHd3s97IowZ2+WaIzZoL28D0sSknyRTva63sG/oQfMWXCZ5SH4DthoFCsB3+jXhC4HKZbJzYOw2xeHHemkKmXo65a/whwsya++UuCqpo+/n+jWycjFun00sy2nE1CecQ4l0F4EpWPZgSR/a3mu4qVFW5YuZ9N1scorzZwryCREGwWRmNRRMtqNnfBcyrYvoDIRWcC1vkqv5511Qdu6ZlnHeh5FPNDMJefzzaOokpGlCLmTWcwjCprUyjXPW9xyHoHU/kdDiw5TUMmtkDvK/EgVoUNbNsCkmywbPaWzDimF3ghC0BbV2vfMCWUlBeO+C5/4HIRKJ5VKcTW9FfbuQe61tf1mN9af8j1VGXZSB6Y/aPSGQkrt0Aq+LbzMAn4Hf9z42/UGVS2/lHb7X0/p2dVEl3RG4mr8l/DtpZ5ilzF4EmFx2By+1eN24CYDshrc7momuZ+8JFUf/ECuMCi9Dv7L0UpwbQyYyoJmjyBAcCAXyZ2Db5sPuFuTm4mBeIbPe3RWmMApD8bdPq503K8g/siN4=
-    on:
-      branch: master
-      tags: true
+  - "2.7"
+  - "3.4"
+  - "3.5"
+  - "3.6"
+
+before_install:
+  - cd example
+
+install:
+  - pip install --upgrade pip
+  - pip install ..
+  - pip install sphinx_rtd_theme
 
+script:
+  - make clean html
+  - make clean singlehtml
+  - make clean dirhtml
+  - make clean html WAVEDROM_HTML_NOJSINLINE=1
+  - make clean singlehtml WAVEDROM_HTML_NOJSINLINE=1
+  - make clean dirhtml WAVEDROM_HTML_NOJSINLINE=1
+  - if [[ $TRAVIS_PYTHON_VERSION != 2.7 ]]; then make clean latexpdf; fi

README.rst

@@ -6,18 +6,18 @@ A sphinx extension that allows including wavedrom diagrams by using its text-bas
 Wavedrom online editor and tutorial: http://wavedrom.com/
 
 .. image:: https://travis-ci.org/bavovanachte/sphinx-wavedrom.svg?branch=master
-    :target: https://travis-ci.org/bavovanachte/sphinx-wavedrom
+	:target: https://travis-ci.org/bavovanachte/sphinx-wavedrom
 
 .. image:: https://badge.fury.io/py/sphinxcontrib-wavedrom.svg
-    :target: https://badge.fury.io/py/sphinxcontrib-wavedrom
+	:target: https://badge.fury.io/py/sphinxcontrib-wavedrom
 
 Installation
 ------------
 
 The wavedrom extension can be installed using pip:
 
 ::
-	
+
 	pip install sphinxcontrib-wavedrom
 
 and by adding **'sphinxcontrib.wavedrom'** to the extensions list in your conf.py file.
@@ -31,20 +31,65 @@ The extension is useable in the form of an extra wavedrom directive, as shown be
 
 	.. wavedrom::
 
-		{ signal: [
-		  	{ name: "clk",  wave: "P......" },
-		  	{ name: "bus",  wave: "x.==.=x", data: ["head", "body", "tail", "data"] },
-		  	{ name: "wire", wave: "0.1..0." }
+		{ "signal": [
+		  	{ "name": "clk",  "wave": "P......" },
+		  	{ "name": "bus",  "wave": "x.==.=x", "data": ["head", "body", "tail", "data"] },
+		  	{ "name": "wire", "wave": "0.1..0." }
 		]}
 
-The extension will not generate an image out of the diagram description itself,
-but it will surround it with some html and js tags in the final html document
-that allow the images to be rendered by the browser.
+Alternatively, it can read the json from a file:
+
+::
+
+	.. wavedrom:: mywave.json
+
+When configured to generate images (see `Configuration`_) the directive will generate an image and include
+it into the input. It allows for the same configuration as the image directive:
+
+::
+
+	.. wavedrom:: mywave.json
+        :height: 100px
+        :width: 200 px
+        :scale: 50 %
+        :alt: alternate text
+        :align: right
+
+The image can be turned into a figure by adding a caption:
+
+::
+
+    .. wavedrom:: mywave.json
+        :caption: My wave figure
+
+The extension can be configured (see `Configuration`_) to not generate an image out of the diagram description
+itself, but to surround it with some html and js tags in the final html document that allow the images to be rendered
+by the browser. This is the currently the default for HTML output.
 
 Configuration
 -------------
 
-The extension can work in 2 modes:
+The extension can be configured to either directly output images or by emitting the javascript to live-render the
+wavedrom code, which obviously only works for HTML output. All other outputs (most notably ``latexpdf``) embed a
+generated image in any case, but this is only supported when using Python 3.
+
+For HTML output the configuration item ``wavedrom_html_jsinline`` (default: ``True``) can toggled to generate images
+instead of inline javascript code. You must add the following line to your ``conf.py``:
+
+::
+
+    wavedrom_html_jsinline = False
+
+or overwrite the setting on the command line, for example:
+
+::
+
+    sphinx-build -b html -D wavedrom_html_jsinline=0 sources build/html
+
+HTML: Inline Javascript
+```````````````````````
+
+When HTML building is configured to inline the javascript (default), the extension can work in 2 modes:
 
 - Online mode: 	the extension links to the javascript file(s) provided by the wavedrom server
 - Offline mode: the extension uses the javascript file(s) that are saved locally on your drive.
@@ -58,6 +103,7 @@ If offline mode is desired, the following parameters need to be provided:
 
 The paths given for these configurations need to be relative to the configuration directory (the directory that contains conf.py)
 
+
 Examples
 --------
 

example/Makefile

@@ -2,11 +2,15 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
+SPHINXOPTS    = -W
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = build
 
+ifdef WAVEDROM_HTML_NOJSINLINE
+SPHINXOPTS += -D wavedrom_html_jsinline=0
+endif
+
 # User-friendly check for sphinx-build
 ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
 $(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)

example/source/conf.py

@@ -13,29 +13,20 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 import sphinx_rtd_theme
-import sys
-import os
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
 
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
 #needs_sphinx = '1.0'
 
-sys.path.insert(0, os.path.abspath('../../sphinxcontrib'))
-
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['wavedrom']
+extensions = ['sphinxcontrib.wavedrom', 'sphinx.ext.ifconfig']
 
-#offline_skin_js_path = r"default.js"
 offline_skin_js_path = r"default.js"
 offline_wavedrom_js_path = r"../wavedrom.js"
+#wavedrom_html_jsinline = True
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

example/source/example.json

@@ -0,0 +1,10 @@
+{ "signal": [
+    { "name": "A", "wave": "01..0..",  "node": ".a..e.." },
+    { "name": "B", "wave": "0.1..0.",  "node": "..b..d.", "phase":0.5 },
+    { "name": "C", "wave": "0..1..0",  "node": "...c..f" },
+    {                              "node": "...g..h" }
+],
+"edge": [
+    "b-|a t1", "a-|c t2", "b-|-c t3", "c-|->e t4", "e-|>f more text",
+    "e|->d t6", "c-g", "f-h", "g<->h 3 ms"
+]}