A Sphinx extension to convert ASCII diagrams to SVGs with Svgbob.
Project description
sphinxcontrib-svgbob
A Sphinx extension to render ASCII diagrams into SVG using Svgbob.
🗺️ Overview
Diagrams to be included into Sphinx documentation are commonly described with a dedicated markup language, and converted into an image by Sphinx when the documentation is built. However, this reduces the legibility of the documentation source for readers that are not browsing the HTML version.
Svgbob is a diagramming model implemented in Rust that can convert ASCII diagrams into SVG. Using it allows you to:
- Keep a textual version of the diagram in your documentation, so that it remains legible.
- Render a nicer version as SVG for HTML or PDF versions of the documentation.
This Sphinx extension builds Svgbob statically and lets you use it to render ASCII diagrams within Sphinx documentation. Since it does not require any external dependency, it's also suitable to use on readthedocs.org.
🔧 Installing
sphinxcontrib-svgbob
can be installed from PyPI,
which hosts some pre-built CPython wheels for x86-64 Linux and OSX, as well as the code required
to compile from source:
$ pip install sphinxcontrib-svgbob
If a Rust compiler is not available, the setup.py
script will attempt to
install a temporary copy if the package is compiled on a UNIX system. If
it doesn't work, see the
documentation on rust-lang.org
to learn how to install Rust on your machine.
Then add this extension to the Sphinx extensions in your conf.py
file to
make the svgbob
directive available:
extensions = [
...,
"sphinxcontrib.svgbob",
]
That's it, you're all set!
💡 Example
Use the svgbob
directive in a function docstring to show a diagram of what
is being computed:
def hamming(x, y):
"""Compute the Hamming distance between two strings.
Hamming distance between two strings of equal length is the number of
positions at which the corresponding symbols are different. For instance,
Hamming distance for a 3-bit string can be computed visually using a
3-bit binary cube:
.. svgbob::
:align: center
110 111
*-----------*
/| /|
/ | 011 / |
010 *--+--------* |
| | 100 | |
| *--------+--* 101
| / | /
|/ |/
000 *-----------* 001
The minimum distance between any two vertices is the Hamming distance
between the two bit vectors (e.g. 100→011 has distance 3).
"""
When Sphinx (and autodoc
) renders the docstring of this function, you'll get
the following HTML page (here shown with the Sphinx theme for readthedocs.org):
And yet, the help(hamming)
will still look nice and helpful:
🔩 Configuration
The svgbob
directive supports the following arguments:
font-size
(integer): the size of the text to be rendered, defaults to 14.font-family
: the family of the font used to render the text, defaults to monospace.fill-color
(CSS color): the color to use to fill closed shapes.stroke-color
(CSS color): the color to use to paint strokes, defaults to black.scale
(float): the SVG scale of the figure, defaults to 8.0.align
(CSS align value): the alignment of the resulting image.class
(HTML class): an arbitrary class to add to the resulting HTML element.
For instance, use the following to use Arial with size 12, to render nicer text in the diagram blocks:
.. svgbob::
:font-family: Arial
:font-size: 12
+-------+ +--------+
| Hello |------>| World! |
+-------+ +--------+
💭 Feedback
⚠️ Issue Tracker
Found a bug ? Have an enhancement request ? Head over to the GitHub issue tracker if you need to report or ask something. If you are filing in on a bug, please include as much information as you can about the issue, and try to recreate the same bug in a simple, easily reproducible situation.
🏗️ Contributing
Contributions are more than welcome! See CONTRIBUTING.md
for more details.
📚 Alternatives
sphinxcontrib-kroki
also lets you use Svgbob to convert ASCII diagrams, but it queries the kroki.io website to do so, and does not support the new options from Svgbob v0.5.sphinxcontrib-aafig
uses theaafigure
binary to convert ASCII diagrams.
🔨 Credits
sphinxcontrib-svgbob
is developped and maintained by:
The structure of this repository was adapted from the aforementioned
sphinxcontrib-kroki
repository, as I had no experience setting up a
Sphinx extension otherwise.
⚖️ License
This library is provided under the MIT License.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
Hashes for sphinxcontrib_svgbob-0.3.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4df35ef07e9a33662f21d3b6dbe9f8568274adeabd03e6b573c9bb5129d1f9f7 |
|
MD5 | c361a463aaaa8b2e3ba7d9b6058c1225 |
|
BLAKE2b-256 | 24f86f5a5374bb35ae290c2eb02a656bb185a3d2cf124766a72c3d6391a10417 |
Hashes for sphinxcontrib_svgbob-0.3.0-cp312-cp312-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 88d4462b94d3482ae82f7624171db3b75a6ebca3d5087b2d6e00220918b141ce |
|
MD5 | ea288b4d4d29f32727efbea2286d5a71 |
|
BLAKE2b-256 | e7fb57c5ce95b13e40a1f217e0428f82c9343a4a8681fe7cb8c116df8d2a2e86 |
Hashes for sphinxcontrib_svgbob-0.3.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3f71eebc8dc29a3769297b6f48956811de1788fd5443f8c622ac53b702f49178 |
|
MD5 | fbfe8e0c8852a953a4681545c54ec7d7 |
|
BLAKE2b-256 | 97101daf4552e3c842912903eb07cdf76326a2dca4de0a2273aa50d0aac6dee7 |
Hashes for sphinxcontrib_svgbob-0.3.0-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 03b26c787d8ec93222cc562a24d2b974cf6fc0d723f3931710599b25c00802f4 |
|
MD5 | 8cfbf88547799d85341545872bc9a5da |
|
BLAKE2b-256 | a9c17ea4ab158f828576012ab518bad62696eef255fc8d355128ddf828a0670e |
Hashes for sphinxcontrib_svgbob-0.3.0-cp312-cp312-macosx_12_0_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | f49939c3ab621dccdba598afecedcb7be50615ebee6c9cefabf743501b06aa2e |
|
MD5 | c938fea51304ac607c9665201e83e265 |
|
BLAKE2b-256 | 3af79fce81c02ee5e623e45ce52c6e83f6e01f1ef0d2f9027544c036a5142ce7 |
Hashes for sphinxcontrib_svgbob-0.3.0-cp312-cp312-macosx_12_0_arm64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | f8ea8d0bdfae277eac999a265349bbc95d77b343ffc783e3091de3afc524af94 |
|
MD5 | 3c17d5aa2f8d927a4f60a9f1839e5a01 |
|
BLAKE2b-256 | 0b7018a7fd04ac13103f17b79f8e0e4936677818e07d848ee2551636e266eb45 |
Hashes for sphinxcontrib_svgbob-0.3.0-cp311-cp311-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e66fbb461b27f0697a49a1b037d9fa437844ff5a04c9bb136fd8aebda11b82ee |
|
MD5 | 5758459006c210227399a31de54c93a0 |
|
BLAKE2b-256 | 88e03ce4c64e1a3ab79a182ef24ff7b42a94e7cd2438477d55a42804198dda7f |
Hashes for sphinxcontrib_svgbob-0.3.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 718a83898628ef9b07efeac9be29b1261354a41344b1e0e71ed441f18286a89b |
|
MD5 | 45e6de40a4b073f2d704968b926a8a8d |
|
BLAKE2b-256 | 13231e976eec1296099f3eb6e633c26e418250eb8481712ca33545756a9a7b56 |
Hashes for sphinxcontrib_svgbob-0.3.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 6d1d0293872020ebc7ec4b61c8fa423eae9f535c2ce42a04571c489761413001 |
|
MD5 | ad76065597abe26f86c17cf26ad1e828 |
|
BLAKE2b-256 | 53df3efcfacc44a544c3b301bc625914355357bca4c17ec1483bf885bdc37f7d |
Hashes for sphinxcontrib_svgbob-0.3.0-cp311-cp311-macosx_12_0_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | bc2752f1a2cb8cd541e4db224e39952e905a4416adeea6f96c2beee50659169b |
|
MD5 | 0475d766cc2f197a6e6ddf7f6cd9409d |
|
BLAKE2b-256 | 8ead5f0f720cb3b72c88499785dc0fe544afe851e416cbe46848eaf03dfc85c2 |
Hashes for sphinxcontrib_svgbob-0.3.0-cp311-cp311-macosx_12_0_arm64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 01aff828c3bb4cb872f794d6f0fb3d99fe2d26f733b3368912d2470424f63474 |
|
MD5 | 433be4f0414a8d317725d93536eaa23f |
|
BLAKE2b-256 | bac74878b0cc9a2704a2f3185cb7c758d9534b3dfdba9e1fdffed5285608f9f7 |
Hashes for sphinxcontrib_svgbob-0.3.0-cp310-cp310-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a36678623b6e0f943cc32f390abfc549afdeb194b552eb6f5266d0410662e03f |
|
MD5 | 91666ee7289a87f73159b1b4917ed6b3 |
|
BLAKE2b-256 | 15859c8e84f1c610494d79a747684252da05911af42a5df58573735d8b56aebc |
Hashes for sphinxcontrib_svgbob-0.3.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 1febf93d3903b780bfaca4b1053e39f41aad7ab9dad9467d981dad5d3d7f6f65 |
|
MD5 | c9cb3c70466bfc17d6e2eebfa68a36f4 |
|
BLAKE2b-256 | 2822864c9c960e2e8aa0b52c4d41c1f4bf8749437f8b1f42f56ef70bbe2fce60 |
Hashes for sphinxcontrib_svgbob-0.3.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | fe75a1f0a90d9a3d9ba1d2adbf3f05d4f9d76cbf9b68b33e379dd198f408bdb6 |
|
MD5 | 86bc2984fe3cb88f25ed317de83c8bd6 |
|
BLAKE2b-256 | d5daf8461ebb2f0e74b11be30495a9a501cbd9c17d51a44f95822bc337a1a46c |
Hashes for sphinxcontrib_svgbob-0.3.0-cp310-cp310-macosx_12_0_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 558d588b04a6d79a2c58210c08ebf0fd83efcc35d685567c23509e04073b0bf1 |
|
MD5 | e6611c35ddd8108080066a85ac4f6c50 |
|
BLAKE2b-256 | 05df22678faf5d8e00e7f21ae367d43bfe5dddd0a6fc3782ede67f4cc3acad5e |
Hashes for sphinxcontrib_svgbob-0.3.0-cp310-cp310-macosx_12_0_arm64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 450601bf725019ebf5a871252177481cc4f2222d0d066c8788656540e45c9c30 |
|
MD5 | 8050bdf6a420350f6ac6fdd8ef2486b0 |
|
BLAKE2b-256 | 90984fc455ebe21c1f553f6cfd80d029267366674d81b34016eb2e8a1dea1a64 |
Hashes for sphinxcontrib_svgbob-0.3.0-cp39-cp39-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 598540c349629baa0eb004b000e6e53fae434cec16bea2007235591d616e76ab |
|
MD5 | 595004366a78cfaeb0faa43156173492 |
|
BLAKE2b-256 | 9119a1dfb5b5eeb34487702210ac75973248e1aa8eba9a287bb01ffc072f1949 |
Hashes for sphinxcontrib_svgbob-0.3.0-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c45131a1b159ef4d77db5db02396d5666ed99eb2fb30266acc8ae440c0dc9559 |
|
MD5 | 1bf9d90cc92100363d51a73dc7e1e15d |
|
BLAKE2b-256 | 0f52e61364e9a538d0b52a6436e3405469804497167df829b8187bfb681a4a35 |
Hashes for sphinxcontrib_svgbob-0.3.0-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3a72e209574debb29c3f910c31981e60e13becd43cefe2836b73c3cbfc001f5f |
|
MD5 | bf38345a7decd6af4375289e84f895c1 |
|
BLAKE2b-256 | 85aa20c655022cc5bc8413cb7c1627df6b16c0dd0b5626eaa0d1add5133343c3 |
Hashes for sphinxcontrib_svgbob-0.3.0-cp39-cp39-macosx_12_0_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 800033384da6916da14b435e3be4459c67c1e23d874504641b814f388f1338fe |
|
MD5 | d425d8c9d834b8aae4dd74848316f56e |
|
BLAKE2b-256 | c0e92b8db41a9ae497606725a0af1f63e9e37516794c45f9ac67e5276d0f4c93 |
Hashes for sphinxcontrib_svgbob-0.3.0-cp39-cp39-macosx_12_0_arm64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4cec1ad385b6b409388f8e19cfeed58bc7ff607b939da2eb8bad465fa26574b9 |
|
MD5 | 7ec110459a21a2bb102bc22a29eddc59 |
|
BLAKE2b-256 | 2cb3685131b419cbcc84774aa0c7f3fae04c24d741e7d7b4c595ddf9943d47f6 |
Hashes for sphinxcontrib_svgbob-0.3.0-cp38-cp38-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 032c3e7e3658675e68645ee5e97ca5145a6a6ca8745f0bce062f5c2a5ccc1e46 |
|
MD5 | 417598a4e00b4323650a614cd89f8ac9 |
|
BLAKE2b-256 | 2defcc88867be9f7ade45e4707d738275788db6421e4d5fde3ee2ec03ac6de53 |
Hashes for sphinxcontrib_svgbob-0.3.0-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2e2439b5aef46da98371f621b291602b866e682d287d02f141b6a48b41efb0ec |
|
MD5 | cc232ef40c6270171b9b366ac9450b65 |
|
BLAKE2b-256 | 5e6795d210c176d632bf2ed08a2e388faca59b183c512f220593fbb018ff6a8c |
Hashes for sphinxcontrib_svgbob-0.3.0-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8c66adde095e2925a7c808c854db63ff79643ebef016e8bc4a5b69451a26f0a6 |
|
MD5 | 9a6e409e13166a95099dadb87c4d1b09 |
|
BLAKE2b-256 | ff9ebc1d175cfa5e996889e3e1f3cf82b01983da6042543b06a2513b3c022f33 |
Hashes for sphinxcontrib_svgbob-0.3.0-cp38-cp38-macosx_12_0_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5fdd259d40497a507dabec96ade8fc61bfb40569f8104d0fb5b914f701fd1ad6 |
|
MD5 | a2ae76055cbd260e156c442bcdae0f77 |
|
BLAKE2b-256 | 68be070fc5bc4fd091fa3fd85b6892701cf6088eddfa20ac2e59a20cf97ad4f5 |
Hashes for sphinxcontrib_svgbob-0.3.0-cp38-cp38-macosx_12_0_arm64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2ce32131594468b0eb12371e8f586a89f79395c1a48f2efc40483707ebadd982 |
|
MD5 | 8702e6ac5042b56ff771b450c2267bc5 |
|
BLAKE2b-256 | 52cd6ebe9ff2a2fe24ef3796b36afbadaa9e36b754ef0b22d2580ba252b0e88d |
Hashes for sphinxcontrib_svgbob-0.3.0-cp37-cp37m-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5108e8cbce41740c57812f92242fc9ace6147de0d84faa75edbc329997b4bd3e |
|
MD5 | bbe38a4944c232e751e512aa1864374a |
|
BLAKE2b-256 | d3192e611adac2126a3d31514bf8dac3e6ac5863815fcd66aca13ab34a35fb31 |
Hashes for sphinxcontrib_svgbob-0.3.0-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d486837a7e92c49aa7f462cd2a76e9a72290ee9e3a2fdc83fcca058ebcdea04b |
|
MD5 | 35bf6090708c043258fce52f0488e64b |
|
BLAKE2b-256 | 9aa8ede5c53d5d27fddd71e83fface59c0fabb0d228f282efa0ec5c24de911f8 |
Hashes for sphinxcontrib_svgbob-0.3.0-cp37-cp37m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ed1c2c8fd5d328677c1e3aa18d03a8549a25772e558f69b01a54e62252d40793 |
|
MD5 | 60fec556c2a752db99233faf934e26c8 |
|
BLAKE2b-256 | e0b8937ef11d7fc863253577753559df4e2101856348da94b1e476e0f49b5a81 |
Hashes for sphinxcontrib_svgbob-0.3.0-cp37-cp37m-macosx_12_0_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 999f2cb887d98c95cee13787ec40ae12ac496aa1b63ddb34ec3e839845e762ff |
|
MD5 | 603d65994228171eef44819772f58942 |
|
BLAKE2b-256 | fa29ac3ec147bbc83eba5d189b24f9ee78226e85eb58584906196bc2f3e39246 |