docs: improved element reference page

![BSD-License](https://img.shields.io/badge/license-BSD-blue.svg?style=flat-square)

PlotFX is a tool for creating data-driven graphics; it allows you to create

parametric illustrations such as charts and dashboards using a lighweight

parametric illustrations such as charts and dashboards using a lightweight

CSS-like syntax.

You can run PlotFX from the command line, where it generates SVG, PNG and PDF

from build_layout import *

import markdown

import yaml

import glob

def build_prop_overview(parent):

  tpl = """

    <section class="api_ref">

      {{{elem_name}}}

      <div class="plist">

        {{#props}}

          <a href="/reference/{{scope}}/{{name}}" class="prop">

            <span><code><strong>{{name}}</strong></code></span>

            <span>{{desc}}</span>

          </a>

        {{/props}}

      </div>

    </section>

  """

  if parent["path"] == "global":

    elem_name = "<h2>Global Properties</h2>"

  else:

    elem_name = TPL.render(

        "<h2>Element <code>{{name}}</code></h2>",

        {

          'name': parent["path"]

        })

  if "cond" in parent:

    elem_name += TPL.render(

        "<h2 class=sub>where <code>{{cond}}</code></h2>",

        {

          'cond': parent["cond"]

        })

  props = []

  for prop in parent["properties"]:

    props.append({

      "scope": parent["id"],

      "name": prop["name"],

      "desc": prop["desc_short"] if "desc_short" in prop else "",

    })

  return TPL.render(tpl, {

    "props": props,

    "elem_name": elem_name

  })

def build_prop_detail(parent, prop):

  url = parent["id"] + "/" + prop["name"]

  print("> Building page: /reference/%s" % url)

  title = "%s | %s | API Reference" % (prop["name"], parent["path"])

def build_elem_page(elem_file):

  elem = yaml.load(open(elem_file))

  url = "/elements/" + elem["name"]

  print("> Building page: %s" % url)

  title = "%s | API Reference" % (elem["name"])

  tpl = Path("extra/web/reference_detail.tpl.html").read_text()

  path = "/reference/" + url

  env = {

    "name": prop["name"],

    "description": markdown.markdown(prop.get("desc", prop["desc_short"])),

    "demo": prop.get("demo", ""),

    "syntax_formal": prop.get("syntax_formal", ""),

    "syntax_example": prop.get("syntax_example", ""),

    "values": prop.get("values", []),

    "default": markdown.markdown(prop.get("default", "")),

    "scope": markdown.markdown(prop.get("scope", "")),

    "scope_example": prop.get("scope_example", ""),

  }

  html = TPL.render(tpl, env)

  write_page(path, html, title=title)

  html = TPL.render(tpl, elem)

  write_page(url, html, title=title)

def main():

  tree = yaml.load(open('manual/properties.yml'))

  html = ""

  for elem in tree["elements"]:

    html += build_prop_overview(elem)

    for prop in elem["properties"]:

      build_prop_detail(elem, prop)

  tpl = """

    <h1>API Reference</h1>

    {{{html}}}

  """

  write_file("/_reference.gen.html", html)

  elems = glob.glob("manual/elem_*.yaml*")

  for elem in elems:

    build_elem_page(elem)

main()

import re

def build_page(page):

  if not "file" in page:

    return

  print("> Building page: %s" % page["url"])

  url = page["url"]

  path = "manual/" + page["file"] + ".md"

  margin-top: 0;

}

#documentation .api_ref {

#documentation .info_box {

  border: 1px solid #ddd;

  margin-top: 2em;

  margin-bottom: 3em;

  border-radius: 2px;

  padding-top: .5em;

}

#documentation .api_ref code strong {

#documentation .info_box code strong {

  font-size: 110%;

}

#documentation .api_ref h2 {

#documentation .info_box h2 {

  border-bottom: none;

  margin-top: .2em;

  margin-top: .1em;

  margin-bottom: 0;

  padding-bottom: 0;

  font-weight: 600;

  padding-left: 14px;

  font-size: 14pt;

  line-height: 18pt;

  font-size: 11pt;

  line-height: 12pt;

  font-weight: 400;

  color: #888;

}

#documentation .api_ref h2.sub {

#documentation .info_box h2.sub {

  font-size: 11pt;

  margin-top: 0;

  padding-top: 0;

  line-height: 16pt;

}

#documentation .api_ref .plist {

  display: table;

#documentation .info_box > div {

  border-top: 2px solid #ddd;

  margin-top: .6em;

}

