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.