hevslib.sphinx module¶

Hevslib sphinx module is facilitating creating a ReStructuredText document indented for sphinx the only requirement is the hevslib.general module

Import¶

import sys
sys.path.append("hevslib")

from hevslib.sphinx import *

Example¶

rstFile = Sphinx(filepath="mdTest.rst", append=False)
rstFile.title("Page Title")
rstFile.h1("Page Title")
rstFile.text("normal")
rstFile.list(["1", ["1.1", "1.2"], "2"])
rstFile.link("https://duckduckgo.com", "DuckDuckGo")
rstFile.pageLink("/about/index")
rstFile.refAnchor("my_reference")
rstFile.refLink("my_reference")
rstFile.download("/folder/docs/file.pdf")
rstFile.figure("img/dashboard.svg", align="left", caption="image caption", alt="image hovertext", scale="10%")
rstFile.rule()
rstFile.linesep()
rstFile.inlineCode("int i = 0")
rstFile.code("i = 0", "python", linenos=True, caption="code caption")
rstFile.inlineMath("a^2 + b^2 = c^2")
rstFile.math("a^2 + b^2 = c^2")
rstFile.note("Note text")
rstFile.warning("Warning text")
rstFile.important("Important text")
rstFile.seealso("See also text")
table.append(["Header 1", "Header 2", "Header 3"])
table.append(["R1 C1", "R1 C2", "R1 C3"])
table.append(["R2 C1", "R2 C2", "R2 C3"])
table.append(["R3 C1", "R3 C2", "R3 C3"])
rstFile.table(table, header=False)

rstFile.writeRst(append=True)

TODO¶

exclude resp. only directive
graphviz
wavedrom
plantuml
Different table systems
Support different table arrangements

Documentation¶

class hevslib.sphinx.Sphinx(filepath=None, append=False, log=None)¶

Bases: object

Main Sphinx class holds all content of one rst document

addLineSep()¶

add self.LINESEP if needed Used for directive which need at least one empty line above

Parameters: None –
Returns: None
Raises: None –

bold(text=None, newline=False)¶

Create rst strong bold text

Parameters

text – string
newline – adds a newline at the end (default: False)

Returns

string

Raises

None –

box(directive=None, text=None, option=None)¶

Create a rst boxes with any directive name

Parameters

string name of the directive (directive) –
text – string text for the box
option – string box option

Returns

string

Raises

None –

code(code=None, lang=None, linenos=False, caption=None)¶

Create rst code block

Parameters

code – string of code including line separations
lang – rst codeblock valid language for syntax highlighting
linenos – bool enable line numbers in code bloc
caption – string

Returns

string

Raises

None –

deprecated(text=None, version=None)¶

Create a rst deprecated box

Parameters

text – string
version – string version

Returns

string

Raises

None –

download(filepath=None, alt=None, space=True, newline=False)¶

Create file download link with the :download: directive

Parameters

filepath – string to created reference
alt – string url alt text
space – add a space at the end (default: True)
newline – adds a newline at the end (default: False)

Returns

string

Raises

None –

figure(imagepath=None, width='100%', align='center', caption=None, alt=None, height=None, scale=None)¶

Create image, some parameters are conflicting

scale <!> width

Parameters

imagepath – string path to image absolut or relative
width – string width of image in “px” or “%” (default: “100%”)
align – string “left” “right” “center” (default: “center”)
caption – string optional caption under the image
alt – string optional image alt text
height – string optional in “px”
scale – string optional in “%”

Returns

string

Raises

None –

getDoc()¶

Get rst document as string

Parameters: None –
Returns: string
Raises: None –

getFile()¶

Get rst document as filepath

Parameters: None –
Returns: string
Raises: None –

h1(text=None)¶

Create rst header level 1

Parameters: text – string header text
Returns: string
Raises: None –

h2(text=None)¶

Create rst header level 2

Parameters: text – string header text
Returns: string
Raises: None –

h3(text=None)¶

Create rst header level 3

Parameters: text – string header text
Returns: string
Raises: None –

h4(text=None)¶

Create rst header level 4

Parameters: text – string header text
Returns: string
Raises: None –

h5(text=None)¶

Create rst header level 5

Parameters: text – string header text
Returns: string
Raises: None –

h6(text=None)¶

Create rst header level 6

Parameters: text – string header text
Returns: string
Raises: None –

heading(text=None, level=0)¶

Create rst Header level 0 is a page title

Parameters

text – header text
level – level of headers [0 .. 6]