#documentation .plist {

  display: table;

  margin-bottom: 0;

  width: 100%;

}

#documentation .api_ref .prop {

#documentation .plist .prop {

  display: table-row;

  width: 100%;

  color: inherit;

}

#documentation .api_ref .prop:nth-child(2n+0) { background-color: #f8f8f8; }

#documentation .plist .prop:nth-child(2n+0) { background-color: #f8f8f8; }

#documentation .api_ref .prop:hover {

#documentation .plist .prop:hover {

  background: #00f;

  color: #fff;

  text-decoration: none;

}

#documentation .api_ref .prop > span {

#documentation .plist .prop > span {

  display: table-cell;

  padding: 6px 6px 5px 6px;

  text-align: left;

<h1>Property: <code>{{name}}</code></h1>

<h1>Element: <code>{{name}}</code></h1>

{{{desc}}}

{{{description}}}

<pre><code>{{demo}}</code></pre>

<h3 class="section">Syntax</h3>

<pre><code>{{syntax_formal}}</code></pre>

<h2>Example</h2>

<section class="info_box" style="margin-top: 1.4em;">

  <h2>Example Output</h2>

  <div>

    <img src="/examples/linecharts/simple_timeseries.svg" />

  </div>

</section>

<pre><code>{{syntax_example}}</code></pre>

<h2>Properties</h2>

<div class="plist">

  {{#properties}}

    <a href="/reference/{{scope}}/{{name}}" class="prop">

      <span><code><strong>{{name}}</strong></code></span>

      <span>{{desc_short}}</span>

    </a>

  {{/properties}}

</div>

<h3 class="section">Values</h3>

{{#properties}}

  <section style="border-top: none; padding-bottom: 1em;">

    <h2>Property: <code>{{name}}</code></h2>

    {{desc_short}}

    <pre><code>{{syntax_formal}}</code></pre>

    <h4>Values</h4>

    <dl>

      {{#values}}

        <dt><code>{{value}}</code></dt>

      {{/values}}

    </dl>

<h3 class="section">Default Value</h3>

{{{default}}}

<h3 class="section">Scope</h3>

{{{scope}}}

<pre><code>{{scope_example}}</code></pre>

<!--

<h3 class="section">Examples</h3>

<ul>

  <li><a href="/examples/barcharts/vertical_ranges">barcharts/vertical_ranges</a></li>

  <li><a href="/examples/barcharts/horizontal_ranges">barcharts/horizontal_ranges</a></li>

  <li><a href="/examples/barcharts/barsandlines">barcharts/barsandlines</a></li>

  <li><a href="/examples/barcharts/horizontal_bars">barcharts/horizontal_bars</a></li>

  <li><a href="/examples/barcharts/vertical_bars">barcharts/vertical_bars</a></li>

  <li><a href="/examples/barcharts/negative_values">barcharts/negative_values</a></li>

  <li><a href="/examples/pointcharts/simple_scatter">pointcharts/simple_scatter</a></li>

  <li><a href="/examples/pointcharts/pointchart_with_labels">pointcharts/pointchart_with_labels</a></li>

  <li><a href="/examples/pointcharts/simple_bubbles">pointcharts/simple_bubbles</a></li>

  <li><a href="/examples/linecharts/irregular_data">linecharts/irregular_data</a></li>

  <li><a href="/examples/linecharts/lines_with_points">linecharts/lines_with_points</a></li>

  <li><a href="/examples/linecharts/logarithmic_domain">linecharts/logarithmic_domain</a></li>

  <li><a href="/examples/linecharts/multiple_y_axes">linecharts/multiple_y_axes</a></li>

  <li><a href="/examples/linecharts/lines_with_labels">linecharts/lines_with_labels</a></li>

  <li><a href="/examples/linecharts/explicit_domain">linecharts/explicit_domain</a></li>

  <li><a href="/examples/linecharts/inverted_axis">linecharts/inverted_axis</a></li>

  <li><a href="/examples/linecharts/simple_timeseries">linecharts/simple_timeseries</a></li>

  <li><a href="/examples/areacharts/arearange_and_line">areacharts/arearange_and_line</a></li>

  <li><a href="/examples/areacharts/area_with_points">areacharts/area_with_points</a></li>

  <li><a href="/examples/areacharts/area_ranges">areacharts/area_ranges</a></li>

  <li><a href="/examples/areacharts/simple_area">areacharts/simple_area</a></li>

</ul>

-->

    <h4>Examples</h4>

    <pre><code>{{syntax_example}}</code></pre>

  </section>

{{/properties}}