Security News
Research
Data Theft Repackaged: A Case Study in Malicious Wrapper Packages on npm
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
sphinxcontrib-svgbob
Advanced tools
sphinxcontrib-svgbob
A Sphinx extension to render ASCII diagrams into SVG using Svgbob.
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:
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.
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!
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:
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! |
+-------+ +--------+
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.
Contributions are more than welcome! See CONTRIBUTING.md
for more details.
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 the
aafigure
binary to convert ASCII diagrams.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.
This library is provided under the MIT License.
FAQs
A Sphinx extension to convert ASCII diagrams to SVGs with Svgbob.
We found that sphinxcontrib-svgbob demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.