Skip to content

Add support for packetdiag. #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: develop
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 11 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Blockdiag Preprocessor for Foliant

[Blockdiag](http://blockdiag.com/) is a tool to generate diagrams from plain text. This preprocessor finds diagram definitions in the source and converts them into images on the fly during project build. It supports all Blockdiag flavors: blockdiag, seqdiag, actdiag, and nwdiag.
[Blockdiag](http://blockdiag.com/) is a tool to generate diagrams from plain text. This preprocessor finds diagram definitions in the source and converts them into images on the fly during project build. It supports all Blockdiag flavors: actdiag, blockdiag, nwdiag, packetdiag, rackdiag, and seqdiag.


## Installation
Expand All @@ -25,10 +25,12 @@ The preprocessor has a number of options:
preprocessors:
- blockdiag:
cache_dir: !path .diagramscache
blockdiag_path: blockdiag
seqdiag_path: seqdiag
actdiag_path: actdiag
blockdiag_path: blockdiag
nwdiag_path: nwdiag
packetdiag_path: packetdiag
rackdiag_path: rackdiag
seqdiag_path: seqdiag
params:
...
```
Expand All @@ -41,7 +43,7 @@ preprocessors:
> To save time during build, only new and modified diagrams are rendered. The generated images are cached and reused in future builds.

`*_path`
: Paths to the `blockdiag`, `seqdiag`, `actdiag`, and `nwdiag` binaries. By default, it is assumed that you have these commands in `PATH`, but if they're installed in a custom place, you can define it here.
: Paths to the `actdiag`, `blockdiag`, `nwdiag`, `packetdiag`, `rackdiag`, or `seqdiag` binaries. By default, it is assumed that you have these commands in `PATH`, but if they're installed in a custom place, you can define it here.

`params`
: Params passed to the image generation commands (`blockdiag`, `seqdiag`, etc.). Params should be defined by their long names, with dashes replaced with underscores (e.g. `--no-transparency` becomes `no_transparency`); also, `-T` param is called `format` for readability:
Expand All @@ -57,12 +59,12 @@ preprocessors:

## Usage

To insert a diagram definition in your Markdown source, enclose it between `<<blockdiag>...</blockdiag>`, `<<seqdiag>...</seqdiag>`, `<actdiag>...</actdiag>`, or `<nwdiag>...</nwdiag>` tags (indentation inside tags is optional):
To insert a diagram definition in your Markdown source, enclose it between `<actdiag>...</actdiag>`, `<blockdiag>...</blockdiag>`, `<nwdiag>...</nwdiag>`, `<packetdiag>...</packetdiag>`, `<rackdiag>...</rackdiag>`, or `<seqdiag>...</seqdiag>` tags (indentation inside tags is optional):

```markdown
Here's a block diagram:

<<blockdiag>
<blockdiag>
blockdiag {
A -> B -> C -> D;
A -> E -> F -> G;
Expand All @@ -71,7 +73,7 @@ Here's a block diagram:

Here's a sequence diagram:

<<seqdiag>
<seqdiag>
seqdiag {
browser -> webserver [label = "GET /index.html"];
browser <-- webserver;
Expand All @@ -88,7 +90,7 @@ To set a caption, use `caption` option:
```markdown
Diagram with a caption:

<<blockdiag caption="Sample diagram from the official site">
<blockdiag caption="Sample diagram from the official site">
blockdiag {
A -> B -> C -> D;
A -> E -> F -> G;
Expand All @@ -101,7 +103,7 @@ You can override `params` values from the preprocessor config for each diagram:
```markdown
By default, diagrams are in png. But this diagram is in svg:

<<blockdiag caption="High-quality diagram" format="svg">
<blockdiag caption="High-quality diagram" format="svg">
blockdiag {
A -> B -> C -> D;
A -> E -> F -> G;
Expand Down
23 changes: 16 additions & 7 deletions foliant/preprocessors/blockdiag.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
'''`Blockdiag <http://blockdiag.com/>`__ preprocessor for Foliant documenation authoring tool.
'''`Blockdiag <http://blockdiag.com/>`__ preprocessor for Foliant documentation authoring tool.

Supports blockdiag, seqdiag, actdiag, and nwdiag.
Supports actdiag, blockdiag, nwdiag, packetdiag, rackdiag, and seqdiag
'''

from pathlib import Path
Expand All @@ -16,12 +16,21 @@
class Preprocessor(BasePreprocessor):
defaults = {
'cache_dir': Path('.diagramscache'),
'actdiag_path': 'actdiag',
'blockdiag_path': 'blockdiag',
'nwdiag_path': 'nwdiag',
'packetdiag_path': 'packetdiag',
'rackdiag_path': 'rackdiag',
'seqdiag_path': 'seqdiag',
'actdiag_path': 'actdiag',
'nwdiag_path': 'nwdiag'
}
tags = 'blockdiag', 'seqdiag', 'actdiag', 'nwdiag'
tags = (
'actdiag',
'blockdiag',
'nwdiag',
'packetdiag',
'rackdiag',
'seqdiag',
)

def _get_command(
self,
Expand All @@ -32,7 +41,7 @@ def _get_command(
'''Generate the image generation command. Options from the config definition are passed
as command options (``cache_dir`` and ``*_path`` options are omitted).

:param kind: Diagram kind: blockdiag, seqdiag, actdiag, or nwdiag
:param kind: Diagram kind: actdiag, blockdiag, nwdiag, packetdiag, rackdiag, or seqdiag
:param options: Options extracted from the diagram definition
:param diagram_src_path: Path to the diagram source file

Expand Down Expand Up @@ -67,7 +76,7 @@ def _process_diagram(self, kind: str, options: Dict[str, OptionValue], body: str
If the image for this diagram has already been generated, the existing version
is used.

:param kind: Diagram kind: blockdiag, seqdiag, actdiag, or nwdiag
:param kind: Diagram kind: actdiag, blockdiag, nwdiag, packetdiag, rackdiag, or seqdiag
:param options: Options extracted from the diagram definition
:param body: Diagram body

Expand Down