webviz documentation¶
Introduction¶
Welcome! You are now browsing the documentation for webviz
- a static site generator,
optionally including different kind of interactive visualizations. webviz
facilitates automatic
visualization using the popular open source libraries d3.js
and plotly.js.
webviz
creates html output such that the report can be viewed through a web browser.
The site generator can be used in two different ways: using yaml
and markdown, or
the webviz
Python API.
Using folder structure and markdown files¶
Webviz can be executed using
python -m webviz site_folder
where site_folder
is a folder containing markdown files.
See the github repository
for an example. In the site_folder
, there are two special files: index.md
and
config.yaml
. index.md
is the landing page for the site and config.yaml
contains
configuration info, such as which theme to use.
In markdown files, page elements (such as visualizations) can be added using:
{{ page_element(
name,
*args,
*kwargs
}}
name
string: name of page element. Page elements are the following: Html
, FilteredPlotly
, Plotly
, LineChart
, BarChart
, PieChart
, TornadoPlot
, FanChart
, ScatterPlotMatrix
, Map
, Histogram
, ScatterPlot
, HeatMap
*args
args: args of page elements method
**kwargs
kwargs: kwargs of page elements method
API example¶
The example below creates several (currently empty) pages, linked together through a navigation menu. Further below you will see examples on how to add content to the different pages.
from webviz import Webviz, Page, SubMenu, Markdown
web = Webviz('Main title', theme='minimal')
ex1 = Page('Example 1')
ex2 = Page('Example 2')
ex3 = Page('Markdown example')
some_content = (r"""
# Markdown support
***
> __You can pass markdown wihin a triple-quotes__<br>
> _Also known as multiline comments_
|First Header | Second Header | Third Header |
|:-------------|:-------------: | ------------:|
|Content Cell | `Content Cell` | Content |
|Content Cell | Content Cell | Content |
---
#!python
def hello():
print('Hello World')
---
If you want to use math formulas, you have several different options. You can
use double dollar signs:
```
$$ \left(\frac{\sqrt x}{y^3}\right) $$
```
Result: $$ \left(\frac{\sqrt x}{y^3}\right) $$
Or you can wrap it between special commands like this:
```
\begin{equation}
\cos (2\theta) = \cos^2 \theta - \sin^2 \theta \label{my_cos_equation}.
\end{equation}
```
Result:
\begin{equation}
\cos (2\theta) = \cos^2 \theta - \sin^2 \theta \label{my_cos_equation}.
\end{equation}
All equations with labels can easily be referred to in the text as
```\eqref{my_cos_equation}```, resulting in something like
\eqref{my_cos_equation}.
If you want an equation without numbering add "notag":
```
\begin{equation}
\lim_{x \to \infty} \exp(-x) = 0.\notag
\end{equation}
```
Result:
\begin{equation}
\lim_{x \to \infty} \exp(-x) = 0.\notag
\end{equation}
If you want to write multi-line equations aligned on e.g. the equal sign, you
can also do that:
```
\begin{align}
f(x) &= (x+a)(x+b) \\\\
&= x^2 + (a+b)x + ab
\end{align}
```
Result:
\begin{align}
f(x) &= (x+a)(x+b) \\\\
&= x^2 + (a+b)x + ab
\end{align}
The & operator indicates what to align on. You can also write in-line equations
or symbols inbetween, like ```\( \alpha \)``` (\( \alpha \)) and
```\( \gamma \)``` (\( \gamma \)).
To prevent build failing because of backslashes, use a rawstring format by
adding `r` in front of the string.
You can read more about the input format
[here](http://docs.mathjax.org/en/latest/tex.html#).
Example:
`formula = Markdown(r'$$x_{1,2} = \frac{-b \pm \sqrt{b^2-4ac}}{2b}.$$')`
Renders out to this:
$$x_{1,2} = \frac{-b \pm \sqrt{b^2-4ac}}{2b}.$$
""")
ex3.add_content(Markdown(some_content))
submenu1 = SubMenu('Menu 1')
submenu2 = SubMenu('Menu 2')
submenu3 = SubMenu('Menu 3')
submenu1.add_page(ex1)
submenu2.add_page(ex2)
submenu3.add_page(ex3)
web.add(submenu1)
web.add(submenu2)
web.add(submenu3)
web.write_html("./webviz_example", overwrite=True, display=False)
When the site is created by running webviz.Webviz.write_html()
, the output is a
folder containing all the files needed for opening and running the site in a browser.
For information about how to use the webviz Python API, see the webviz package.