Generate documentation via SkyDoc (#9)
* Generate documentation via SkyDoc
* Add documentation for some attributes.
diff --git a/WORKSPACE b/WORKSPACE
index 14591aa..1bba670 100644
--- a/WORKSPACE
+++ b/WORKSPACE
@@ -5,3 +5,21 @@
name = "test_workspace",
path = __workspace_dir__ + "/tests/test_workspace",
)
+
+# Dependency of skydoc
+git_repository(
+ name = "io_bazel_rules_sass",
+ remote = "https://github.com/bazelbuild/rules_sass.git",
+ tag = "0.0.1",
+)
+load("@io_bazel_rules_sass//sass:sass.bzl", "sass_repositories")
+sass_repositories()
+
+# Used to create documentation
+git_repository(
+ name = "io_bazel_skydoc",
+ remote = "https://github.com/bazelbuild/skydoc.git",
+ tag = "0.0.5",
+)
+load("@io_bazel_skydoc//skylark:skylark.bzl", "skydoc_repositories")
+skydoc_repositories()
diff --git a/docs/BUILD b/docs/BUILD
new file mode 100644
index 0000000..b1abd6a
--- /dev/null
+++ b/docs/BUILD
@@ -0,0 +1,24 @@
+# To regenerate html docs, run:
+# ./update_docs.sh
+
+load("@io_bazel_skydoc//skylark:skylark.bzl", "skylark_doc", "skylark_library")
+
+skylark_library(
+ name = "subpar-rules",
+ srcs = [
+ "//:debug.bzl",
+ "//:subpar.bzl",
+ ],
+)
+
+skylark_doc(
+ name = "docs-html",
+ format = "markdown",
+ deps = ["subpar-rules"],
+)
+
+skylark_doc(
+ name = "docs-md",
+ format = "html",
+ deps = ["subpar-rules"],
+)
diff --git a/docs/css/main.css b/docs/css/main.css
new file mode 100755
index 0000000..f46dd08
--- /dev/null
+++ b/docs/css/main.css
@@ -0,0 +1,3 @@
+body{background-color:#fafafa}pre,code{font-family:'Liberation Mono', Consolas, Monaco, 'Andale Mono', monospace}pre{background-color:#eee;padding:20px;overflow-x:auto;word-wrap:normal}pre code{overflow-wrap:normal;white-space:pre}code{display:inline-block;font-size:90%;white-space:pre-wrap}.mdl-layout__drawer{background-color:#fff}.mdl-layout__drawer .mdl-layout-title{border-bottom:1px solid #e0e0e0;padding-left:24px}.drawer-nav ul{list-style:none;padding-left:0}.drawer-nav ul li{display:block;padding:0}.drawer-nav ul li ul li a{padding-left:44px;font-weight:400}.drawer-nav ul li a{display:block;flex-shrink:0;padding:15px 0 15px 22px;margin:0;font-weight:600;color:#757575;line-height:1em;text-decoration:none;cursor:pointer}.drawer-nav ul li a:active,.drawer-nav ul li a:hover{background-color:#f0f0f0}.drawer-nav ul li.active a{color:#4caf50;font-weight:500}h1.page-title{font-size:34px;font-weight:400;line-height:40px;margin-bottom:30px;color:#4caf50}p.lead{font-size:20px;line-height:32px}table{border-collapse:collapse;border-spacing:0;background-color:#fff;table-layout:auto}table thead th{background-color:#fafafa;border:1px solid #eee;color:#757575;padding:12px 12px 12px 24px;vertical-align:top}table tbody td{border:1px solid #eee;padding:12px 12px 12px 24px;vertical-align:top}table.params-table{width:100%}table.params-table col.col-param{width:25%}table.params-table col.col-description{width:75%}hr{margin-top:80px;margin-bottom:80px}nav.toc{border-left:5px solid #4caf50;padding-left:20px;margin-bottom:48px}nav.toc h1,nav.toc h2{font-size:15px;line-height:16px;padding-bottom:12px;margin-bottom:0;font-weight:400;color:#757575}nav.toc ul{list-style:none;margin-top:0;padding-left:0}nav.toc ul li{font-size:20px;line-height:40px}nav.toc ul li a{color:#4caf50}.page-content{margin-left:auto;margin-right:auto;padding-top:60px;padding-bottom:60px;width:760px}.page-content a{text-decoration:none}.page-content h1{font-size:34px;font-weight:400;line-height:40px;margin-bottom:30px;color:#4caf50}.page-content h2{font-size:24px;font-weight:400;line-height:32px;margin-bottom:30px;color:#4caf50}.page-content h3{font-size:20px;font-weight:400;line-height:32px;margin-bottom:30px;color:#4caf50}@media (max-width: 768px){.page-content{width:360px}}@media (min-width: 768px){.page-content{width:760px}}@media (min-width: 1476px){.page-content{width:1160px}}.mdl-mini-footer{padding-left:40px}
+
+/*# sourceMappingURL=main.css.map */
\ No newline at end of file
diff --git a/docs/debug.html b/docs/debug.html
new file mode 100644
index 0000000..a285791
--- /dev/null
+++ b/docs/debug.html
@@ -0,0 +1,122 @@
+
+<!--
+Documentation generated by Skydoc
+-->
+<!DOCTYPE html>
+<html>
+ <head>
+ <meta charset="utf-8">
+ <meta name="viewport" content="width=device-width initial-scale=1" />
+ <meta http-equiv="X-UA-Compatible" content="IE=edge">
+
+ <title>debug Rules</title>
+
+ <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,400,500,600,700" type="text/css">
+ <link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons">
+ <link rel="stylesheet" href="https://code.getmdl.io/1.1.1/material.green-light_blue.min.css">
+ <script defer src="https://code.getmdl.io/1.1.1/material.min.js"></script>
+ <link rel="stylesheet" href="css/main.css">
+ </head>
+ <body>
+ <div class="mdl-layout mdl-js-layout mdl-layout--fixed-drawer
+ mdl-layout--fixed-header">
+ <header class="mdl-layout__header">
+ <div class="mdl-layout__header-row">
+ <span class="mdl-layout-title">debug Rules</span>
+ </div>
+ </header>
+ <div class="mdl-layout__drawer">
+ <span class="mdl-layout-title">Bazel</span>
+ <nav class="drawer-nav">
+ <ul class="drawer-nav">
+
+<li>
+ <a href="debug.html">debug</a>
+ <ul>
+ <li><a href="debug.html#dump">dump</a></li>
+ </ul>
+</li>
+<li>
+ <a href="subpar.html">subpar</a>
+ <ul>
+ <li><a href="subpar.html#par_binary">par_binary</a></li>
+ <li><a href="subpar.html#parfile">parfile</a></li>
+ </ul>
+</li>
+
+ </ul>
+ </nav>
+ </div>
+
+ <main class="mdl-layout__content">
+ <div class="page-content">
+ <h1>debug Rules</h1>
+
+<nav class="toc">
+ <h2>Rules</h2>
+ <ul>
+ <li><a href="#dump">dump</a></li>
+ </ul>
+</nav>
+ <hr>
+
+ <h2 id="dump">dump</h2>
+
+ <pre>dump(<a href="#dump.obj">obj</a>, <a href="#dump.obj_name">obj_name</a>)</pre>
+
+ <p>Debugging method that recursively prints object fields to stderr</p>
+<p>Example Usage:</p>
+<pre><code>load("debug", "dump")
+...
+dump(ctx, "ctx")
+</code></pre>
+<p>Example Output:</p>
+<pre><code>WARNING: /code/rrrrr/subpar/debug.bzl:11:5:
+ctx[ctx]:
+ action[string]: <getattr(action) failed>
+ attr[struct]:
+ _action_listener[list]: []
+ _compiler[RuleConfiguredTarget]:
+ data_runfiles[runfiles]:
+</code></pre>
+
+
+ <h3 id="dump_args">Attributes</h3>
+
+<table class="params-table">
+ <colgroup>
+ <col class="col-param" />
+ <col class="col-description" />
+ </colgroup>
+ <tbody>
+ <tr id="dump.obj">
+ <td><code>obj</code></td>
+ <td>
+ <p><code>Unknown; Required</code></p>
+ <p>Object to dump</p>
+ </td>
+ </tr>
+ <tr id="dump.obj_name">
+ <td><code>obj_name</code></td>
+ <td>
+ <p><code>Unknown; Required</code></p>
+ <p>Name to print for that object</p>
+ </td>
+ </tr>
+ </tbody>
+</table>
+ </div>
+
+ <footer class="mdl-mini-footer">
+ <div class="mdl-mini-footer__left-section">
+ <div class="mdl-logo">Bazel</div>
+ <ul class="mdl-mini-footer__link-list">
+ <li><a href="http://bazel.io">Home</a></li>
+ <li><a href="https://github.com/bazelbuild">GitHub</a></li>
+ </ul>
+ </div>
+ </footer>
+ </main>
+ </div>
+ </body>
+</html>
diff --git a/docs/debug.md b/docs/debug.md
new file mode 100644
index 0000000..ee3cf80
--- /dev/null
+++ b/docs/debug.md
@@ -0,0 +1,67 @@
+
+<!---
+Documentation generated by Skydoc
+-->
+<h1>debug Rules</h1>
+
+
+<nav class="toc">
+ <h2>Rules</h2>
+ <ul>
+ <li><a href="#dump">dump</a></li>
+ </ul>
+</nav>
+<a name="dump"></a>
+## dump
+
+<pre>
+dump(<a href="#dump.obj">obj</a>, <a href="#dump.obj_name">obj_name</a>)
+</pre>
+
+Debugging method that recursively prints object fields to stderr
+
+Example Usage:
+```
+load("debug", "dump")
+...
+dump(ctx, "ctx")
+```
+
+Example Output:
+```
+WARNING: /code/rrrrr/subpar/debug.bzl:11:5:
+ctx[ctx]:
+ action[string]: <getattr(action) failed>
+ attr[struct]:
+ _action_listener[list]: []
+ _compiler[RuleConfiguredTarget]:
+ data_runfiles[runfiles]:
+```
+
+
+<a name="dump_args"></a>
+### Attributes
+
+
+<table class="params-table">
+ <colgroup>
+ <col class="col-param" />
+ <col class="col-description" />
+ </colgroup>
+ <tbody>
+ <tr id="dump.obj">
+ <td><code>obj</code></td>
+ <td>
+ <p><code>Unknown; Required</code></p>
+ <p>Object to dump</p>
+ </td>
+ </tr>
+ <tr id="dump.obj_name">
+ <td><code>obj_name</code></td>
+ <td>
+ <p><code>Unknown; Required</code></p>
+ <p>Name to print for that object</p>
+ </td>
+ </tr>
+ </tbody>
+</table>
diff --git a/docs/subpar.html b/docs/subpar.html
new file mode 100644
index 0000000..1bd624d
--- /dev/null
+++ b/docs/subpar.html
@@ -0,0 +1,175 @@
+
+<!--
+Documentation generated by Skydoc
+-->
+<!DOCTYPE html>
+<html>
+ <head>
+ <meta charset="utf-8">
+ <meta name="viewport" content="width=device-width initial-scale=1" />
+ <meta http-equiv="X-UA-Compatible" content="IE=edge">
+
+ <title>Build self-contained python executables.</title>
+
+ <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,400,500,600,700" type="text/css">
+ <link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons">
+ <link rel="stylesheet" href="https://code.getmdl.io/1.1.1/material.green-light_blue.min.css">
+ <script defer src="https://code.getmdl.io/1.1.1/material.min.js"></script>
+ <link rel="stylesheet" href="css/main.css">
+ </head>
+ <body>
+ <div class="mdl-layout mdl-js-layout mdl-layout--fixed-drawer
+ mdl-layout--fixed-header">
+ <header class="mdl-layout__header">
+ <div class="mdl-layout__header-row">
+ <span class="mdl-layout-title">Build self-contained python executables.</span>
+ </div>
+ </header>
+ <div class="mdl-layout__drawer">
+ <span class="mdl-layout-title">Bazel</span>
+ <nav class="drawer-nav">
+ <ul class="drawer-nav">
+
+<li>
+ <a href="debug.html">debug</a>
+ <ul>
+ <li><a href="debug.html#dump">dump</a></li>
+ </ul>
+</li>
+<li>
+ <a href="subpar.html">subpar</a>
+ <ul>
+ <li><a href="subpar.html#par_binary">par_binary</a></li>
+ <li><a href="subpar.html#parfile">parfile</a></li>
+ </ul>
+</li>
+
+ </ul>
+ </nav>
+ </div>
+
+ <main class="mdl-layout__content">
+ <div class="page-content">
+ <h1>Build self-contained python executables.</h1>
+
+<nav class="toc">
+ <h2>Rules</h2>
+ <ul>
+ <li><a href="#par_binary">par_binary</a></li>
+ <li><a href="#parfile">parfile</a></li>
+ </ul>
+</nav>
+ <hr>
+
+ <h2 id="par_binary">par_binary</h2>
+
+ <pre>par_binary(<a href="#par_binary.name">name</a>)</pre>
+
+ <p>An executable Python program.</p>
+<p>par_binary() is a drop-in replacement for py_binary() that also
+builds a self-contained, single-file executable for the
+application, with a .par file extension.</p>
+<p>See <a href="http://www.bazel.io/docs/be/python.html#py_binary">py_binary</a>
+for arguments and usage.</p>
+
+
+ <h3 id="par_binary_args">Attributes</h3>
+
+<table class="params-table">
+ <colgroup>
+ <col class="col-param" />
+ <col class="col-description" />
+ </colgroup>
+ <tbody>
+ <tr id="par_binary.name">
+ <td><code>name</code></td>
+ <td>
+ <p><code><a href="http://bazel.io/docs/build-ref.html#name">Name</a>; Required</code></p>
+ <p>A unique name for this rule.</p>
+ </td>
+ </tr>
+ </tbody>
+</table>
+ <hr>
+
+ <h2 id="parfile">parfile</h2>
+
+ <pre>parfile(<a href="#parfile.name">name</a>, <a href="#parfile.src">src</a>, <a href="#parfile.compiler">compiler</a>, <a href="#parfile.default_python_version">default_python_version</a>, <a href="#parfile.imports">imports</a>, <a href="#parfile.main">main</a>)</pre>
+
+ <p>A self-contained, single-file Python program, with a .par file extension.</p>
+<p>You probably want to use par_binary() instead of this.</p>
+<p>TODO(b/27502830): A directory foo.par.runfiles is also created. This
+is a bug, don't use or depend on it.</p>
+
+
+ <h3 id="parfile_args">Attributes</h3>
+
+<table class="params-table">
+ <colgroup>
+ <col class="col-param" />
+ <col class="col-description" />
+ </colgroup>
+ <tbody>
+ <tr id="parfile.name">
+ <td><code>name</code></td>
+ <td>
+ <p><code><a href="http://bazel.io/docs/build-ref.html#name">Name</a>; Required</code></p>
+ <p>A unique name for this rule.</p>
+ </td>
+ </tr>
+ <tr id="parfile.src">
+ <td><code>src</code></td>
+ <td>
+ <p><code><a href="http://bazel.io/docs/build-ref.html#labels">Label</a>; Required</code></p>
+ <p>A py_binary() target</p>
+ </td>
+ </tr>
+ <tr id="parfile.compiler">
+ <td><code>compiler</code></td>
+ <td>
+ <p><code><a href="http://bazel.io/docs/build-ref.html#labels">Label</a>; Optional</code></p>
+ <p>Internal use only.</p>
+ </td>
+ </tr>
+ <tr id="parfile.default_python_version">
+ <td><code>default_python_version</code></td>
+ <td>
+ <p><code>String; Required</code></p>
+ <p>A string specifying the default Python major version to use when building this par file.</p>
+<p>See <a href="http://www.bazel.io/docs/be/python.html#py_binary.default_python_version">py_binary.default_python_version</a></p>
+ </td>
+ </tr>
+ <tr id="parfile.imports">
+ <td><code>imports</code></td>
+ <td>
+ <p><code>List of strings; Optional</code></p>
+ <p>List of import directories to be added to the PYTHONPATH.</p>
+<p>See <a href="http://www.bazel.io/docs/be/python.html#py_binary.imports">py_binary.imports</a></p>
+ </td>
+ </tr>
+ <tr id="parfile.main">
+ <td><code>main</code></td>
+ <td>
+ <p><code><a href="http://bazel.io/docs/build-ref.html#labels">Label</a>; Required</code></p>
+ <p>The name of the source file that is the main entry point of
+the application.</p>
+<p>See <a href="http://www.bazel.io/docs/be/python.html#py_binary.main">py_binary.main</a></p>
+ </td>
+ </tr>
+ </tbody>
+</table>
+ </div>
+
+ <footer class="mdl-mini-footer">
+ <div class="mdl-mini-footer__left-section">
+ <div class="mdl-logo">Bazel</div>
+ <ul class="mdl-mini-footer__link-list">
+ <li><a href="http://bazel.io">Home</a></li>
+ <li><a href="https://github.com/bazelbuild">GitHub</a></li>
+ </ul>
+ </div>
+ </footer>
+ </main>
+ </div>
+ </body>
+</html>
diff --git a/docs/subpar.md b/docs/subpar.md
new file mode 100644
index 0000000..f183464
--- /dev/null
+++ b/docs/subpar.md
@@ -0,0 +1,123 @@
+
+<!---
+Documentation generated by Skydoc
+-->
+<h1>Build self-contained python executables.</h1>
+
+
+<nav class="toc">
+ <h2>Rules</h2>
+ <ul>
+ <li><a href="#par_binary">par_binary</a></li>
+ <li><a href="#parfile">parfile</a></li>
+ </ul>
+</nav>
+<a name="par_binary"></a>
+## par_binary
+
+<pre>
+par_binary(<a href="#par_binary.name">name</a>)
+</pre>
+
+An executable Python program.
+
+par_binary() is a drop-in replacement for py_binary() that also
+builds a self-contained, single-file executable for the
+application, with a .par file extension.
+
+See [py_binary](http://www.bazel.io/docs/be/python.html#py_binary)
+for arguments and usage.
+
+
+<a name="par_binary_args"></a>
+### Attributes
+
+
+<table class="params-table">
+ <colgroup>
+ <col class="col-param" />
+ <col class="col-description" />
+ </colgroup>
+ <tbody>
+ <tr id="par_binary.name">
+ <td><code>name</code></td>
+ <td>
+ <p><code><a href="http://bazel.io/docs/build-ref.html#name">Name</a>; Required</code></p>
+ <p>A unique name for this rule.</p>
+ </td>
+ </tr>
+ </tbody>
+</table>
+<a name="parfile"></a>
+## parfile
+
+<pre>
+parfile(<a href="#parfile.name">name</a>, <a href="#parfile.src">src</a>, <a href="#parfile.compiler">compiler</a>, <a href="#parfile.default_python_version">default_python_version</a>, <a href="#parfile.imports">imports</a>, <a href="#parfile.main">main</a>)
+</pre>
+
+A self-contained, single-file Python program, with a .par file extension.
+
+You probably want to use par_binary() instead of this.
+
+TODO(b/27502830): A directory foo.par.runfiles is also created. This
+is a bug, don't use or depend on it.
+
+
+<a name="parfile_args"></a>
+### Attributes
+
+
+<table class="params-table">
+ <colgroup>
+ <col class="col-param" />
+ <col class="col-description" />
+ </colgroup>
+ <tbody>
+ <tr id="parfile.name">
+ <td><code>name</code></td>
+ <td>
+ <p><code><a href="http://bazel.io/docs/build-ref.html#name">Name</a>; Required</code></p>
+ <p>A unique name for this rule.</p>
+ </td>
+ </tr>
+ <tr id="parfile.src">
+ <td><code>src</code></td>
+ <td>
+ <p><code><a href="http://bazel.io/docs/build-ref.html#labels">Label</a>; Required</code></p>
+ <p>A py_binary() target</p>
+ </td>
+ </tr>
+ <tr id="parfile.compiler">
+ <td><code>compiler</code></td>
+ <td>
+ <p><code><a href="http://bazel.io/docs/build-ref.html#labels">Label</a>; Optional</code></p>
+ <p>Internal use only.</p>
+ </td>
+ </tr>
+ <tr id="parfile.default_python_version">
+ <td><code>default_python_version</code></td>
+ <td>
+ <p><code>String; Required</code></p>
+ <p>A string specifying the default Python major version to use when building this par file.</p>
+<p>See <a href="http://www.bazel.io/docs/be/python.html#py_binary.default_python_version">py_binary.default_python_version</a></p>
+ </td>
+ </tr>
+ <tr id="parfile.imports">
+ <td><code>imports</code></td>
+ <td>
+ <p><code>List of strings; Optional</code></p>
+ <p>List of import directories to be added to the PYTHONPATH.</p>
+<p>See <a href="http://www.bazel.io/docs/be/python.html#py_binary.imports">py_binary.imports</a></p>
+ </td>
+ </tr>
+ <tr id="parfile.main">
+ <td><code>main</code></td>
+ <td>
+ <p><code><a href="http://bazel.io/docs/build-ref.html#labels">Label</a>; Required</code></p>
+ <p>The name of the source file that is the main entry point of
+the application.</p>
+<p>See <a href="http://www.bazel.io/docs/be/python.html#py_binary.main">py_binary.main</a></p>
+ </td>
+ </tr>
+ </tbody>
+</table>
diff --git a/subpar.bzl b/subpar.bzl
index 8506a8c..f2898b2 100644
--- a/subpar.bzl
+++ b/subpar.bzl
@@ -134,6 +134,12 @@
See [py_binary.imports](http://www.bazel.io/docs/be/python.html#py_binary.imports)
+ default_python_version: A string specifying the default Python major version to use when building this par file.
+
+ See [py_binary.default_python_version](http://www.bazel.io/docs/be/python.html#py_binary.default_python_version)
+
+ compiler: Internal use only.
+
TODO(b/27502830): A directory foo.par.runfiles is also created. This
is a bug, don't use or depend on it.
diff --git a/update_docs.sh b/update_docs.sh
new file mode 100755
index 0000000..dfba97c
--- /dev/null
+++ b/update_docs.sh
@@ -0,0 +1,22 @@
+#!/bin/bash
+
+# Copyright 2016 Google Inc. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+set -euo pipefail
+
+bazel build //docs/...
+unzip -d docs/ -o bazel-bin/docs/docs-md-skydoc.zip
+unzip -d docs/ -o bazel-bin/docs/docs-html-skydoc.zip
+perl -i -pe 's|href="/css/main.css"|href="css/main.css"|' docs/*.html
