Sphinx wavedrom extension
=========================
A sphinx extension that allows including wavedrom diagrams by using its text-based representation
Wavedrom online editor and tutorial: https://wavedrom.com/
.. image:: https://travis-ci.org/bavovanachte/sphinx-wavedrom.svg?branch=master
: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
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.
Directives
----------
The extension is useable in the form of an extra wavedrom directive, as shown below.
::
.. wavedrom::
{ "signal": [
{ "name": "clk", "wave": "P......" },
{ "name": "bus", "wave": "x.==.=x", "data": ["head", "body", "tail", "data"] },
{ "name": "wire", "wave": "0.1..0." }
]}
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 following decision tree gives an overview of which configurations to make in different use cases:
.. image:: configuration.png
:alt: Decision tree for configuration settings
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.
Depending on the output you're building, the plugin will automatically choose the appropriate image rendering method
(HTML defaults to browser rendering, pdf to build-time image generation). You can force the generation of build-time
images by adding the following configuration to your ``conf.py``:
::
wavedrom_html_jsinline = False
This may be interesting in case you are building for various output targets and want to ensure consistent diagrams
between all output formats
Build-time image generation through wavedrompy or wavedrom-cli
``````````````````````````````````````````````````````````````
2 Tools are available for the build-time generation of images:
- `wavedrom-cli <https://github.com/wavedrom/cli>`_: The default builder. This is the tool maintained by the wavedrom
team itself. More bloaty than wavedrompy as it requires node.js and npm to install and use, but more likely to render
consistent images w.r.t. the browser-rendered version.
- `wavedrompy <https://github.com/wallento/wavedrompy>`_: A python "clone" of wavedrompy. The goal of the project is to
stay as close as possible to the JS implementation, but offer a solution that doesn't require node.js or npm to be
installed.
As mentioned, wavedrom-cli is the default builder. If you want to select wavedrompy instead, add
``render_using_wavedrompy = True`` to your ``conf.py``:
Wavedrompy is imported as a python module and requires no further configuration. Wavedrom-cli is executed using system
calls. The default command is `npx wavedrom-cli`, but this can be overwritten using the ``wavedrom_cli`` configuration
parameter in `conf.py`
Browser-rendered images through 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) hosted on the wavedrom server or your own server
- Offline mode: the extension uses the javascript file(s) that are saved locally on your drive.
The online mode is the default one. In case you want to use the js files hosted on the wavedrom server, no configuration
is needed. However, in case the desired JS files are hosted on a custom server (or on localhost) add the following to
conf.py:
- ``online_wavedrom_js_url`` : the url of the server hosting the javascript files. The plugin will look for 2 files:
+ {online_wavedrom_js_url}/skins/default.js
+ {online_wavedrom_js_url}/wavedrom.min.js
**Warning**: A full URI is needed when configuring. "http://www.google.com" will work but "www.google.com" won't.
If offline mode is desired, the following configuration parameters need to be provided:
- ``offline_skin_js_path`` : the path to the skin javascript file (the url to the online version is "https://wavedrom.com/skins/default.js")
- ``offline_wavedrom_js_path`` : the path to the wavedrom javascript file (the url to the online version is "https://wavedrom.com/wavedrom.min.js")
The paths given for these configurations need to be relative to the configuration directory (the directory that contains conf.py)
Examples
--------
In the `example` folder, you can find a couple of examples (taken from the wavedrom tutorial), illustration the use of the extension.
Raw data
{
"_id": null,
"home_page": "https://github.com/bavovanachte/sphinx-wavedrom",
"name": "sphinxcontrib-wavedrom",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "sphinx,wavedrom,documentation",
"author": "Bavo Van Achte, Stefan Wallentowitz",
"author_email": "bavo.van.achte@gmail.com, stefan@wallentowitz.de",
"download_url": "https://files.pythonhosted.org/packages/ff/b5/c09b6ac2b0ac8455ec65ab73b62aaebd77ca6ac7eaee47730f9a4b67812b/sphinxcontrib-wavedrom-3.0.4.tar.gz",
"platform": "any",
"description": "Sphinx wavedrom extension\n=========================\n\nA sphinx extension that allows including wavedrom diagrams by using its text-based representation\n\nWavedrom online editor and tutorial: https://wavedrom.com/\n\n.. image:: https://travis-ci.org/bavovanachte/sphinx-wavedrom.svg?branch=master\n\t:target: https://travis-ci.org/bavovanachte/sphinx-wavedrom\n\n.. image:: https://badge.fury.io/py/sphinxcontrib-wavedrom.svg\n\t:target: https://badge.fury.io/py/sphinxcontrib-wavedrom\n\nInstallation\n------------\n\nThe wavedrom extension can be installed using pip:\n\n::\n\n\tpip install sphinxcontrib-wavedrom\n\nand by adding **'sphinxcontrib.wavedrom'** to the extensions list in your conf.py file.\n\nDirectives\n----------\n\nThe extension is useable in the form of an extra wavedrom directive, as shown below.\n\n::\n\n\t.. wavedrom::\n\n\t\t{ \"signal\": [\n\t\t \t{ \"name\": \"clk\", \"wave\": \"P......\" },\n\t\t \t{ \"name\": \"bus\", \"wave\": \"x.==.=x\", \"data\": [\"head\", \"body\", \"tail\", \"data\"] },\n\t\t \t{ \"name\": \"wire\", \"wave\": \"0.1..0.\" }\n\t\t]}\n\nAlternatively, it can read the json from a file:\n\n::\n\n\t.. wavedrom:: mywave.json\n\nWhen configured to generate images (see `Configuration`_) the directive will generate an image and include\nit into the input. It allows for the same configuration as the image directive:\n\n::\n\n\t.. wavedrom:: mywave.json\n :height: 100px\n :width: 200 px\n :scale: 50 %\n :alt: alternate text\n :align: right\n\nThe image can be turned into a figure by adding a caption:\n\n::\n\n .. wavedrom:: mywave.json\n :caption: My wave figure\n\nThe extension can be configured (see `Configuration`_) to not generate an image out of the diagram description\nitself, but to surround it with some html and js tags in the final html document that allow the images to be rendered\nby the browser. This is the currently the default for HTML output.\n\nConfiguration\n-------------\n\nThe following decision tree gives an overview of which configurations to make in different use cases:\n\n.. image:: configuration.png\n :alt: Decision tree for configuration settings\n\nThe extension can be configured to either directly output images or by emitting the javascript to live-render the\nwavedrom code, which obviously only works for HTML output. All other outputs (most notably ``latexpdf``) embed a\ngenerated image in any case, but this is only supported when using Python 3.\n\nDepending on the output you're building, the plugin will automatically choose the appropriate image rendering method\n(HTML defaults to browser rendering, pdf to build-time image generation). You can force the generation of build-time\nimages by adding the following configuration to your ``conf.py``:\n\n::\n\n wavedrom_html_jsinline = False\n\nThis may be interesting in case you are building for various output targets and want to ensure consistent diagrams\nbetween all output formats\n\nBuild-time image generation through wavedrompy or wavedrom-cli\n``````````````````````````````````````````````````````````````\n\n2 Tools are available for the build-time generation of images:\n\n- `wavedrom-cli <https://github.com/wavedrom/cli>`_: The default builder. This is the tool maintained by the wavedrom\n team itself. More bloaty than wavedrompy as it requires node.js and npm to install and use, but more likely to render\n consistent images w.r.t. the browser-rendered version.\n- `wavedrompy <https://github.com/wallento/wavedrompy>`_: A python \"clone\" of wavedrompy. The goal of the project is to\n stay as close as possible to the JS implementation, but offer a solution that doesn't require node.js or npm to be\n installed.\n\nAs mentioned, wavedrom-cli is the default builder. If you want to select wavedrompy instead, add\n``render_using_wavedrompy = True`` to your ``conf.py``:\n\nWavedrompy is imported as a python module and requires no further configuration. Wavedrom-cli is executed using system\ncalls. The default command is `npx wavedrom-cli`, but this can be overwritten using the ``wavedrom_cli`` configuration\nparameter in `conf.py`\n\nBrowser-rendered images through inline Javascript\n`````````````````````````````````````````````````\n\nWhen HTML building is configured to inline the javascript (default), the extension can work in 2 modes:\n\n- Online mode: \tthe extension links to the javascript file(s) hosted on the wavedrom server or your own server\n- Offline mode: the extension uses the javascript file(s) that are saved locally on your drive.\n\nThe online mode is the default one. In case you want to use the js files hosted on the wavedrom server, no configuration\nis needed. However, in case the desired JS files are hosted on a custom server (or on localhost) add the following to\nconf.py:\n\n- ``online_wavedrom_js_url`` : the url of the server hosting the javascript files. The plugin will look for 2 files:\n\n\t+ {online_wavedrom_js_url}/skins/default.js\n\t+ {online_wavedrom_js_url}/wavedrom.min.js\n\n**Warning**: A full URI is needed when configuring. \"http://www.google.com\" will work but \"www.google.com\" won't.\n\nIf offline mode is desired, the following configuration parameters need to be provided:\n\n- ``offline_skin_js_path`` : the path to the skin javascript file (the url to the online version is \"https://wavedrom.com/skins/default.js\")\n- ``offline_wavedrom_js_path`` : the path to the wavedrom javascript file (the url to the online version is \"https://wavedrom.com/wavedrom.min.js\")\n\nThe paths given for these configurations need to be relative to the configuration directory (the directory that contains conf.py)\n\n\nExamples\n--------\n\nIn the `example` folder, you can find a couple of examples (taken from the wavedrom tutorial), illustration the use of the extension.\n\n\n",
"bugtrack_url": null,
"license": "MIT license",
"summary": "A sphinx extension that allows generating wavedrom diagrams based on their textual representation",
"version": "3.0.4",
"project_urls": {
"Homepage": "https://github.com/bavovanachte/sphinx-wavedrom"
},
"split_keywords": [
"sphinx",
"wavedrom",
"documentation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "41ec4d733b2ad6b6b55bda555ed3184d6525de3371426bb522106b217b56b35a",
"md5": "34b5dfcd89e6f55cc25a187c22cce972",
"sha256": "1131126ab00c05984cf5c20c3f164b0200209fff7c8c0ad66dd36b019fc3cb95"
},
"downloads": -1,
"filename": "sphinxcontrib_wavedrom-3.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "34b5dfcd89e6f55cc25a187c22cce972",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 10676,
"upload_time": "2022-03-07T21:04:14",
"upload_time_iso_8601": "2022-03-07T21:04:14.847830Z",
"url": "https://files.pythonhosted.org/packages/41/ec/4d733b2ad6b6b55bda555ed3184d6525de3371426bb522106b217b56b35a/sphinxcontrib_wavedrom-3.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ffb5c09b6ac2b0ac8455ec65ab73b62aaebd77ca6ac7eaee47730f9a4b67812b",
"md5": "24909dd3a08744ea3039b8de957ad050",
"sha256": "d334c7541afd917c0c128e1545316cc5d5f61c8df50f17477cb5070909b0d4aa"
},
"downloads": -1,
"filename": "sphinxcontrib-wavedrom-3.0.4.tar.gz",
"has_sig": false,
"md5_digest": "24909dd3a08744ea3039b8de957ad050",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 209122,
"upload_time": "2022-03-07T21:04:16",
"upload_time_iso_8601": "2022-03-07T21:04:16.324336Z",
"url": "https://files.pythonhosted.org/packages/ff/b5/c09b6ac2b0ac8455ec65ab73b62aaebd77ca6ac7eaee47730f9a4b67812b/sphinxcontrib-wavedrom-3.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-03-07 21:04:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bavovanachte",
"github_project": "sphinx-wavedrom",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sphinxcontrib-wavedrom"
}
JSON
