Adds conf to build /docs into nice HTML docs.
authorDavid Schoonover <dsc@wikimedia.org>
Fri, 29 Jun 2012 13:29:33 +0000 (06:29 -0700)
committerDavid Schoonover <dsc@wikimedia.org>
Fri, 29 Jun 2012 13:29:33 +0000 (06:29 -0700)
13 files changed:
.gitignore
.markdoc.yaml [new symlink]
docs/README.md [new symlink]
docs/internals/chart-types/timeseries-options.md [new file with mode: 0644]
msc/markdoc/404.html [new file with mode: 0644]
msc/markdoc/base.html [new file with mode: 0644]
msc/markdoc/document.html [new file with mode: 0644]
msc/markdoc/listing.html [new file with mode: 0644]
msc/markdoc/macros/html [new file with mode: 0644]
msc/markdoc/markdoc.yaml [new file with mode: 0644]
static/css/github-readme.css [moved from docs/assets/github-readme.css with 100% similarity]
static/css/solarized.css [moved from docs/assets/solarized.css with 100% similarity]
www/css/docs.styl [new file with mode: 0644]

index ac951e7..2488c18 100644 (file)
@@ -36,3 +36,5 @@ lib/version.js
 www/presets/*.json
 
 .cache
+.tmp
+
diff --git a/.markdoc.yaml b/.markdoc.yaml
new file mode 120000 (symlink)
index 0000000..4737e1f
--- /dev/null
@@ -0,0 +1 @@
+msc/markdoc/markdoc.yaml
\ No newline at end of file
diff --git a/docs/README.md b/docs/README.md
new file mode 120000 (symlink)
index 0000000..32d46ee
--- /dev/null
@@ -0,0 +1 @@
+../README.md
\ No newline at end of file
diff --git a/docs/internals/chart-types/timeseries-options.md b/docs/internals/chart-types/timeseries-options.md
new file mode 100644 (file)
index 0000000..e8aaf32
--- /dev/null
@@ -0,0 +1,68 @@
+# Timeseries Chart Options
+
+Right now, all options are global (apply to all metrics of a chart) because that's how Dygraph worked. This doesn't make sense when you have per-metric options, which we see bleeding in now with color etc, or when you want to mix and match chart-types.
+
+That said, most "local" (per-metric) options also make sense as global defaults for new metrics. Cases where that doesn't hold are noted.
+
+
+## Local Per-Metric Options
+
+- id
+- enabled
+- visible
+- type
+
+- label
+- format
+- timespan: [start, stop] -- inferred
+- stroke[]
+    - width: 4.0
+    - color: default from palette
+    - opacity: 1.0
+    - style: solid | dashed | dotted -- presets for advanced options which are otherwise hidden
+        - solid  := (all defaults)
+        - dashed := dashes:[2,2]
+        - dotted := dashes:[1,1], caps:round, joins:round
+    - (advanced options)
+    - dashes: null | dash pattern array (int array) -- null == solid
+    - caps: butt | round | square
+    - joins: miter | round | bevel
+- fill: null | color | gradient?
+- opacity: 1.0
+- points
+    - enabled: false
+    - size: 0
+    - color: inherit from first stroke
+- horizon: false
+- smoothing: false
+- axis
+    - scale: linear | log | sqrt | pow | (discrete | quantize | quantile)?
+    - scaleQuanta: Number -- for linear, log(?), pow, discrete, quant*
+    - range: [min, max] -- auto-inferred from dataset extents
+    - ticks: Number
+    - format: inherit from format
+- data
+    - errorBars: false | choose error data column
+
+## Chart-Global Options
+
+- palette
+- stacked: false
+- axis
+- grid[x,y]
+    - enabled: false
+    - stroke
+- timespan: [start, stop] -- inferred
+- legend
+    - enabled: true
+    - fixed: false -- when true, graph is smaller to accommodate legend; otherwise, legend moves itself
+    - draggable: false -- legend won't dodge the mouse so you can grab it
+- zoom
+    - enabled: true -- enables Y-zoom independent of pan
+    - starting: 1.0
+    - range: [min, max]
+- pan
+    - enabled: true
+    - starting: [0, 1.0] -- Floats as % of timespan, or Dates
+- minimap: false
+- transitions: ?
\ No newline at end of file
diff --git a/msc/markdoc/404.html b/msc/markdoc/404.html
new file mode 100644 (file)
index 0000000..ac434a7
--- /dev/null
@@ -0,0 +1,11 @@
+{% extends 'base.html' %}
+
+{% block title %}Not Found: {{ request.path_info|e }}{% endblock %}
+
+{% block content %}
+<h1>Not Found: <code>{{ request.path_info|e }}</code></h1>
+<p>
+  We couldn’t find what you were looking for.
+  {% if not is_index %}You could try going <a href="/">home</a>.{% endif %}
+</p>
+{% endblock %}
diff --git a/msc/markdoc/base.html b/msc/markdoc/base.html
new file mode 100644 (file)
index 0000000..f997b20
--- /dev/null
@@ -0,0 +1,94 @@
+<!DOCTYPE html>
+<html>
+{% import "macros/html" as html -%}
+
+<head>
+  {% block head %}
+    
+    {% block meta %}
+      <meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
+    {% endblock %}
+    
+    <title>
+      {% block title -%}
+        {{ title }}
+      {%- endblock %}
+      {% block title_suffix -%}
+        {% if 'wiki-name' in config %} | {{ config['wiki-name']|e }}{% endif %}
+      {%- endblock %}
+    </title>
+    
+    {% block css %}
+      {{ html.cssimport("/vendor/bootstrap/css/bootstrap.min.css") }}
+      {{ html.cssimport("/css/solarized.css") }}
+      {{ html.cssimport("/css/docs.css") }}
+    {% endblock %}
+    
+  {% endblock head %}
+</head>
+
+<body {% block body_attrs %}{% endblock %}><div id="content">{% block body %}
+
+{% block header %}
+  <header>
+  {% block crumbs %}
+    {% if crumbs %}
+      <ul class="breadcrumb">
+        {% if 'wiki-name' in config %}
+          <li id="wiki-name">{{ config['wiki-name']|e }} <span class="divider">&sect;</span></li>
+        {% endif %}
+        {% for name, href in crumbs %}
+          <li>
+          {% if href == None %}
+            {{ name|e }}
+          {% else %}
+              <a href="{{ make_relative(href)|e }}">{{ name|e }}</a>{% if loop.revindex0 %} <span class="divider">/</span>{% endif %}
+          {% endif %}
+          </li>
+        {% endfor %}
+      </ul> <!-- ul.breadcrumbs -->
+    {% endif %}
+  {% endblock crumbs %}
+  </header>
+{% endblock header %}
+
+<div id="doc">
+  {% block content %}
+  {% endblock content %}
+</div> <!-- div#content -->
+
+{% block footer %}
+  <footer>
+    Powered by <a href="http://bitbucket.org/zacharyvoase/markdoc">Markdoc</a>.
+  </footer>
+{% endblock footer %}
+
+{% block end %}{% endblock %}
+
+{% block scripts %}
+  <div class="scripts">
+    {% block vendor %}
+      {{ html.jsimport("/vendor/jquery.min.js") }}
+      {{ html.jsimport("/vendor/bootstrap.min.js") }}
+    {% endblock %}
+    {% block analytics %}
+      {% if 'google-analytics' in config %}
+        <!-- Google Analytics -->
+        <script type="text/javascript">
+          var _gaq = _gaq || [];
+          _gaq.push(['_setAccount', '{{ config['google-analytics'] }}']);
+          _gaq.push(['_trackPageview']);
+          (function() {
+            var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+            ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+            (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(ga);
+          })();
+        </script>
+      {% endif %}
+    {% endblock analytics %}
+    {% block js %}{% endblock %}
+  </div>
+{% endblock scripts %}
+
+{% endblock body %}</div></body>
+</html>
diff --git a/msc/markdoc/document.html b/msc/markdoc/document.html
new file mode 100644 (file)
index 0000000..03a1f34
--- /dev/null
@@ -0,0 +1,5 @@
+{% extends 'base.html' %}
+
+{% block content %}
+{{ content | replace('<h1', '<h1 class="page-header"') }}
+{% endblock %}
diff --git a/msc/markdoc/listing.html b/msc/markdoc/listing.html
new file mode 100644 (file)
index 0000000..b57dac0
--- /dev/null
@@ -0,0 +1,57 @@
+{% extends 'base.html' %}
+
+{% block title %}ls /{{ directory|e }}{% endblock %}
+
+{% block content %}
+  <h1><code>ls /{{ directory|e }}</code></h1>
+
+  {% if sub_directories %}
+  <h2>Directories</h2>
+
+  <table id="subdirs">
+    {% for subdir in sub_directories %}
+      <tr>
+        <td class="name">
+          <a class="dirlink" href="{{ make_relative(subdir.href)|e }}">
+            {{ subdir.basename|e }}/
+          </a>
+        </td>
+      </tr>
+    {% endfor %}
+  </table>
+  {% endif %}
+
+  {% if pages %}
+  <h2>Pages</h2>
+
+  <table id="pages">
+    {% for page in pages %}
+      <tr>
+        <td class="size">{{ page.humansize }}</td>
+        <td class="name">
+          <a href="{{ make_relative(page.href)|e }}" title="{{ page.title|e }}">
+            {{ page.title|e }}
+          </a>
+        </td>
+      </tr>
+    {% endfor %}
+  </table>
+  {% endif %}
+
+  {% if files %}
+  <h2>Files</h2>
+
+  <table id="files">
+    {% for file in files %}
+      <tr>
+        <td class="size">{{ file.humansize }}</td>
+        <td class="name">
+          <a href="{{ make_relative(file.href)|e }}">
+            <code>{{ file.basename|e }}</code>
+          </a>
+        </td>
+      </tr>
+    {% endfor %}
+  </table>
+  {% endif %}
+{% endblock %}
diff --git a/msc/markdoc/macros/html b/msc/markdoc/macros/html
new file mode 100644 (file)
index 0000000..833f169
--- /dev/null
@@ -0,0 +1,19 @@
+{% macro cssimport(css_href, media="screen, projection") -%}
+    <link rel="stylesheet" type="text/css" href="{{ css_href }}" {% if media %}media="{{ media }}" {% endif %}/>
+{%- endmacro %}
+
+{% macro css() -%}
+    <style type="text/css">
+        {{ caller() }}
+    </style>
+{%- endmacro %}
+
+{% macro jsimport(js_href) -%}
+    <script type="application/javascript" src="{{ js_href }}"></script>
+{%- endmacro %}
+
+{% macro js() -%}
+    <script type="text/javascript">
+        {{ caller() }}
+    </script>
+{%- endmacro %}
diff --git a/msc/markdoc/markdoc.yaml b/msc/markdoc/markdoc.yaml
new file mode 100644 (file)
index 0000000..acd521e
--- /dev/null
@@ -0,0 +1,37 @@
+wiki-name             : Limn Docs
+
+wiki-dir              : "docs"
+template-dir          : "msc/markdoc"
+static-dir            : "msc/markdoc/static"
+html-dir              : "var/docs"
+temp-dir              : ".tmp"
+
+use-default-static    : false
+use-default-templates : false
+generate-listing      : always
+hide-prefix           : "."
+cvs-exclude           : true
+listing-filename      : "_list.html"
+
+markdown:
+    output-format: html5
+    extensions:
+        - abbr
+        - codehilite
+        - def_list
+        - extra
+        - fenced_code
+        - footnotes
+        - headerid
+        - meta
+        - tables
+        - toc
+        # - rss
+        # - html_tidy
+        # - imagelinks
+        # - wikilinks
+    extension-configs:
+        codehilite:
+            force_linenos: false
+
+
diff --git a/www/css/docs.styl b/www/css/docs.styl
new file mode 100644 (file)
index 0000000..571d298
--- /dev/null
@@ -0,0 +1,36 @@
+h1, h2, h3, h4, h5 
+    font-weight normal
+    margin 0
+    margin-top 1em
+    padding 0.5em 0
+
+h1.page-header 
+    // font-size 30px
+    padding-bottom 0
+
+h2 
+    font-size 18px
+
+h3, h4 
+    font-size 13px
+    text-transform uppercase
+    letter-spacing 0.2em
+    word-spacing 0.1em
+
+
+#content
+    height 100%
+
+header, #doc
+    margin 0 auto
+    width 60%
+    max-width 800px
+    min-width 600px
+
+footer
+    margin-top 3em
+    padding 1em 3em 3em
+    background-color #fbfbfb
+    border-top 1px solid #ddd
+    font-size 11px
+