Returns

string

Raises

None –

important(text=None)¶

Create a rst important box

Parameters: text – string
Returns: string
Raises: None –

inlineCode(text=None, newline=False)¶

Create rst inline literal text

Parameters

text – string
newline – adds a newline at the end (default: False)

Returns

string

Raises

None –

inlineLiteral(text=None, newline=False)¶

Create rst inline literal text

Parameters

text – string
newline – adds a newline at the end (default: False)

Returns

string

Raises

None –

inlineMath(math=None, newline=False)¶

Create rst inline math text

Parameters

text – string of math formatted in latex
newline – bool adds newline

Returns

string

Raises

None –

interpreted(text=None, newline=False)¶

Create rst interpreted text

Parameters

text – string
newline – adds a newline at the end (default: False)

Returns

string

Raises

None –

italic(text=None, newline=False)¶

Create rst italic text

Parameters

text – string
newline – adds a newline at the end (default: False)

Returns

string

Raises

None –

linesep()¶

Creates a rst line separation

Parameters: None –
Returns: string
Raises: None –

link(url=None, alt=None, space=True, newline=False)¶

Create rst Link

Parameters

url – string url to link to
alt – string url alt text
space – add a space at the end (default: True)
newline – adds a newline at the end (default: False)

Returns

string

Raises

None –

list(stringList=[], level=0, ordered=False, append=True)¶

Create rst ordered or unordered list from a python list of string. Can also be a list of list of string to create multilevel lists

Parameters

stringList – list of strings or lists of strings [“”, “”, [“”, “”], …]
level – int of list (starts with 0)
ordered – bool ordered vs unordered list
append – appends to internal variable or gives just the value on return (default: True)

Returns

string

Raises

None –

markup(text=None, newline=False)¶

Create rst markup text

Parameters

text – string
newline – adds a newline at the end (default: False)

Returns

string

Raises

None –

math(math=None)¶

Create rst math block

Parameters: math – string of math formatted in latex including line separation
Returns: string
Raises: None –

note(text=None)¶

Create a rst note box

Parameters: text – string
Returns: string
Raises: None –

pageLink(path=None, alt=None, space=True, newline=False)¶

Create rst interpage link with :doc: directive

Parameters

path – string to linked page either from root (/…) or relative (…)
alt – string url alt text
space – add a space at the end (default: True)
newline – adds a newline at the end (default: False)

Returns

string

Raises

None –

quote(text=None, newline=False)¶

Create rst quote text

Parameters

text – string
newline – adds a newline at the end (default: False)

Returns

string

Raises

None –

refAnchor(ref=None)¶

Create rst reference anchor .. _ref_name:

Parameters

ref – string of anchor name
space – add a space at the end (default: True)
newline – adds a newline at the end

Returns

string

Raises

None –

refLink(ref=None, alt=None, space=True, newline=False)¶

Create rst interpage link with :ref: directive

Parameters

ref – string to created reference
alt – string url alt text
space – add a space at the end (default: True)
newline – adds a newline at the end (default: False)

Returns

string

Raises

None –

rule()¶

Creates a rst rule (horizontal line)

Parameters: None –
Returns: string
Raises: None –

seealso(text=None)¶

Create a rst seealso box

Parameters: text – string
Returns: string
Raises: None –

table(stringlist=[], header=True)¶

Create rst table

Parameters

stringList – list list of strings with content of table [[“”, “”], [“”, “”]]
header – bool optional create header or not

Returns

string

Raises

NotSameLengthError –

text(text=None, newline=False)¶

Create rst normal text

Parameters

text – string
newline – adds a newline at the end (default: False)

Returns

string

Raises

None –

title(text=None)¶

Create rst title, header level 0

Parameters: text – string header text
Returns: string
Raises: None –

toc()¶

Creates a rst table of content

Parameters: None –
Returns: string
Raises: None –

verifyUrl(url=None)¶

Verify url syntax

Parameters: url – valid url
Returns: bool
Raises: None –

versionadded(text=None, version=None)¶

Create a rst versionadded box

Parameters

text – string
version – string version

Returns

string

Raises

None –

versionchanged(text=None, version=None)¶

Create a rst versionchanged box

Parameters

text – string
version – string version

Returns

string

Raises

None –

warning(text=None)¶

Create a rst warning box

Parameters: text – string
Returns: string
Raises: None –

writeRst(append=None)¶

Creates and writes markdown file

Parameters: None –
Returns: string
Raises: None –