Skip to content
GitLab
Projects
Groups
Snippets
/
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in
Toggle navigation
Menu
Open sidebar
Florian Rhiem
doc-utils
Commits
a5c52c2a
Commit
a5c52c2a
authored
Sep 03, 2018
by
Ingo Meyer
Browse files
Merge branch 'develop'
parents
613de438
b173e995
Changes
6
Hide whitespace changes
Inline
Side-by-side
README.md
View file @
a5c52c2a
...
...
@@ -17,19 +17,44 @@ pip install git+https://iffgit.fz-juelich.de/doc-utils/doc-utils
After installing you can use the extended rst writers
`rst2latex-extended`
and
`rst2html-extended`
that are compatible
with the standard versions but offer additional features:
-
Code blocks are formatted with the
`minted`
package (LaTeX only)
-
Images can be embedded into the generated document (
`embedded-image`
directive, HTML only; for LaTeX this is already
the default behavior)
-
Support for TikZ images by
`tikz`
and
`tikz-figure`
directives. TikZ code can be loaded from an external file or
written as embedded source.
`rst2html-extended`
needs either
`pdf2svg`
or
`mupdf-tools`
to support TikZ pictures.
`pdf2svg`
is recommended because it produces SVG images without any quality loss.
-
Code blocks are formatted with the
`minted`
package (LaTeX only).
-
Images can be embedded into the generated document (
`embedded-image`
and
`embedded-figure`
directives). Adds an
additional convert step if the graphics format is not suitable for the output (SVG images are converted to PDF and
GIF to PNG for LaTeX output). If the image path is a web link, the image is downloaded before.
-
Support for TikZ images by
`tikz`
and
`tikz-figure`
directives. TikZ code can be loaded from an external file or
written as embedded source.
`rst2html-extended`
needs either
`pdf2svg`
or
`mupdf-tools`
to support TikZ pictures.
`pdf2svg`
is recommended because it produces SVG images without any quality loss.
### Directive options
-
`tikz`
and
`tikz-figure`
:
- Both directives inherit `alt`, `height`, `width`, `scale`, `align`, `name`, `target` and `class` from the `image`
directive.
- Both directives have the additional options:
- `document_options`: Extra options for the LaTeX
[`standalone` document class](https://ctan.org/pkg/standalone?lang=en)
- `lang`: Babel language
- `do_not_use_default_packages`: Do not load these default packages: `inputenc`, `fontenc`, `lmodern`,
`babel`, `xcolor`, `graphicx`
- `extra_packages`: Extra packages to load, can be used like this: `[options]{package};[options]{package}`
- `tikz_libs`: Additional TikZ libraries to load, separated by comma, e.g.: `arrows,calc`
- `tikzpicture_options`: Additional tikzpicture options, for example: `overlay`
- The `tikz-figure` directive has the additional options `figwidth` and `caption` like other `figure` objects.
-
`embedded-image`
and
`embedded-figure`
:
- All options are identical to the usual `image` and `figure` directives.
## Files
-
`styles/rst2html_githublike_fzj.css`
: Stylesheet for
`rst2html`
with fzj blue for strong emphasized text; Using
`--syntax-highlight=short`
option with
`rst2html`
is recommended but long class names are also included in the this
CSS file
-
`styles/rst2latex_fzj.sty`
: Style with fzj colors and a custom title page
-
`styles/rst2luatex_fzj.sty`
: Style with fzj colors and a custom title page for use with LuaTex / LuaLaTeX
-
`utils/Makefile`
: Example Makefile for generating PDFs and HTML pages from Markdown and reStructuredText documents
-
`styles/rst2html_githublike_fzj.css`
: Stylesheet for
`rst2html`
with fzj blue for strong emphasized text; Using
`--syntax-highlight=short`
option with
`rst2html`
is recommended but long class names are also included in the this
CSS file
.
-
`styles/rst2latex_fzj.sty`
: Style with fzj colors and a custom title page
-
`styles/rst2luatex_fzj.sty`
: Style with fzj colors and a custom title page for use with LuaTex / LuaLaTeX
-
`utils/Makefile`
: Example Makefile for generating PDFs and HTML pages from Markdown and reStructuredText documents
docutils_extended/_version.py
View file @
a5c52c2a
__version_info__
=
(
0
,
2
,
2
)
__version_info__
=
(
0
,
2
,
3
)
__version__
=
'.'
.
join
(
map
(
str
,
__version_info__
))
docutils_extended/directives/__init__.py
View file @
a5c52c2a
from
.code_directive
import
CodeBlock
from
.embedded_image_directive
import
EmbeddedImage
from
.embedded_image_directive
import
EmbeddedImage
,
EmbeddedFigure
from
.jupyter_outbox_directive
import
JupyterOutbox
from
.tikz_directive
import
Tikz
,
TikzFigure
from
.output_mode
import
get_output_mode
,
set_output_mode
__all__
=
(
"CodeBlock"
,
"EmbeddedImage"
,
"JupyterOutbox"
,
"Tikz"
,
"TikzFigure"
,
"get_output_mode"
,
"set_output_mode"
)
__all__
=
(
"CodeBlock"
,
"EmbeddedImage"
,
"EmbeddedFigure"
,
"JupyterOutbox"
,
"Tikz"
,
"TikzFigure"
,
"get_output_mode"
,
"set_output_mode"
)
docutils_extended/directives/embedded_image_directive.py
View file @
a5c52c2a
...
...
@@ -181,3 +181,32 @@ class EmbeddedImage(Directive):
return
messages
+
[
reference_node
]
else
:
return
messages
+
[
image_node
]
class
EmbeddedFigure
(
EmbeddedImage
):
option_spec
=
EmbeddedImage
.
option_spec
.
copy
()
option_spec
[
"figwidth"
]
=
lambda
argument
:
directives
.
length_or_percentage_or_unitless
(
argument
,
"px"
)
option_spec
[
"figclass"
]
=
directives
.
class_option
option_spec
[
"align"
]
=
lambda
argument
:
directives
.
choice
(
argument
,
EmbeddedFigure
.
align_values
)
option_spec
[
"caption"
]
=
directives
.
unchanged
has_content
=
True
def
run
(
self
):
figwidth
=
self
.
options
.
pop
(
"figwidth"
,
None
)
figclasses
=
self
.
options
.
pop
(
"figclass"
,
None
)
align
=
self
.
options
.
pop
(
"align"
,
None
)
caption
=
self
.
options
.
pop
(
"caption"
,
None
)
(
image_node
,)
=
EmbeddedImage
.
run
(
self
)
if
isinstance
(
image_node
,
nodes
.
system_message
):
return
[
image_node
]
figure_node
=
nodes
.
figure
(
""
,
image_node
)
if
figwidth
is
not
None
:
figure_node
[
"width"
]
=
figwidth
if
figclasses
:
figure_node
[
"classes"
]
+=
figclasses
if
align
:
figure_node
[
"align"
]
=
align
if
caption
:
caption
=
nodes
.
caption
(
""
,
text
=
caption
)
figure_node
+=
caption
return
[
figure_node
]
docutils_extended/writers/rst2html_extended.py
View file @
a5c52c2a
...
...
@@ -19,7 +19,7 @@ except:
from
docutils.core
import
publish_cmdline
,
default_description
from
docutils.parsers.rst
import
directives
from
docutils.parsers.rst.directives.body
import
ParsedLiteral
from
..directives
import
EmbeddedImage
,
Tikz
,
TikzFigure
,
set_output_mode
from
..directives
import
EmbeddedImage
,
EmbeddedFigure
,
Tikz
,
TikzFigure
,
set_output_mode
description
=
"Generates (X)HTML documents from standalone reStructuredText "
"sources. "
+
default_description
...
...
@@ -28,6 +28,7 @@ description = "Generates (X)HTML documents from standalone reStructuredText " "s
def
main
():
set_output_mode
(
"html"
)
directives
.
register_directive
(
"embedded-image"
,
EmbeddedImage
)
directives
.
register_directive
(
"embedded-figure"
,
EmbeddedFigure
)
directives
.
register_directive
(
"jupyter-outbox"
,
ParsedLiteral
)
directives
.
register_directive
(
"tikz"
,
Tikz
)
directives
.
register_directive
(
"tikz-figure"
,
TikzFigure
)
...
...
docutils_extended/writers/rst2latex_extended.py
View file @
a5c52c2a
...
...
@@ -19,7 +19,7 @@ except:
from
docutils.core
import
publish_cmdline
from
docutils.parsers.rst
import
directives
from
..directives
import
CodeBlock
,
EmbeddedImage
,
JupyterOutbox
,
Tikz
,
TikzFigure
,
set_output_mode
from
..directives
import
CodeBlock
,
EmbeddedImage
,
EmbeddedFigure
,
JupyterOutbox
,
Tikz
,
TikzFigure
,
set_output_mode
description
=
(
...
...
@@ -37,6 +37,7 @@ def main():
for
directive_name
in
(
"code"
,
"code-block"
):
directives
.
register_directive
(
directive_name
,
CodeBlock
)
directives
.
register_directive
(
"embedded-image"
,
EmbeddedImage
)
directives
.
register_directive
(
"embedded-figure"
,
EmbeddedFigure
)
directives
.
register_directive
(
"jupyter-outbox"
,
JupyterOutbox
)
directives
.
register_directive
(
"tikz"
,
Tikz
)
directives
.
register_directive
(
"tikz-figure"
,
TikzFigure
)
...
...
Write
Preview
Supports
Markdown
0%
Try again
or
attach a new file
.
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment