vscode-sphinx-seed

Setup vscode

install vscode extension of ms-vscode-remote.remote-containers [https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers]
Ctrl+Shift+P -> Reopen in Container

Crete sphinx project

Run command following:

sphinx-quickstart --no-batchfile --sep

The following directories will be created:

.
├── Makefile
├── build
└── source
    ├── _static
    ├── _templates
    ├── conf.py
    └── index.rst

See also details command line help: sphinx-quickstart --help

Setup sphinx for use graph tools

As you can see in the Dockerfile it contains some diagram extensions. To enable them add the following to your conf.py: If unset, the figure is visible in preview, but not when generating documentation.

Use PlantUML

Add the following configuration to conf.py

extensions += ['sphinxcontrib.plantuml']
plantuml = ['java', '-jar', '/usr/local/bin/plantuml.jar']

Use blockdiags

Add the following configuration to conf.py

extensions += [
    'sphinxcontrib.blockdiag',
    'sphinxcontrib.seqdiag',
    'sphinxcontrib.actdiag',
    'sphinxcontrib.nwdiag',
    'sphinxcontrib.rackdiag',
    'sphinxcontrib.packetdiag',
]
blockdiag_html_image_format = 'SVG'
seqdiag_html_image_format = 'SVG'
actdiag_html_image_format = 'SVG'
nwdiag_html_image_format = 'SVG'
rackiag_html_image_format = 'SVG'
packetdiag_html_image_format = 'SVG'

Build document

Create PDF

make latexpdf

Create HTML

make html

Trouble shooting

If you don't see the diagram, you may be able to fix it by checking your esbonio settings and restart vscode.

{
    "esbonio.sphinx.buildDir" : "${workspaceFolder}/build/html",
    "esbonio.sphinx.confDir"  : "${workspaceFolder}/source",
    "esbonio.sphinx.srcDir"   : "${workspaceFolder}/source"
}

tdoioka/vscode-sphinx-seed