Remove a number of files related to legacy skydoc (#3)
diff --git a/.gitignore b/.gitignore index 7c504ec..a7f7d95 100644 --- a/.gitignore +++ b/.gitignore
@@ -8,7 +8,7 @@ /.settings /WORKSPACE.user.bzl /base_workspace/* -/bazel-skydoc +/bazel-stardoc /bazel-bin /bazel-genfiles /bazel-out
diff --git a/CONTRIBUTORS b/CONTRIBUTORS index e8e0f12..c186cc2 100644 --- a/CONTRIBUTORS +++ b/CONTRIBUTORS
@@ -9,4 +9,7 @@ # Names should be added to this file as: # Name <email address> -David Z. Chen <dzc@google.com> +Jon Brandvein <brandjon@google.com> +Chris Parsons <cparsons@google.com> +Jingwen Chen <jingwen@google.com> +Laurent Le Brun <laurentlb@google.com>
diff --git a/README.md b/README.md index b9afc1d..a27ed44 100644 --- a/README.md +++ b/README.md
@@ -1,31 +1,11 @@ # [Stardoc](https://skydoc.bazel.build) - Starlark Documentation Generator -[](https://buildkite.com/bazel/skydoc-postsubmit) - Stardoc is a documentation generator for [Bazel](https://bazel.build) build rules written in [Starlark](https://bazel.build/docs/skylark/index.html). -Stardoc provides a Starlark rule (`stardoc`) that can be used to build documentation -for Starlark rules in Markdown. Stardoc generates one documentation page per `.bzl` file. - -## Skydoc deprecation - -NOTE: Stardoc is a replacement for the **deprecated** "Skydoc" documentation generator. - -See [Skydoc Deprecation](https://skydoc.bazel.build/docs/skydoc_deprecation.html) for -details on the deprecation, and for some migration tips. - -## Get Started - -* How to [set up Stardoc for your project](https://skydoc.bazel.build/docs/getting_started_stardoc.html) -* Writing [docstrings](https://skydoc.bazel.build/docs/writing_stardoc.html) -* How to [integrate Stardoc with your build](https://skydoc.bazel.build/docs/generating_stardoc.html). - -## About Stardoc - -* How to [contribute to Stardoc](https://skydoc.bazel.build/contributing.html) -* See the [Stardoc roadmap](https://skydoc.bazel.build/roadmap.html) - - - +This repository is currently in a transitionary state as pieces of the +[bazelbuild/skydoc](https://github.com/bazelbuild/skydoc) repository + are being moved to this one. Use the +[bazelbuild/skydoc](https://github.com/bazelbuild/skydoc) repository +for the time being.
diff --git a/WORKSPACE b/WORKSPACE index 1021b95..d4813e5 100644 --- a/WORKSPACE +++ b/WORKSPACE
@@ -5,31 +5,11 @@ skydoc_repositories() -load("@io_bazel_rules_sass//:package.bzl", "rules_sass_dependencies") - -rules_sass_dependencies() - -load("@build_bazel_rules_nodejs//:defs.bzl", "node_repositories") - -node_repositories() - -load("@io_bazel_rules_sass//:defs.bzl", "sass_repositories") - -sass_repositories() - ####################################################################### ##### MOST USERS SHOULD NOT NEED TO COPY ANYTHING BELOW THIS LINE ##### ####################################################################### load("@bazel_tools//tools/build_defs/repo:git.bzl", "git_repository") -# Needed for skydoc only (not Stardoc), which is deprecated. Users should include -# this in their WORKSPACE only if they need skydoc. -git_repository( - name = "com_google_protobuf", - commit = "7b28271a61a3da0a37f6fda399b0c4c86464e5b3", # 2018-11-16 - remote = "https://github.com/protocolbuffers/protobuf.git", -) - # Needed for generating the Stardoc release binary. git_repository( name = "io_bazel", @@ -37,15 +17,6 @@ remote = "https://github.com/bazelbuild/bazel.git", ) -git_repository( - name = "rules_python", - remote = "https://github.com/bazelbuild/rules_python.git", - commit = "4b84ad270387a7c439ebdccfd530e2339601ef27", -) - -load("@rules_python//python:repositories.bzl", "py_repositories") -py_repositories() - # Needed only because of java_tools. http_archive( name = "rules_cc", @@ -58,6 +29,20 @@ ) # Needed as a transitive dependency of @io_bazel +git_repository( + name = "com_google_protobuf", + commit = "7b28271a61a3da0a37f6fda399b0c4c86464e5b3", # 2018-11-16 + remote = "https://github.com/protocolbuffers/protobuf.git", +) + +# Needed as a transitive dependency of @io_bazel +git_repository( + name = "rules_python", + remote = "https://github.com/bazelbuild/rules_python.git", + commit = "4b84ad270387a7c439ebdccfd530e2339601ef27", +) + +# Needed as a transitive dependency of @io_bazel http_archive( name = "rules_pkg", sha256 = "5bdc04987af79bd27bc5b00fe30f59a858f77ffa0bd2d8143d5b31ad8b1bd71c",
diff --git a/serve-docs.sh b/serve-docs.sh deleted file mode 100755 index 4674e03..0000000 --- a/serve-docs.sh +++ /dev/null
@@ -1,103 +0,0 @@ -#!/usr/bin/env bash -# Copyright 2016 The Bazel Authors. 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 -eu - -if [ "${1-}" == "help" ]; then - cat <<EOF -Usage: -$0 [port] - Builds docs and starts a web server serving docs on localhost:port - Default port is 12345. -$0 <target directory> [<serving prefix>] - Builds docs as static web pages in <target directory>. - Replaces absolute paths in the resulting HTML with <serving prefix>, - or, if it is not specified, with <target directory>. -EOF - exit 0 -fi - -if [[ "${1-}" == [0-9]* ]]; then - readonly PORT="$1" - readonly TARGET='' -else - readonly PORT="${1-12345}" - readonly TARGET="${1-}" -fi - -readonly WORKING_DIR=$(mktemp -d) -readonly SERVING_PREFIX="${2-$TARGET}" - -function check { - which "$1" > /dev/null || (echo "$1 not installed. Please install $1."; exit 1) -} - -function build_and_serve { - bazel build //site:jekyll-tree.tar - rm -rf "$WORKING_DIR/*" - tar -xf bazel-genfiles/site/jekyll-tree.tar -C "$WORKING_DIR" - - pkill -9 jekyll || true - - if [ -z "$TARGET" ]; then - echo "Serving skydoc.bazel.build site at port $PORT" - jekyll serve --detach --quiet --port "$PORT" --source "$WORKING_DIR" - else - TMP_TARGET=$(mktemp -d) - jekyll build --source "$WORKING_DIR" --destination "$TMP_TARGET" - REPLACEMENT=$(echo "$SERVING_PREFIX" | sed s/\\//\\\\\\//g) - find "$TMP_TARGET" -name '*.html' | xargs sed -i s/href=\\\"\\//href=\"$REPLACEMENT\\//g - find "$TMP_TARGET" -name '*.html' | xargs sed -i s/src=\\\"\\//src=\"$REPLACEMENT\\//g - cp -R $TMP_TARGET/* "$TARGET" - echo "Static pages copied to $TARGET" - echo "Should be served from $SERVING_PREFIX" - fi -} - -function main { - check jekyll - - old_version="Jekyll 0.11.2" - if expr match "$(jekyll --version)" "$old_version"; then - # The ancient version that apt-get has. - echo "ERROR: Running with an old version of Jekyll, update " \ - "to 2.5.3 with \`sudo gem install jekyll -v 2.5.3\`" - exit 1 - fi - - build_and_serve - - echo "Type q to quit, r to rebuild docs and restart jekyll" - while true; do - - read -n 1 -s user_input - if [ "$user_input" == "q" ]; then - echo "Quitting" - exit 0 - elif [ "$user_input" == "r" ]; then - echo "Rebuilding docs and restarting jekyll" - build_and_serve - echo "Rebuilt docs and restarted jekyll" - fi - done -} - -function cleanup { - rm -rf "$WORKING_DIR" - pkill -9 jekyll -} -trap cleanup EXIT - -main
diff --git a/setup.bzl b/setup.bzl index 60b787b..47a1df9 100644 --- a/setup.bzl +++ b/setup.bzl
@@ -21,45 +21,6 @@ if not native.existing_rule(name): repo_rule(name = name, **kwargs) -JINJA2_BUILD_FILE = """ -py_library( - name = "jinja2", - srcs = glob(["jinja2/*.py"]), - srcs_version = "PY2AND3", - deps = [ - "@markupsafe_archive//:markupsafe", - ], - visibility = ["//visibility:public"], -) -""" - -MARKUPSAFE_BUILD_FILE = """ -py_library( - name = "markupsafe", - srcs = glob(["markupsafe/*.py"]), - srcs_version = "PY2AND3", - visibility = ["//visibility:public"], -) -""" - -MISTUNE_BUILD_FILE = """ -py_library( - name = "mistune", - srcs = ["mistune.py"], - srcs_version = "PY2AND3", - visibility = ["//visibility:public"], -) -""" - -SIX_BUILD_FILE = """ -py_library( - name = "six", - srcs = ["six.py"], - srcs_version = "PY2AND3", - visibility = ["//visibility:public"], -) -""" - def skydoc_repositories(): """Adds the external repositories used by the skylark rules.""" _include_if_not_defined( @@ -69,63 +30,6 @@ sha256 = "2ef429f5d7ce7111263289644d233707dba35e39696377ebab8b0bc701f7818e", ) _include_if_not_defined( - git_repository, - name = "io_bazel_rules_sass", - remote = "https://github.com/bazelbuild/rules_sass.git", - commit = "8ccf4f1c351928b55d5dddf3672e3667f6978d60", - ) - _include_if_not_defined( - http_archive, - name = "markupsafe_archive", - urls = ["https://pypi.python.org/packages/source/M/MarkupSafe/MarkupSafe-0.23.tar.gz#md5=f5ab3deee4c37cd6a922fb81e730da6e"], - sha256 = "a4ec1aff59b95a14b45eb2e23761a0179e98319da5a7eb76b56ea8cdc7b871c3", - build_file_content = MARKUPSAFE_BUILD_FILE, - strip_prefix = "MarkupSafe-0.23", - ) - native.bind( - name = "markupsafe", - actual = "@markupsafe_archive//:markupsafe", - ) - - _include_if_not_defined( - http_archive, - name = "jinja2_archive", - urls = ["https://pypi.python.org/packages/source/J/Jinja2/Jinja2-2.8.tar.gz#md5=edb51693fe22c53cee5403775c71a99e"], - sha256 = "bc1ff2ff88dbfacefde4ddde471d1417d3b304e8df103a7a9437d47269201bf4", - build_file_content = JINJA2_BUILD_FILE, - strip_prefix = "Jinja2-2.8", - ) - native.bind( - name = "jinja2", - actual = "@jinja2_archive//:jinja2", - ) - - _include_if_not_defined( - http_archive, - name = "mistune_archive", - urls = ["https://pypi.python.org/packages/source/m/mistune/mistune-0.7.1.tar.gz#md5=057bc28bf629d6a1283d680a34ed9d0f"], - sha256 = "6076dedf768348927d991f4371e5a799c6a0158b16091df08ee85ee231d929a7", - build_file_content = MISTUNE_BUILD_FILE, - strip_prefix = "mistune-0.7.1", - ) - native.bind( - name = "mistune", - actual = "@mistune_archive//:mistune", - ) - - _include_if_not_defined( - http_archive, - name = "six_archive", - urls = ["https://pypi.python.org/packages/source/s/six/six-1.10.0.tar.gz#md5=34eed507548117b2ab523ab14b2f8b55"], - sha256 = "105f8d68616f8248e24bf0e9372ef04d3cc10104f1980f54d57b2ce73a5ad56a", - build_file_content = SIX_BUILD_FILE, - strip_prefix = "six-1.10.0", - ) - native.bind( - name = "six", - actual = "@six_archive//:six", - ) - _include_if_not_defined( http_archive, name = "rules_java", urls = [
diff --git a/site/BUILD b/site/BUILD deleted file mode 100644 index 6259cba..0000000 --- a/site/BUILD +++ /dev/null
@@ -1,36 +0,0 @@ -licenses(["notice"]) # Apache 2.0 - -load("@bazel_tools//tools/build_defs/pkg:pkg.bzl", "pkg_tar") - -filegroup( - name = "jekyll-srcs", - srcs = glob( - ["**/*"], - exclude = [ - "BUILD", - "jekyll-tree.sh", - "*.swp", - ], - ), -) - -pkg_tar( - name = "jekyll-base", - srcs = [":jekyll-srcs"], - strip_prefix = ".", -) - -genrule( - name = "jekyll-tree", - srcs = [ - ":jekyll-base", - "//stardoc:stardoc_doc", - "//skylark:skylark-docs", - ], - outs = ["jekyll-tree.tar"], - cmd = ("$(location jekyll-tree.sh) $@ " + - "$(location jekyll-base) " + - "$(location //skylark:skylark-docs) " + - "$(location //stardoc:stardoc_doc) "), - tools = ["jekyll-tree.sh"], -)
diff --git a/site/CNAME b/site/CNAME deleted file mode 100644 index 9fce306..0000000 --- a/site/CNAME +++ /dev/null
@@ -1 +0,0 @@ -skydoc.bazel.build
diff --git a/site/_config.yml b/site/_config.yml deleted file mode 100755 index 288fa5c..0000000 --- a/site/_config.yml +++ /dev/null
@@ -1,8 +0,0 @@ -destination: production -markdown: redcarpet -paginate: 10 -highlighter: pygments -sass: - sass_dir: _sass - style: compressed -
diff --git a/site/_includes/drawer.html b/site/_includes/drawer.html deleted file mode 100644 index 880a6c9..0000000 --- a/site/_includes/drawer.html +++ /dev/null
@@ -1,40 +0,0 @@ - <div class="mdl-layout__drawer"> - <span class="mdl-layout-title"> - <a href="/">Skydoc</a> - </span> - <nav class="drawer-nav"> - <ul> - <li><a href="/">Home</a></li> - <li> - <span class="drawer-nav-title">Stardoc Documentation</span> - <ul> - <li><a href="/docs/getting_started_stardoc.html">Getting Started</a></li> - <li><a href="/docs/writing_stardoc.html">Writing Documentation</a></li> - <li><a href="/docs/generating_stardoc.html">Generating Documentation</a></li> - <li><a href="/docs/stardoc_reference.html">Build Rule Reference</a></li> - </ul> - </li> - <li> - <span class="drawer-nav-title">Skydoc (deprecated)</span> - <ul> - <li><a href="/docs/skydoc_deprecation.html">About Skydoc Deprecation</a></li> - <li><a href="/docs/getting_started.html">Getting Started</a></li> - <li><a href="/docs/writing.html">Writing Documentation</a></li> - <li><a href="/docs/generating.html">Generating Documentation</a></li> - <li><a href="/docs/skylark.html">Build Rule Reference</a></li> - <li><a href="/docs/faq.html">FAQ</a></li> - </ul> - </li> - <li> - <span class="drawer-nav-title">Get Involved</span> - <ul> - <li><a href="/contributing.html">Contribute to Stardoc</a></li> - <li><a href="/roadmap.html">Roadmap</a></li> - <li><a href="https://groups.google.com/forum/#!forum/bazel-discuss">User mailing list</a></li> - <li><a href="https://github.com/bazelbuild/skydoc/issues">Issue tracker</a></li> - <li><a href="https://github.com/bazelbuild/skydoc">GitHub</a></li> - </ul> - </li> - </ul> - </nav> - </div>
diff --git a/site/_includes/footer.html b/site/_includes/footer.html deleted file mode 100644 index b68b3e7..0000000 --- a/site/_includes/footer.html +++ /dev/null
@@ -1,102 +0,0 @@ - <footer class="mdl-mini-footer"> - <div class="mdl-mini-footer__left-section"> - <div class="mdl-logo">© 2016 Google, Inc.</div> - </div> - <div class="mdl-mini-footer__right-section"> - <a class="mdl-button mdl-js-button mdl-js-ripple-effect" href="#" - id="scroll-to-top"> - Back to Top - </a> - </div> - </footer> - - <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.2/jquery.min.js"></script> - <script> - var shiftWindow = function() { - if (location.hash.length !== 0) { - window.scrollBy(0, -50); - } - }; - window.addEventListener("hashchange", shiftWindow); - - var highlightCurrentSidebarNav = function() { - var href = location.pathname; - var item = $('.drawer-nav [href$="' + href + '"]'); - if (item) { - var li = item.parent(); - li.addClass("active"); - } - }; - - /** - * Creates a CSE search form and submits the search query. - * - * Since the Material Design Lite header expandable text field does not - * support having a <form> element around the <input> element, we need to - * capture the ENTER keypress and then submit the form using this handler. - */ - var submitSearch = function(query) { - var form = document.createElement("form"); - form.setAttribute("action", "/search.html"); - - var cseParams = { - "cx": "008327220137350982602:0mpaowwcmvg", - "cof": "FORID:10", - "ie": "UTF-8", - }; - for (key in cseParams) { - var hidden = document.createElement("input"); - hidden.setAttribute("type", "hidden"); - hidden.setAttribute("name", key); - hidden.setAttribute("value", cseParams[key]); - form.appendChild(hidden); - } - - var text = document.createElement("input"); - text.setAttribute("type", "text"); - text.setAttribute("name", "q"); - text.setAttribute("value", query); - form.appendChild(text); - - document.body.appendChild(form); - form.submit(); - }; - - $(document).ready(function() { - // Scroll to anchor of location hash, adjusted for fixed navbar. - window.setTimeout(function() { - shiftWindow(); - }, 1); - - // Highlight the current item on the sidebar. - highlightCurrentSidebarNav(); - - // Handler to capture the ENTER keypress for the CSE search input - // in the page header and then call submitSearch() to submit the search - // query. - $("#cse-search-box").keyup(function(e) { - if (e.keyCode == 13) { - let query = $("#cse-search-box").val(); - submitSearch(query); - } - }); - - // Handler for the Scroll to Top link in the page footer to scroll the - // main content back to the top. - $("#scroll-to-top").click(function() { - $(".mdl-layout__content").animate({ scrollTop: 0 }, "slow"); - return false; - }); - }); - </script> - - <!-- Google Analytics tracking code --> - <script> - (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ - (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), - m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) - })(window,document,'script','https://www.google-analytics.com/analytics.js','ga'); - - ga('create', 'UA-61082125-2', 'auto'); - ga('send', 'pageview'); - </script>
diff --git a/site/_includes/head.html b/site/_includes/head.html deleted file mode 100644 index 26824d4..0000000 --- a/site/_includes/head.html +++ /dev/null
@@ -1,29 +0,0 @@ - <head> - <meta charset="utf-8"> - <meta http-equiv="X-UA-Compatible" content="IE=edge"> - <meta name="viewport" content="width=device-width, initial-scale=1"> - <title>{{ page.title }} - Skydoc</title> - - <script> - var current_url = window.location.href; - var bad_url = new RegExp("^https?://bazelbuild.github.io/skydoc/"); - if (bad_url.test(current_url)) { - window.location.replace(current_url.replace(bad_url, "https://skydoc.bazel.build/")); - } - </script> - - <link rel="canonical" href="{{ page.url | replace:'index.html','' | prepend: site_root }}"> - - <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.3/material.green-blue.min.css"> - <script defer src="https://code.getmdl.io/1.1.3/material.min.js"></script> - <link rel="stylesheet" href="/css/{{ page.stylesheet }}.css"> - - <link rel="shortcut icon" type="image/png" href="/images/favicon.ico"> - - <!-- metadata --> - <meta name="og:title" content="Skydoc"/> - <meta name="og:description" content="Generate documentation for Bazel Skylark rules."/> - </head> -
diff --git a/site/_includes/header.html b/site/_includes/header.html deleted file mode 100644 index eab757f..0000000 --- a/site/_includes/header.html +++ /dev/null
@@ -1,23 +0,0 @@ - <header class="mdl-layout__header mdl-layout__header--waterfall"> - <div class="mdl-layout__header-row"> - <span class="mdl-layout-title">{{ page.title }}</span> - <div class="mdl-layout-spacer"></div> - <nav class="mdl-navigation mdl-layout--large-screen-only"> - <a class="mdl-navigation__link" href="/docs/getting_started.html">Docs</a> - <a class="mdl-navigation__link" href="/contributing.html">Contributing</a> - <a class="mdl-navigation__link" href="https://github.com/bazelbuild/skydoc">GitHub</a> - </nav> - <div class="mdl-textfield mdl-js-textfield mdl-textfield--expandable - mdl-textfield--floating-label mdl-textfield--align-right"> - <label class="mdl-button mdl-js-button mdl-button--icon" - for="cse-search-box"> - <i class="material-icons">search</i> - </label> - <div class="mdl-textfield__expandable-holder"> - <input class="mdl-textfield__input" type="text" - id="cse-search-box"> - </div> - </div> - </div> - </header> - {% include drawer.html %}
diff --git a/site/_layouts/default.html b/site/_layouts/default.html deleted file mode 100644 index 81cd665..0000000 --- a/site/_layouts/default.html +++ /dev/null
@@ -1,25 +0,0 @@ ---- -stylesheet: docs ---- -<!DOCTYPE html> -<html lang="en" itemscope itemtype="https://schema.org/WebPage"> - {% include head.html %} - <body> - <div class="mdl-layout mdl-js-layout mdl-layout--fixed-drawer - mdl-layout--fixed-header"> - {% include header.html %} - - <main class="mdl-layout__content"> - <div class="page-content"> - {% if page.title %} - <h1 class="page-title">{{ page.title }}</h1> - {% endif %} - - {{ content }} - </div> - <div class="mdl-layout-spacer"></div> - {% include footer.html %} - </main> - </div> - </body> -</html>
diff --git a/site/_layouts/home.html b/site/_layouts/home.html deleted file mode 100644 index df98d18..0000000 --- a/site/_layouts/home.html +++ /dev/null
@@ -1,23 +0,0 @@ ---- -stylesheet: home -title: Skydoc ---- -<!DOCTYPE html> -<html lang="en" itemscope itemtype="https://schema.org/WebPage"> - {% include head.html %} - <body class="body-home"> - <div class="mdl-layout mdl-js-layout mdl-layout--fixed-header"> - {% include header.html %} - - <main class="mdl-layout__content"> - <div class="page-content"> - - {{ content }} - - </div> - <div class="mdl-layout-spacer"></div> - {% include footer.html %} - </main> - </div> - </body> -</html>
diff --git a/site/_sass/base.scss b/site/_sass/base.scss deleted file mode 100644 index a513a93..0000000 --- a/site/_sass/base.scss +++ /dev/null
@@ -1,91 +0,0 @@ -// Copyright 2016 The Skydoc Authors. 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. - -$primary-color: rgb(76,175,80); -$body-bg-color: #fafafa; -$code-bg-color: #fff; -$code-dark-bg-color: #424242; -$border-color: #f5f5f5; - -body { - background-color: $body-bg-color; -} - -img.responsive { - max-width: 100%; - height: auto; - border: 1px solid $border-color; -} - -a { - text-decoration: none; -} - -pre, -code { - font-family: 'Liberation Mono', Consolas, Monaco, 'Andale Mono', monospace; -} - -pre, -pre.term { - background-color: $code-bg-color; - padding: 20px; - overflow-x: auto; - word-wrap: normal; - border: 1px solid $border-color; - - code { - overflow-wrap: normal; - white-space: pre; - } -} - -pre.term { - background-color: $code-dark-bg-color; - color: $code-bg-color; - font-size: 90%; - - span.info { - color: #81C784; - } -} - -code { - display: inline-block; - font-size: 90%; - white-space: pre-wrap; -} - -.mdl-layout__content { - display: -webkit-flex; - display: -ms-flexbox; - display: flex; - -webkit-flex-direction: column; - -ms-flex-flow: column; - flex-direction: column; -} - -.mdl-layout__content > *:not(.mdl-layout-spacer) { - -webkit-flex: none; - -ms-flex: none; - flex: none; -} - -$scroll-to-top-color: #fff; - -footer { - #scroll-to-top { - color: $scroll-to-top-color; - } -}
diff --git a/site/_sass/docs.scss b/site/_sass/docs.scss deleted file mode 100644 index a1008e9..0000000 --- a/site/_sass/docs.scss +++ /dev/null
@@ -1,168 +0,0 @@ -// Copyright 2016 The Skydoc Authors. 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. - -p.lead { - font-size: 20px; - line-height: 32px; -} - -img { - margin: 20px 0; - max-width: 100%; - height: auto; -} - -$table-bg-color: #fff; -$table-border-color: #eee; -$th-bg-color: #fafafa; -$th-color: #757575; - -table { - border-collapse: collapse; - border-spacing: 0; - background-color: $table-bg-color; - table-layout: auto; - - thead { - th { - background-color: $th-bg-color; - border: 1px solid $table-border-color; - color: $th-color; - padding: 12px 12px 12px 24px; - vertical-align: top; - } - } - - tbody { - td { - border: 1px solid $table-border-color; - padding: 12px 12px 12px 24px; - vertical-align: top; - } - } -} - -table.params-table { - width: 100%; - - col.col-param { - width: 25%; - } - - col.col-description { - width: 75%; - } -} - -hr { - margin-top: 80px; - margin-bottom: 80px; -} - -$toc-heading-color: #757575; - -nav.toc { - border-left: 5px solid $primary-color; - padding-left: 20px; - margin-bottom: 48px; - - h1, - h2 { - font-size: 15px; - line-height: 16px; - padding-bottom: 12px; - margin-bottom: 0; - font-weight: 400; - color: $toc-heading-color; - } - - ul { - list-style: none; - margin-top: 0; - padding-left: 0; - - li { - font-size: 20px; - line-height: 40px; - - a { - color: $primary-color; - } - } - } -} - -$h3-color: #757575; - -.page-content { - margin-left: auto; - margin-right: auto; - padding-top: 60px; - padding-bottom: 60px; - width: 760px; - - h1.page-title { - font-size: 34px; - font-weight: 400; - line-height: 40px; - margin-bottom: 30px; - color: $primary-color; - } - - h1 { - font-size: 24px; - font-weight: 400; - line-height: 40px; - margin-bottom: 20px; - color: $primary-color; - } - - h2 { - font-size: 20px; - font-weight: 400; - line-height: 32px; - margin-bottom: 20px; - color: $primary-color; - } - - h3 { - font-size: 18px; - font-weight: 400; - line-height: 32px; - margin-bottom: 20px; - color: $h3-color; - } -} - -@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; -}
diff --git a/site/_sass/drawer.scss b/site/_sass/drawer.scss deleted file mode 100644 index 89e7df4..0000000 --- a/site/_sass/drawer.scss +++ /dev/null
@@ -1,89 +0,0 @@ -// Copyright 2016 The Skydoc Authors. 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. - -$drawer-bg-color: #fff; -$drawer-border-color: #e0e0e0; -$drawer-heading-color: #757575; -$drawer-hover-color: #f0f0f0; - -.mdl-layout__drawer { - background-color: $drawer-bg-color; - - .mdl-layout-title { - border-bottom: 1px solid $drawer-border-color; - padding-left: 24px; - - a { - text-decoration: none; - color: $drawer-heading-color; - font-weight: normal; - } - } -} - -.drawer-nav { - ul { - list-style: none; - padding-left: 0; - - li { - display: block; - padding: 0; - - ul { - li { - a { - padding-left: 44px; - font-weight: 400; - } - } - } - - span.drawer-nav-title { - display: block; - flex-shrink: 0; - padding: 15px 0 15px 22px; - margin: 0; - font-weight: 600; - color: $drawer-heading-color; - line-height: 1em; - text-decoration: none; - } - - a { - display: block; - flex-shrink: 0; - padding: 15px 0 15px 22px; - margin: 0; - font-weight: 600; - color: $drawer-heading-color; - line-height: 1em; - text-decoration: none; - cursor: pointer; - - &:active, - &:hover { - background-color: $drawer-hover-color; - } - } - - &.active { - a { - color: $primary-color; - font-weight: 500; - } - } - } - } -}
diff --git a/site/_sass/home.scss b/site/_sass/home.scss deleted file mode 100644 index d01f3d7..0000000 --- a/site/_sass/home.scss +++ /dev/null
@@ -1,57 +0,0 @@ -// Copyright 2016 The Skydoc Authors. 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. - -$hero-bg-color: rgb(76,175,80); -$hero-color: #fff; - -.hero { - background-color: $hero-bg-color; - color: $hero-color; - padding-top: 40px; - padding-bottom: 20px; - - .mdl-cell { - text-align: center; - } - - h1 { - font-size: 32px; - font-weight: 300; - } - - p.lead { - font-size: 18px; - font-weight: 300; - } - - .mdl-button { - margin-top: 10px; - background-color: $body-bg-color; - } -} - -.feature { - .mdl-grid { - max-width: 1230px; - } - - .mdl-cell { - padding: 10px; - } - - h1 { - font-size: 28px; - font-weight: 300; - } -}
diff --git a/site/_sass/syntax.scss b/site/_sass/syntax.scss deleted file mode 100644 index 46dda20..0000000 --- a/site/_sass/syntax.scss +++ /dev/null
@@ -1,89 +0,0 @@ -// -// Copyright 2015 Google -// -// Generated using Base16 Builder -// (https://github.com/chriskempson/base16-builder) - -$base00: #212121; // ---- -$base01: #424242; // --- -$base02: #616161; // -- -$base03: #757575; // - -$base04: #9e9e9e; // + -$base05: #bdbdbd; // ++ -$base06: #e0e0e0; // +++ -$base07: #eee; // ++++ - -$base08: #f44336; // red -$base09: #ff9800; // orange -$base0A: #ffc107; // yellow -$base0B: #4caf50; // green -$base0C: #009688; // aqua -$base0D: #2196f3; // blue -$base0E: #9c27b0; // purple -$base0F: #795548; // brown - -.highlight .hll { background-color: $base06 } -.highlight { background: $base07; color: $base00 } -.highlight .c { color: $base03 } // Comment -.highlight .err { color: $base08 } // Error -.highlight .k { color: $base0E } // Keyword -.highlight .l { color: $base09 } // Literal -.highlight .n { color: $base00 } // Name -.highlight .o { color: $base0C } // Operator -.highlight .p { color: $base00 } // Punctuation -.highlight .cm { color: $base03 } // Comment.Multiline -.highlight .cp { color: $base03 } // Comment.Preproc -.highlight .c1 { color: $base03 } // Comment.Single -.highlight .cs { color: $base03 } // Comment.Special -.highlight .gd { color: $base08 } // Generic.Deleted -.highlight .ge { font-style: italic } // Generic.Emph -.highlight .gh { color: $base00; font-weight: bold } // Generic.Heading -.highlight .gi { color: $base0B } // Generic.Inserted -.highlight .gp { color: $base03; font-weight: bold } // Generic.Prompt -.highlight .gs { font-weight: bold } // Generic.Strong -.highlight .gu { color: $base0C; font-weight: bold } // Generic.Subheading -.highlight .kc { color: $base0E } // Keyword.Constant -.highlight .kd { color: $base0E } // Keyword.Declaration -.highlight .kn { color: $base0C } // Keyword.Namespace -.highlight .kp { color: $base0E } // Keyword.Pseudo -.highlight .kr { color: $base0E } // Keyword.Reserved -.highlight .kt { color: $base0A } // Keyword.Type -.highlight .ld { color: $base0B } // Literal.Date -.highlight .m { color: $base09 } // Literal.Number -.highlight .s { color: $base0B } // Literal.String -.highlight .na { color: $base0D } // Name.Attribute -.highlight .nb { color: $base00 } // Name.Builtin -.highlight .nc { color: $base0A } // Name.Class -.highlight .no { color: $base08 } // Name.Constant -.highlight .nd { color: $base0C } // Name.Decorator -.highlight .ni { color: $base00 } // Name.Entity -.highlight .ne { color: $base08 } // Name.Exception -.highlight .nf { color: $base0D } // Name.Function -.highlight .nl { color: $base00 } // Name.Label -.highlight .nn { color: $base0A } // Name.Namespace -.highlight .nx { color: $base0D } // Name.Other -.highlight .py { color: $base00 } // Name.Property -.highlight .nt { color: $base0C } // Name.Tag -.highlight .nv { color: $base08 } // Name.Variable -.highlight .ow { color: $base0C } // Operator.Word -.highlight .w { color: $base00 } // Text.Whitespace -.highlight .mf { color: $base09 } // Literal.Number.Float -.highlight .mh { color: $base09 } // Literal.Number.Hex -.highlight .mi { color: $base09 } // Literal.Number.Integer -.highlight .mo { color: $base09 } // Literal.Number.Oct -.highlight .sb { color: $base0B } // Literal.String.Backtick -.highlight .sc { color: $base00 } // Literal.String.Char -.highlight .sd { color: $base03 } // Literal.String.Doc -.highlight .s2 { color: $base0B } // Literal.String.Double -.highlight .se { color: $base09 } // Literal.String.Escape -.highlight .sh { color: $base0B } // Literal.String.Heredoc -.highlight .si { color: $base09 } // Literal.String.Interpol -.highlight .sx { color: $base0B } // Literal.String.Other -.highlight .sr { color: $base0B } // Literal.String.Regex -.highlight .s1 { color: $base0B } // Literal.String.Single -.highlight .ss { color: $base0B } // Literal.String.Symbol -.highlight .bp { color: $base00 } // Name.Builtin.Pseudo -.highlight .vc { color: $base08 } // Name.Variable.Class -.highlight .vg { color: $base08 } // Name.Variable.Global -.highlight .vi { color: $base08 } // Name.Variable.Instance -.highlight .il { color: $base09 } // Literal.Number.Integer.Long
diff --git a/site/contributing.md b/site/contributing.md deleted file mode 100644 index a17a523..0000000 --- a/site/contributing.md +++ /dev/null
@@ -1,48 +0,0 @@ ---- -layout: default -title: Contributing -stylesheet: docs ---- - -We welcome your contributions! To contribute to Stardoc, fork the [Skydoc][repo] -GitHub repository and start submitting pull requests. - -[repo]: https://github.com/bazelbuild/skydoc - -## Contributing to Skydoc - -In general, we prefer contributions that fix bugs or add features (as opposed to -purely stylistic, refactoring, or "cleanup" changes). Please check with us on -the [bazel-dev][bazel-dev] mailing list or open a GitHub Issue before investing -a lot of time in a patch. - -[bazel-dev]: https://groups.google.com/forum/#!forum/bazel-dev - -To submit a patch to Skydoc: - -* Skydoc is part of the Bazel project. Read the [Bazel governance - plan](https://www.bazel.build/governance.html) and Skydoc's [contribution - guidelines](https://github.com/bazelbuild/skydoc/blob/master/CONTRIBUTING.md). -* Open an [Issue](https://github.com/bazelbuild/skydoc/issues) or discuss your - plan or design on the [bazel-dev][bazel-dev] mailing list. -* Prepare a Git commit that implements your feature or bug fix. Don't forget to - add tests and reference the corresponding bug, if any. -* Open a [Pull Request][pull-request] on the Skydoc repository. This will - require that you have signed a [Contributor License Agreement][cla]. -* Complete a code review a [core contributor](#core-contributors). Amend your - patch by making additional commits or rebasing with HEAD if there are - conflicts with new commits on the master branch. -* Once the code review is complete, your reviewer will squash/merge your pull - request to the master branch. - -[pull-request]: https://github.com/bazelbuild/skydoc/pulls -[cla]: https://cla.developers.google.com/ - -## Core Contributors - -The current group of Stardoc core contributors are: - -* [cparsons](https://github.com/c-parsons) -* [laurentlb](https://github.com/laurentlb) - -
diff --git a/site/css/docs.scss b/site/css/docs.scss deleted file mode 100644 index 7d244a1..0000000 --- a/site/css/docs.scss +++ /dev/null
@@ -1,7 +0,0 @@ ---- ---- - -@import "base.scss"; -@import "docs.scss"; -@import "drawer.scss"; -@import "syntax.scss";
diff --git a/site/css/home.scss b/site/css/home.scss deleted file mode 100644 index 520cd01..0000000 --- a/site/css/home.scss +++ /dev/null
@@ -1,7 +0,0 @@ ---- ---- - -@import "base.scss"; -@import "home.scss"; -@import "drawer.scss"; -@import "syntax.scss";
diff --git a/site/docs/faq.md b/site/docs/faq.md deleted file mode 100644 index f73bbec..0000000 --- a/site/docs/faq.md +++ /dev/null
@@ -1,39 +0,0 @@ ---- -layout: default -title: FAQ -stylesheet: docs ---- - -## Why am I getting `TypeError: unsupported operand type(s) for +: 'dict' and 'dict'`? - -Skylark currently defines the `+` operator for dictionaries. Because -Skydoc evaluates `.bzl` files as Python code and because the `+` operator -for dictionaries may be [removed][dict-op] from Skylark in the future, we -suggest using the `dict(a.items() + b.items())` syntax instead. - -[dict-op]: https://github.com/bazelbuild/bazel/issues/1086 - -## Is Skydoc used to generate the documentation on [bazel.build](https://bazel.build)? - -Not for now. The [Build Encyclopedia](https://bazel.build/docs/be/overview.html) -documents the set of native Bazel build rules written in Java, and the -[Skylark Library](https://bazel.build/docs/skylark/lib/globals.html) documents the -built-in Skylark modules and functions. Because both of these sets of docs are -generated from Bazel's Java source code, they are generated using a [separate -documentation generation -tool](https://github.com/bazelbuild/bazel/tree/master/src/main/java/com/google/devtools/build/docgen). - -We are planning to create a catalog of Skylark rule sets to make it easy to -publish and discover Skylark rule sets and browse their documentation. See -[bazelbuild/bazel#1046](https://github.com/bazelbuild/bazel/issues/1046) for -more information. - -## Why do the docstrings for rules come after the rule definition? - -Unlike in other languages, [Python docstrings -](https://www.python.org/dev/peps/pep-0257/) are special string literals rather -than comments. Because Skylark is a subset of Python, we take the same approach -for Skylark docstrings as well. Because rule declarations are basically global -variables, we follow the same convention for variable docstrings used by Python -documentation generation tools, such as -[epydoc](http://epydoc.sourceforge.net/manual-docstring.html).
diff --git a/site/docs/generating.md b/site/docs/generating.md deleted file mode 100644 index f27c5be..0000000 --- a/site/docs/generating.md +++ /dev/null
@@ -1,117 +0,0 @@ ---- -layout: default -title: Generating Documentation -stylesheet: docs ---- - -<nav class="toc"> - <h2>Contents</h2> - <ul> - <li><a href="#single-target">Single Target</a></li> - <li><a href="#multiple-targets">Multiple Targets</a></li> - </ul> -</nav> - -The following are some examples of how to use Skydoc. - -<a name="single-target"></a> -## Single Target - -Suppose you have a project containing Skylark rules you want to document: - -``` -[workspace]/ - WORKSPACE - checkstyle/ - BUILD - checkstyle.bzl -``` - -To generate documentation for the rules and macros in `checkstyle.bzl`, add the -following target to `rules/BUILD`: - -```python -load("@io_bazel_skydoc//skylark:skylark.bzl", "skylark_doc") - -skylark_doc( - name = "checkstyle-docs", - srcs = ["checkstyle.bzl"], -) -``` - -Running `bazel build //checkstyle:checkstyle-docs` will generate a zip file -containing documentation for the public rules and macros in `checkstyle.bzl`. - -By default, Skydoc will generate documentation in Markdown. To generate -a set of HTML pages that is ready to be served, set `format = "html"`. - -<a name="multiple-targets"></a> -## Multiple Targets - -If you would like to generate documentation for multiple .bzl files in various -packages in your workspace, you can use the `skylark_library` rule to create -logical collections of Skylark sources and add a single `skylark_doc` target for -building documentation for all of the rule sets. - -Suppose your project has the following structure: - -``` -[workspace]/ - WORKSPACE - BUILD - checkstyle/ - BUILD - checkstyle.bzl - lua/ - BUILD - lua.bzl - luarocks.bzl -``` - -In this case, you can have `skylark_library` targets in `checkstyle/BUILD` and -`lua/BUILD`: - -`checkstyle/BUILD`: - -```python -load("@bazel_skylib//:skylark_library.bzl", "skylark_library") - -skylark_library( - name = "checkstyle-rules", - srcs = ["checkstyle.bzl"], -) -``` - -`lua/BUILD`: - -```python -load("@bazel_skylib//:skylark_library.bzl", "skylark_library") - -skylark_library( - name = "lua-rules", - srcs = [ - "lua.bzl", - "luarocks.bzl", - ], -) -``` - -To build documentation for all the above `.bzl` files at once: - -`BUILD`: - -```python -load("@io_bazel_skydoc//skylark:skylark.bzl", "skylark_doc") - -skylark_doc( - name = "docs", - srcs = [ - "//checkstyle:checkstyle-rules", - "//lua:lua-rules", - ], -) -``` - -Running `bazel build //:docs` would build a single zip containing documentation -for all the `.bzl` files contained in the two `skylark_library` targets' `srcs`. -
diff --git a/site/docs/generating_stardoc.md b/site/docs/generating_stardoc.md deleted file mode 100644 index 81f4a5e..0000000 --- a/site/docs/generating_stardoc.md +++ /dev/null
@@ -1,170 +0,0 @@ ---- -layout: default -title: Generating Documentation -stylesheet: docs ---- - -<nav class="toc"> - <h2>Contents</h2> - <ul> - <li><a href="#single-file">Single File</a></li> - <li><a href="#files-with-deps">Files with Dependencies</a></li> - <li><a href="#multiple-files">Multiple Files</a></li> - </ul> -</nav> - -The following are some examples of how to use Stardoc. - -<a name="single-file"></a> -## Single File - -Suppose you have a project containing Stardoc rules you want to document: - -``` -[workspace]/ - WORKSPACE - checkstyle/ - BUILD - checkstyle.bzl -``` - -To generate documentation for the rules in `checkstyle.bzl`, add the -following target to `rules/BUILD`: - -```python -load("@io_bazel_skydoc//stardoc:stardoc.bzl", "stardoc") - -stardoc( - name = "checkstyle-docs", - input = "checkstyle.bzl", - out = "checkstyle_doc.md", -) -``` - -Running `bazel build //checkstyle:checkstyle-docs` will generate a markdown file -containing documentation for all Starlark rules defined in `checkstyle.bzl`. - -To generate a subset of rules defined in `checkstyle.bzl`, you may specify which -rule names you specifically want documentation for using the `symbol_names` attribute -of the `stardoc` rule. If `symbol_names` is specified, only rules matching a name -in `symbol_names` will be documented: - -```python -load("@io_bazel_skydoc//stardoc:stardoc.bzl", "stardoc") - -stardoc( - name = "checkstyle-docs", - input = "checkstyle.bzl", - out = "checkstyle_doc.md", - symbol_names = ["checkstyle_rule", "other_rule"], -) -``` - -<a name="files-with-deps"></a> -## Files with Dependencies - -If you would like to generate documentation for a `.bzl` with dependencies on -other `.bzl` files, use the `bzl_library` rule to create logical collections of -Starlark sources and depend on these libraries via the `deps` attribute of your -`stardoc` target. - -Suppose your project has the following structure: - -``` -[workspace]/ - WORKSPACE - BUILD - checkstyle/ - BUILD - checkstyle.bzl - lua/ - BUILD - lua.bzl - luarocks.bzl -``` - -...and suppose your target `.bzl` file depends on other `.bzl` files in your workspace: - -`checkstyle/checkstyle.bzl`: - -```python -load("//lua:lua.bzl", "lua_utility") - -lua_utility() - -checkstyle_rule = rule( - ... -) -``` - -In this case, you can have a `bzl_library` target in `lua/BUILD`: - -`lua/BUILD`: - -```python -load("@bazel_skylib//:bzl_library.bzl", "bzl_library") - -bzl_library( - name = "lua-rules", - srcs = [ - "lua.bzl", - "luarocks.bzl", - ], -) -``` - -To build documentation for `checkstyle.bzl`, specify the `bzl_library` target -as a dependency of the `stardoc` target: - -`checkstyle/BUILD`: - -```python -load("@io_bazel_skydoc//stardoc:stardoc.bzl", "stardoc") - -stardoc( - name = "checkstyle-docs", - input = "checkstyle.bzl", - out = "checkstyle_doc.md", - deps = ["//lua:lua-rules"], -) -``` - -<a name="multiple-files"></a> -## Multiple Files - -If you would like to generate documentation for multiple .bzl files in various -packages in your workspace, you will need to create a single `.bzl` file that depends -on all those `.bzl` files. You can then explicitly whitelist rules for which you would -like documentation to be generated. - -For example, you may want to generate documentation for `foo_rule`, `bar_rule`, and -`baz_rule`, all in different `.bzl` files. First, you would create a single `.bzl` file -which loads these files: - -`doc_hub.bzl`: - -```python -load("//foo:foo.bzl", "foo_rule") -load("//bar:bar.bzl", "bar_rule") -load("//baz:baz.bzl", "baz_rule") - -# No need for any implementation here. The rules need only be loaded. -``` - -A single `skydoc` target can then be used to generate their documentation: - -`BUILD`: - -```python -load("@io_bazel_skydoc//stardoc:stardoc.bzl", "stardoc") - -stardoc( - name = "my-docs", - input = "doc_hub.bzl", - out = "docs.md", - symbol_names = ["foo_rule", "bar_rule", "baz_rule"], -) -``` - - -
diff --git a/site/docs/getting_started.md b/site/docs/getting_started.md deleted file mode 100644 index 96d6958..0000000 --- a/site/docs/getting_started.md +++ /dev/null
@@ -1,73 +0,0 @@ ---- -layout: default -title: Getting started -stylesheet: docs ---- - -Skydoc is a documentation generator for [Bazel](https://bazel.build) build rules -written in [Skylark](https://bazel.build/docs/skylark/index.html). - -Skydoc provides a set of Skylark rules (`skylark_library` and `skylark_doc`) -that can be used to build documentation for Skylark rules in either Markdown or -HTML. Skydoc generates one documentation page per `.bzl` file. - -If you are new to writing build rules for Bazel, please read the Bazel -documentation on [writing -extensions](https://www.bazel.build/docs/skylark/concepts.html) - -<img src="/images/screenshot.png" class="responsive" - alt="A screenshot of Skydoc generated HTML documentation"> - -## Setup - -To use Skydoc, add the following to your `WORKSPACE` file: - -```python -git_repository( - name = "io_bazel_rules_sass", - remote = "https://github.com/bazelbuild/rules_sass.git", - tag = "0.0.3", -) -load("@io_bazel_rules_sass//sass:sass.bzl", "sass_repositories") -sass_repositories() - -git_repository( - name = "bazel_skylib", - remote = "https://github.com/bazelbuild/bazel-skylib.git", - tag = "0.3.0", -) - -git_repository( - name = "io_bazel_skydoc", - remote = "https://github.com/bazelbuild/skydoc.git", - tag = "0.1.4", -) -load("@io_bazel_skydoc//skylark:skylark.bzl", "skydoc_repositories") -skydoc_repositories() -``` - -Note that the Sass repositories also need to be loaded since Skydoc uses the -Bazel Sass rules. - -If you would like to load all Skydoc rules by default using Bazel's prelude, add -the following to the file `tools/build_rules/prelude_bazel` in your repository: - -```python -load( - "@io_bazel_skydoc//skylark:skylark.bzl", - "skydoc_repositories", - "skylark_doc", -) -``` - -## Next Steps - -Now you are ready to document your Skylark rules. - -* Learn about the [docstring format][format] used to document Skylark rules, - macros, and files. -* Learn about how you can use Skydoc's [build rules][generate] to generate your - documentation in Markdown or HTML format. - -[format]: writing.md -[generate]: generating.md
diff --git a/site/docs/getting_started_stardoc.md b/site/docs/getting_started_stardoc.md deleted file mode 100644 index 6326be4..0000000 --- a/site/docs/getting_started_stardoc.md +++ /dev/null
@@ -1,60 +0,0 @@ ---- -layout: default -title: Getting started -stylesheet: docs ---- - -Stardoc is a documentation generator for [Bazel](https://bazel.build) build rules -written in [Starlark](https://bazel.build/docs/skylark/index.html). - -Stardoc provides a Starlark rule (`stardoc`) -that can be used to build Markdown documentation for Starlark rules, providers, -and functions. -Starlark generates one documentation page per `stardoc` target. - -If you are new to writing build rules for Bazel, please read the Bazel -documentation on [writing -extensions](https://www.bazel.build/docs/skylark/concepts.html) - -<img src="/images/screenshot.png" class="responsive" - alt="A screenshot of Stardoc generated documentation"> - -## Setup - -To use Stardoc, add the following to your `WORKSPACE` file: - -```python -load("@bazel_tools//tools/build_defs/repo:git.bzl", "git_repository") - -git_repository( - name = "io_bazel_skydoc", - remote = "https://github.com/bazelbuild/skydoc.git", - tag = "0.3.0", -) - -load("@io_bazel_skydoc//:setup.bzl", "skydoc_repositories") -skydoc_repositories() - -load("@io_bazel_rules_sass//:package.bzl", "rules_sass_dependencies") -rules_sass_dependencies() - -load("@build_bazel_rules_nodejs//:defs.bzl", "node_repositories") -node_repositories() - -load("@io_bazel_rules_sass//:defs.bzl", "sass_repositories") -sass_repositories() -``` - -The load statements and function calls after the `io_bazel_skydoc` repository -definition ensure that this repository's dependencies are loaded. - -## Next Steps - -Now you are ready to document your Starlark rules. - -* Learn about the [docstring format][format] used to document Starlark rules. -* Learn about how you can use Stardoc's [build rules][generate] to generate your - documentation in Markdown format. - -[format]: writing_stardoc.html -[generate]: generating_stardoc.html
diff --git a/site/docs/skydoc_deprecation.md b/site/docs/skydoc_deprecation.md deleted file mode 100644 index 0023661..0000000 --- a/site/docs/skydoc_deprecation.md +++ /dev/null
@@ -1,141 +0,0 @@ ---- -layout: default -title: Skydoc Deprecation -stylesheet: docs ---- - -## Why was Skydoc deprecated? - -Skydoc functioned by evalutating Starlark files as if they were python. Unfortunately, while -Starlark is **similar** to Python, there are some important syntactic differences between -the languages. Assuming compatibility between the languages was inherently brittle, and resulted -in a maintenance burden on the Starlark code. Specifically, if one of your transitive dependencies -were to adopt a Starlark-compatible, python-incompatible construct, your Skydoc integration would -break! - -Skydoc still exists as it's a nontrivial migration to Stardoc, but we plan on removing it -in mid 2019. - -## How to migrate - -Stardoc is not a drop-in replacement for Skydoc. Its usage is slightly different, and it has some -new features. It's recommended to take a look at the root Stardoc documentation, but here is -a brief summary of some things to note for migration: - -### Docstring specification - -Stardoc uses inline documentation strings instead of python-style docstrings. -For example, Skydoc documentation may have been specified with: - -``` -my_rule = rule( - implementation = _my_rule_impl, - attrs = { - "srcs": attr.label_list(), - "deps": attr.label_list(), - }, -) -"""Example rule documentation. - -Example: - Here is an example of how to use this rule. - -Args: - srcs: Source files used to build this target. - deps: Dependencies for this target. -""" -``` - -...the equivalent for Stardoc is: - -``` -my_rule = rule( - implementation = _my_rule_impl, - doc = """ -Example rule documentation. - -Example: - Here is an example of how to use this rule. -""", - attrs = { - "srcs" : attr.label_list( - doc = "Source files used to build this target.", - ), - "deps" : attr.label_list( - doc = "Dependencies for this target.", - ), - } -) -``` - -### Different Starlark Rule - -Stardoc uses a different Starlark rule than Skydoc with different attributes. - -See [Generating Documentation](https://skydoc.bazel.build/docs/generating_stardoc.html) for a -tutorial on using the new rule, and the -[Build Rule Reference](https://skydoc.bazel.build/docs/stardoc_reference.html) for information -about the new `stardoc` rule itself. - -### Starlark Dependencies - -Stardoc depends on your `bzl` file, all of its dependencies, and all of its **transitive** -dependencies, so that it can fully evaluate your Starlark code. -`bazel-skylib`'s `bzl_library` is your "best friend" for tracking `bzl` dependencies. - -For example, suppose your `mypackage/foo.bzl` file depends on `other/package/bar.bzl`, which -depends on `third/package/baz.bzl`. - -**BUILD**: - -``` -load("@io_bazel_skydoc//stardoc:stardoc.bzl", "stardoc") - -stardoc( - name = "foo_docs", - input = "foo.bzl", - out = "foo_doc.md", - deps = ["//other/package:bar"], -) -``` - -**other/package/BUILD**: - -``` -load("@bazel_skylib//:bzl_library.bzl", "bzl_library") - -bzl_library( - name = "bar", - srcs = ["bar.bzl"], - deps = ["//third/package:baz"], -) -``` - -**third/package/BUILD**: - -``` -load("@bazel_skylib//:bzl_library.bzl", "bzl_library") - -bzl_library( - name = "baz", - srcs = ["baz.bzl"], -) -``` - -Thus, each `.bzl` file should appear in the `srcs` of a `bzl_library` target defined in the same -package. The `deps` of this `bzl_library` should be (only) the `bzl_library` targets corresponding -to the files that are _directly_ `load()`ed by the `srcs`. This structure mirrors that of other -`<language>_library` rules in Bazel. - -This migration might involve creating a large number of new `bzl_library` targets, -but this work is useful beyond Stardoc. For example, `bzl_library` can be also used to gather -transitive Starlark dependencies for use in shell tests or other test frameworks. - -See [Generating Documentation](https://skydoc.bazel.build/docs/generating_stardoc.html) for -a tutorial. - -## Migration Issues - -If you run into any issues migrating, please file a -[github issue](https://github.com/bazelbuild/skydoc/issues). -
diff --git a/site/docs/writing.md b/site/docs/writing.md deleted file mode 100644 index f68c32d..0000000 --- a/site/docs/writing.md +++ /dev/null
@@ -1,122 +0,0 @@ ---- -layout: default -title: Writing Documentation -stylesheet: docs ---- - -<nav class="toc"> - <h2>Contents</h2> - <ul> - <li><a href="#rule-documentation">Rule Documentation</a></li> - <li><a href="#macro-documentation">Macro Documentation</a></li> - <li><a href="#file-documentation">File Documentation</a></li> - </ul> -</nav> - -Since Skylark is a subset of Python, it uses Python docstrings for inline -documentation for Skylark rules and macros as well as file (module) docstrings -for documenting `.bzl` files. Skydoc supports Markdown for all inline -documentation. - -When generating documentation, Skydoc parses the `.bzl` file to extract the -inline documentation as well as evaluates the Skylark code to determine the -types for rule attributes. Skydoc will generate documentation for all public -rules and macros. For undocumented rules and macros, Skydoc will still generate -the rule signature and table of attributes. - -Private rules and macros (i.e. those whose names begin with `_`) will not -appear in generated documentation. - -<a name="rule-documentation"></a> -## Rule Documentation - -[Skylark Rules](https://bazel.build/docs/skylark/rules.html) are declared using -the `rule()` function as global variables. As a result, they are documented -using variable docstrings, similar to those supported by -[epydoc](http://epydoc.sourceforge.net/manual-docstring.html). - -Attributes are documented in a special `Args:` section. Begin the documentation -for each attribute on an indented line with the attribute name followed by a -colon `:`. The documentation for an attribute can span multiple lines as long as -each line is indented from the first line: - -```python -checkstyle = rule( - implementation = _impl, - attrs = { - "srcs": attr.label_list(allow_files = FileType([".java"]), - "config": attr.label(), - }, -) -"""Runs checkstyle on the given source files. - -This rule runs [Checkstyle](http://checkstyle.sourceforge.net/) on a set of -Java source files. - -Args: - srcs: The Java source files to run checkstyle against. - config: The checkstyle configuration file to use. - - If no configuration file is provided, then the default `checkstyle.xml` will - be used. -""" -``` - -The `name` attribute that is common to all rules is documented by default, but -the default documentation can be overwridden by adding documentation for `name` -in `Args`. - -<a name="macro-documentation"></a> -## Macro Documentation - -[Skylark Macros](https://bazel.build/docs/skylark/macros.html) are Python -functions and are thus documented using function docstrings: - -```python -def rat_check(name, srcs=[], format, visibility): - """Runs Apache Rat license checks on the given source files. - - This rule runs [Apache Rat](http://creadur.apache.org/rat/) license checks on - a given set of source files. Use `bazel build` to run the check. - - Args: - name: A unique name for this rule. - srcs: Source files to run the Rat license checks against. - - Note that the Bazel glob() function can be used to specify which source - files to include and which to exclude. - format: The format to write the Rat check report in. - visibility: The visibility of this rule. - """ - if format not in ['text', 'html', 'xml']: - fail('Invalid format: %s' % format, 'format') - - _rat_check( - name = name, - srcs = srcs, - format = format, - visibility = visibility, - ) -``` - -Note that the format of the docstrings for rules and macros are identical. - -<a name="file-documentation"></a> -## File Documentation - -Skydoc also supports file docstrings (similar to Python's module docstrings), -which can be used to document a `.bzl` file, such as providing an overview of -the rules and macros implemented in the file: - -```python -"""Checkstyle Rules - -Skylark rules for running [Checkstyle](http://checkstyle.sourceforge.net/) on -Java source files. -""" -``` - -If a file docstring is provided, the short docstring will be used as the title -on the generated documentation file, and the rest of the docstring (separated -from the title with an empty line) will be used to generate an Overview section -on the page.
diff --git a/site/docs/writing_stardoc.md b/site/docs/writing_stardoc.md deleted file mode 100644 index c931744..0000000 --- a/site/docs/writing_stardoc.md +++ /dev/null
@@ -1,127 +0,0 @@ ---- -layout: default -title: Writing Documentation -stylesheet: docs ---- - -<nav class="toc"> - <h2>Contents</h2> - <ul> - <li><a href="#rule-documentation">Rule Documentation</a></li> - <li><a href="#provider-documentation">Provider Documentation</a></li> - <li><a href="#macro-documentation">Macro Documentation</a></li> - </ul> -</nav> - -When generating documentation, Stardoc parses the `.bzl` file to extract the -inline documentation as well as evaluates the Starlark code to determine the -types for rule attributes. Stardoc will, by default, generate documentation for -all rules, macros, and functions reachable from a target `.bzl` file. -(See [Generating Stardoc][geenrating_stardoc.html] for details on limiting the -symbols for which stardoc generates documentation.) - -<a name="rule-documentation"></a> -## Rule Documentation - -When generating documentation, Stardoc parses the `.bzl` file to extract the -inline documentation as well as evaluates the Starlark code to determine the -types for rule attributes. - -Private rule attributes (attributes with names that begin with `_`) will not -appear in generated documentation. - -[Starlark Rules](https://bazel.build/docs/skylark/rules.html) are declared using -the `rule()` function as global variables. - -General rule documentation should be supplied in the `doc` parameter of the -`rule()` function. - -Likewise, supply attribute documentation in the `doc` parameter of attribute -schema-defining functions, such as `attr.label()`. - -```python -my_rule = rule( - implementation = _my_rule_impl, - doc = """ -Example rule documentation. - -Example: - Here is an example of how to use this rule. -""", - attrs = { - "srcs" : attr.label_list( - doc = "Source files used to build this target.", - ), - "deps" : attr.label_list( - doc = "Dependencies for this target.", - ), - } -) -``` - -The `name` attribute that is common to all rules is documented by default. - -<a name="provider-documentation"></a> -## Provider Documentation - -[Starlark Providers](https://docs.bazel.build/versions/master/skylark/rules.html#providers) -are documented similarly to rules: using docstrings specified as parameters during -creation of the provider. - -General provider documentation can be specified using the `doc` parameter -to the `provider()` function. - -Field-related documentation can be specified by passing a map to the -`fields` parameter of the `provider()` function. Keys are required field -names, and values are their corresponding docstrings. - -``` -MyInfo = provider( - doc = """ -A provider with some really neat documentation. - -Contains information about some of my favorite things. -""", - fields = {'favorite_food' : 'A string representing my favorite food', - 'favorite_color' : 'A string representing my favorite color'} -) -``` - -<a name="macro-documentation"></a> -## Macro Documentation - -[Starlark Macros](https://bazel.build/docs/skylark/macros.html) are documented -using docstrings similar to Python docstring format: - -```python -def rat_check(name, srcs=[], format, visibility): - """Runs Apache Rat license checks on the given source files. - - This rule runs [Apache Rat](http://creadur.apache.org/rat/) license checks on - a given set of source files. Use `bazel build` to run the check. - - Args: - name: A unique name for this rule. - srcs: Source files to run the Rat license checks against. - - Note that the Bazel glob() function can be used to specify which source - files to include and which to exclude. - format: The format to write the Rat check report in. - visibility: The visibility of this rule. - """ - if format not in ['text', 'html', 'xml']: - fail('Invalid format: %s' % format, 'format') - - _rat_check( - name = name, - srcs = srcs, - format = format, - visibility = visibility, - ) -``` - -Parameters are documented in a special `Args:` section. Begin the documentation -for each parameter on an indented line with the parameter name followed by a -colon `:`. The documentation for a parameter can span multiple lines as long as -each line is indented from the first line. -
diff --git a/site/images/favicon.ico b/site/images/favicon.ico deleted file mode 100644 index 97fc067..0000000 --- a/site/images/favicon.ico +++ /dev/null Binary files differ
diff --git a/site/images/sample.png b/site/images/sample.png deleted file mode 100644 index 2cc8941..0000000 --- a/site/images/sample.png +++ /dev/null Binary files differ
diff --git a/site/images/screenshot.png b/site/images/screenshot.png deleted file mode 100644 index 31bbb24..0000000 --- a/site/images/screenshot.png +++ /dev/null Binary files differ
diff --git a/site/index.html b/site/index.html deleted file mode 100644 index 2ef4874..0000000 --- a/site/index.html +++ /dev/null
@@ -1,86 +0,0 @@ ---- -layout: home -title: Home -stylesheet: home ---- - -<div class="hero"> - <div class="mdl-grid"> - <div class="mdl-cell mdl-cell--12-col-desktop mdl-cell--8-col-tablet - mdl-cell--4-col-phone"> - <h1>Beautiful Documentation for Build Rules</h1> - <p class="lead"> - Stardoc is an easy-to-use documentation generator for Bazel build rules - written in Starlark. - </p> - <p class="lead"> - (Stardoc is a recent replacement of the documentation generator tool named "Skydoc") - </p> - <a href="/docs/getting_started_stardoc.html" class="mdl-button mdl-js-button - mdl-button--raised mdl-js-ripple-effect">Get Started with Stardoc</a> - <a href="/docs/getting_started.html" class="mdl-button mdl-js-button - mdl-button--raised mdl-js-ripple-effect">Take me to Skydoc documentation instead</a> - </div> - </div> -</div> -<div class="feature"> - <div class="mdl-grid"> - <div class="mdl-cell mdl-cell--4-col-desktop mdl-cell--8-col-tablet - mdl-cell--4-col-phone"> - <h1>Python docstrings</h1> - <p> - Document your Starlark rules - <a href="docs/writing_stardoc.html">alongside their definition</a>. - </p> -{% highlight python %} -my_rule = rule( - implementation = _my_rule_impl, - doc = """ -Example rule documentation. - -Example: - Here is an example of how to use this rule. -""", - attrs = { - "srcs" : attr.label_list( - doc = "Source files used to build this target.", - ), - "deps" : attr.label_list( - doc = "Dependencies for this target.", - ), - } -) -{% endhighlight %} - </div> - - <div class="mdl-cell mdl-cell--4-col-desktop mdl-cell--8-col-tablet - mdl-cell--4-col-phone"> - <h1>Convenient Build Rules</h1> - <p> - Skydoc's own convenient Bazel <a href="docs/generating_stardoc.html">build - rules</a> making it to integrate Skydoc into your build or release - pipeline. - </p> -{% highlight python %} -load("@io_bazel_skydoc//stardoc:stardoc.bzl", - "stardoc") - -stardoc( - name = "checkstyle-docs", - input = "checkstyle.bzl", - out = "checkstyle_doc.md", -) -{% endhighlight %} -<pre class="term">$ <span class="info">bazel</span> build :checkstyle-docs</pre> - </div> - - <div class="mdl-cell mdl-cell--4-col-desktop mdl-cell--8-col-tablet - mdl-cell--4-col-phone"> - <h1>Beautiful Documentation</h1> - <p> - Generate <a href="docs/skylark.html">documentation</a> in Markdown. - </p> - <img src="/images/sample.png" class="responsive"> - </div> - </div> -</div>
diff --git a/site/jekyll-tree.sh b/site/jekyll-tree.sh deleted file mode 100755 index 10fa0a0..0000000 --- a/site/jekyll-tree.sh +++ /dev/null
@@ -1,79 +0,0 @@ -#!/usr/bin/env bash -# Copyright 2016 The Bazel Authors. 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 -eu - -readonly OUTPUT=${PWD}/$1 -shift -readonly JEKYLL_BASE=${PWD}/$1 -shift -readonly SKYLARK_DOCS=${PWD}/$1 -shift -readonly STARDOC_DOC=${PWD}/$1 - -# Create temporary directory that is removed when this script exits. -readonly TMP=$(mktemp -d "${TMPDIR:-/tmp}/tmp.XXXXXXXX") -readonly OUT_DIR="$TMP/out" -trap "rm -rf ${TMP}" EXIT - -function setup { - mkdir -p "$OUT_DIR" - cd "$OUT_DIR" - tar -xf "${JEKYLL_BASE}" -} - -function unpack_skylark_doc { - local generated_dir="$TMP/skylark" - mkdir -p $generated_dir - - # Unpack the generated documentation. - unzip -qq "$SKYLARK_DOCS" -d "$generated_dir" - - for f in $(find "$generated_dir" -name "*.md"); do - ( cat <<EOF ---- -layout: default -title: Build Rule Reference -stylesheet: docs ---- -EOF - cat $f; ) > "$OUT_DIR/docs/$(basename $f)" - done -} - -function include_skydoc_doc { - ( cat <<EOF ---- -layout: default -title: Build Rule Reference -stylesheet: docs ---- -EOF - cat $STARDOC_DOC; ) > "$OUT_DIR/docs/stardoc_reference.md" -} - -function package_output { - cd "$OUT_DIR" - tar -hcf $OUTPUT $(find . -type f | sort) -} - -function main { - setup - unpack_skylark_doc - include_skydoc_doc - package_output - cd "$(dirname ${TMP})" -} -main
diff --git a/site/roadmap.md b/site/roadmap.md deleted file mode 100644 index 00c63f0..0000000 --- a/site/roadmap.md +++ /dev/null
@@ -1,12 +0,0 @@ ---- -layout: default -title: Roadmap -stylesheet: docs ---- - -* Document default values for rule and macro attributes. -* Enable greater customization of generated documentation, such as adding custom - HTML and CSS to the documentation pages. -* Improve documentation for Skylark - [Aspects](https://www.bazel.build/docs/skylark/aspects.html) and - [Repository Rules](https://www.bazel.build/docs/skylark/repository_rules.html).
diff --git a/site/search.html b/site/search.html deleted file mode 100644 index c455a81..0000000 --- a/site/search.html +++ /dev/null
@@ -1,18 +0,0 @@ ---- -layout: home -title: Site Search -stylesheet: home ---- - -<script> - (function() { - var cx = '008327220137350982602:0mpaowwcmvg'; - var gcse = document.createElement('script'); - gcse.type = 'text/javascript'; - gcse.async = true; - gcse.src = 'https://cse.google.com/cse.js?cx=' + cx; - var s = document.getElementsByTagName('script')[0]; - s.parentNode.insertBefore(gcse, s); - })(); -</script> -<gcse:search></gcse:search>
diff --git a/skydoc-screenshot.png b/skydoc-screenshot.png deleted file mode 100644 index 31bbb24..0000000 --- a/skydoc-screenshot.png +++ /dev/null Binary files differ
diff --git a/skydoc/BUILD b/skydoc/BUILD deleted file mode 100644 index d3c191b..0000000 --- a/skydoc/BUILD +++ /dev/null
@@ -1,107 +0,0 @@ -licenses(["notice"]) # Apache 2.0 - -package(default_visibility = ["//visibility:public"]) - -load("@com_google_protobuf//:protobuf.bzl", "py_proto_library") -load("@rules_python//python:defs.bzl", "py_binary", "py_library", "py_test") - -py_proto_library( - name = "build_pb_py", - srcs = ["build.proto"], - default_runtime = "@com_google_protobuf//:protobuf_python", - protoc = "@com_google_protobuf//:protoc", -) - -py_library( - name = "common", - srcs = ["common.py"], -) - -py_test( - name = "common_test", - srcs = ["common_test.py"], - python_version = "PY2", - deps = [ - ":common", - ], -) - -py_library( - name = "load_extractor", - srcs = ["load_extractor.py"], -) - -py_test( - name = "load_extractor_test", - srcs = ["load_extractor_test.py"], - python_version = "PY2", - deps = [ - ":load_extractor", - ], -) - -py_library( - name = "macro_extractor", - srcs = ["macro_extractor.py"], - deps = [":common"], -) - -py_test( - name = "macro_extractor_test", - srcs = ["macro_extractor_test.py"], - python_version = "PY2", - deps = [ - ":build_pb_py", - ":macro_extractor", - ], -) - -py_library( - name = "rule_extractor", - srcs = ["rule_extractor.py"], - deps = [ - ":common", - ":load_extractor", - "//skydoc/stubs", - ], -) - -py_test( - name = "rule_extractor_test", - srcs = ["rule_extractor_test.py"], - python_version = "PY2", - deps = [ - ":build_pb_py", - ":load_extractor", - ":rule_extractor", - ], -) - -py_library( - name = "rule", - srcs = ["rule.py"], - deps = [ - ":build_pb_py", - "//external:mistune", - ], -) - -py_binary( - name = "skydoc", - srcs = ["main.py"], - data = [ - "//skydoc/sass:main.css", - "//skydoc/templates", - ], - # no py_binary launcher - main = "main.py", - python_version = "PY2", - deps = [ - ":common", - ":macro_extractor", - ":rule", - ":rule_extractor", - "//external:jinja2", - "@bazel_tools//tools/python/runfiles", - ], -)
diff --git a/skydoc/build.proto b/skydoc/build.proto deleted file mode 100644 index 8d344fa..0000000 --- a/skydoc/build.proto +++ /dev/null
@@ -1,112 +0,0 @@ -// Copyright 2014 The Bazel Authors. 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. - -syntax = "proto2"; - -package skydoc; - -// internal options - -message Attribute { - // Indicates the type of attribute. - enum Discriminator { - INTEGER = 1; // int_value - STRING = 2; // string_value - LABEL = 3; // string_value - OUTPUT = 4; // string_value - STRING_LIST = 5; // string_list_value - LABEL_LIST = 6; // string_list_value - OUTPUT_LIST = 7; // string_list_value - DISTRIBUTION_SET = 8; // string_list_value - order is unimportant - LICENSE = 9; // license - STRING_DICT = 10; // string_dict_value - FILESET_ENTRY_LIST = 11; // fileset_list_value - LABEL_LIST_DICT = 12; // label_list_dict_value - STRING_LIST_DICT = 13; // string_list_dict_value - BOOLEAN = 14; // int, bool and string value - TRISTATE = 15; // tristate, int and string value - INTEGER_LIST = 16; // int_list_value - UNKNOWN = 18; // unknown type, use only for build extensions - LABEL_DICT_UNARY = 19; // label_dict_unary_value - SELECTOR_LIST = 20; // selector_list - NAME = 21; // name, use only for the name attribute - LABEL_KEYED_STRING_DICT = 22; // label_keyed_string_dict - - // Deprecated. - DEPRECATED_STRING_DICT_UNARY = 17; - } -} - -// Information about allowed rule classes for a specific attribute of a rule. -message AllowedRuleClassInfo { - enum AllowedRuleClasses { - ANY = 1; // Any rule is allowed to be in this attribute - SPECIFIED = 2; // Only the explicitly listed rules are allowed - } - - required AllowedRuleClasses policy = 1; - - // Rule class names of rules allowed in this attribute, e.g "cc_library", - // "py_binary". Only present if the allowed_rule_classes field is set to - // SPECIFIED. - repeated string allowed_rule_class = 2; -} - -// Information about an output target for a rule. -message OutputTarget { - // The template name of the output target (e.g. %{name}.jar. - optional string template = 1; - // The documentation for the output target. - optional string documentation = 2; -} - -// This message represents a single attribute of a single rule. -message AttributeDefinition { - // Rule name, e.g. "cc_library" - required string name = 1; - required Attribute.Discriminator type = 2; - required bool mandatory = 3; - - // Only present for attributes of type LABEL and LABEL_LIST. - optional AllowedRuleClassInfo allowed_rule_classes = 4; - // The documentation for the attribute. - optional string documentation = 5; - // The string representation of the default value of the attribute. - optional string default = 6; -} - -message RuleDefinition { - required string name = 1; - // Only contains documented attributes - repeated AttributeDefinition attribute = 2; - // The documentation for the rule. - optional string documentation = 3; - // Documentation illustrating example usages of the rule. - optional string example_documentation = 4; - - // The list of outputs for this rule. - repeated OutputTarget output = 5; - - enum Type { - RULE = 1; - MACRO = 2; - REPOSITORY_RULE = 3; - } - optional Type type = 6; -} - -message BuildLanguage { - // Only contains documented rule definitions - repeated RuleDefinition rule = 1; -}
diff --git a/skydoc/common.py b/skydoc/common.py deleted file mode 100644 index 8ec4bd5..0000000 --- a/skydoc/common.py +++ /dev/null
@@ -1,176 +0,0 @@ -# Copyright 2016 The Bazel Authors. 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. - -"""Common functions for skydoc.""" - -import collections -import re -import textwrap -from xml.sax.saxutils import escape - - -ARGS_HEADING = "Args:" -EXAMPLES_HEADING = "Examples:" -EXAMPLE_HEADING = "Example:" -OUTPUTS_HEADING = "Outputs:" - - -class InputError(Exception): - pass - - -class ExtractedDocs(object): - """Simple class to contain the documentation extracted from a docstring.""" - - def __init__(self, doc, attr_docs, example_doc, output_docs): - self.doc = doc - self.attr_docs = attr_docs - self.example_doc = example_doc - self.output_docs = output_docs - - -def leading_whitespace(line): - """Returns the number of leading whitespace in the line.""" - return len(line) - len(line.lstrip()) - - -def validate_strip_prefix(strip_prefix, bzl_files): - if not strip_prefix: - return strip_prefix - prefix = strip_prefix if strip_prefix.endswith('/') else strip_prefix + '/' - for path in bzl_files: - if not path.startswith(prefix): - raise InputError( - 'Input file %s does not have path prefix %s. Directory prefix set ' - 'with --strip_prefix must be common to all input files.' - % (path, strip_prefix)) - return prefix - -def _parse_attribute_docs(attr_docs, lines, index): - """Extracts documentation in the form of name: description. - - This includes documentation for attributes and outputs. - - Args: - attr_docs: A dict used to store the extracted documentation. - lines: List containing the input docstring split into lines. - index: The index in lines containing the heading that begins the - documentation, such as "Args:" or "Outputs:". - - Returns: - Returns the next index after the documentation to resume processing - documentation in the caller. - """ - attr = None # Current attribute name - desc = None # Description for current attribute - args_leading_ws = leading_whitespace(lines[index]) - i = index + 1 - while i < len(lines): - line = lines[i] - # If a blank line is encountered, we have finished parsing the "Args" - # section. - if line.strip() and leading_whitespace(line) == args_leading_ws: - break - # In practice, users sometimes add a "-" prefix, so we strip it even - # though it is not recommended by the style guide - pattern = re.compile(r""" - # Any amount of leading whitespace, plus an optional "-" prefix. - ^\s*-?\s* - # The attribute name, plus an optional "**" prefix for a **kwargs - # attribute. - ((?:\*\*)?[`\{\}\%\.\w\*]+) - # A colon plus any amount of whitespace to separate the attribute name - # from the description text. - :\s* - # The attribute description text. - (.*) - """, re.VERBOSE) - match = re.search(pattern, line) - if match: # We have found a new attribute - if attr: - attr_docs[attr] = escape(desc) - attr, desc = match.group(1), match.group(2) - elif attr: - # Merge documentation when it is multiline - desc = desc + "\n" + line.strip() - i += + 1 - - if attr: - attr_docs[attr] = escape(desc).strip() - - return i - - -def _parse_example_docs(examples, lines, index): - """Extracts example documentation. - - Args: - examples: A list to contain the lines containing the example documentation. - lines: List containing the input docstring split into lines. - index: The index in lines containing "Example[s]:", which begins the - example documentation. - - Returns: - Returns the next index after the attribute documentation to resume - processing documentation in the caller. - """ - heading_leading_ws = leading_whitespace(lines[index]) - i = index + 1 - while i < len(lines): - line = lines[i] - if line.strip() and leading_whitespace(line) == heading_leading_ws: - break - examples.append(line) - i += 1 - - return i - - -def parse_docstring(doc): - """Analyzes the documentation string for attributes. - - This looks for the "Args:" separator to fetch documentation for each - attribute. The "Args" section ends at the first blank line. - - Args: - doc: The documentation string - - Returns: - The new documentation string and a dictionary that maps each attribute to - its documentation - """ - attr_docs = collections.OrderedDict() if hasattr(collections, 'OrderedDict') else {} - output_docs = collections.OrderedDict() if hasattr(collections, 'OrderedDict') else {} - examples = [] - lines = doc.split("\n") - docs = [] - i = 0 - while i < len(lines): - line = lines[i] - if line.strip() == ARGS_HEADING: - i = _parse_attribute_docs(attr_docs, lines, i) - continue - elif line.strip() == EXAMPLES_HEADING or line.strip() == EXAMPLE_HEADING: - i = _parse_example_docs(examples, lines, i) - continue - elif line.strip() == OUTPUTS_HEADING: - i = _parse_attribute_docs(output_docs, lines, i) - continue - - docs.append(line) - i += 1 - - doc = "\n".join(docs).strip() - examples_doc = textwrap.dedent("\n".join(examples)).strip() - return ExtractedDocs(doc, attr_docs, examples_doc, output_docs)
diff --git a/skydoc/common_test.py b/skydoc/common_test.py deleted file mode 100644 index af12e5e..0000000 --- a/skydoc/common_test.py +++ /dev/null
@@ -1,204 +0,0 @@ -# Copyright 2016 The Bazel Authors. 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. - -import unittest -# internal imports - -from skydoc import common - - -class CommonTest(unittest.TestCase): - """Unit tests for common functions.""" - - def test_rule_doc_only(self): - docstring = 'Rule documentation only docstring.' - extracted_docs = common.parse_docstring(docstring) - self.assertEqual('Rule documentation only docstring.', extracted_docs.doc) - self.assertDictEqual({}, extracted_docs.attr_docs) - self.assertEqual('', extracted_docs.example_doc) - self.assertDictEqual({}, extracted_docs.output_docs) - - def test_rule_and_attribute_doc(self): - docstring = ( - 'Rule and attribute documentation.\n' - '\n' - 'Args:\n' - ' name: A unique name for this rule.\n' - ' visibility: The visibility of this rule.\n') - expected_attrs = { - 'name': 'A unique name for this rule.', - 'visibility': 'The visibility of this rule.' - } - - extracted_docs = common.parse_docstring(docstring) - self.assertEqual('Rule and attribute documentation.', extracted_docs.doc) - self.assertDictEqual(expected_attrs, extracted_docs.attr_docs) - self.assertEqual('', extracted_docs.example_doc) - self.assertDictEqual({}, extracted_docs.output_docs) - - def test_multi_line_doc(self): - docstring = ( - 'Multi-line rule and attribute documentation.\n' - '\n' - 'Rule doc continued here.\n' - '\n' - 'Args:\n' - ' name: A unique name for this rule.\n' - '\n' - ' Documentation for name continued here.\n' - ' visibility: The visibility of this rule.\n' - '\n' - ' Documentation for visibility continued here.\n') - expected_doc = ( - 'Multi-line rule and attribute documentation.\n' - '\n' - 'Rule doc continued here.') - expected_attrs = { - 'name': ('A unique name for this rule.\n\n' - 'Documentation for name continued here.'), - 'visibility': ('The visibility of this rule.\n\n' - 'Documentation for visibility continued here.') - } - - extracted_docs = common.parse_docstring(docstring) - self.assertEqual(expected_doc, extracted_docs.doc) - self.assertDictEqual(expected_attrs, extracted_docs.attr_docs) - self.assertEqual('', extracted_docs.example_doc) - self.assertDictEqual({}, extracted_docs.output_docs) - - def test_invalid_args(self): - docstring = ( - 'Rule and attribute documentation.\n' - '\n' - 'Foo:\n' - ' name: A unique name for this rule.\n' - ' visibility: The visibility of this rule.\n') - - extracted_docs = common.parse_docstring(docstring) - self.assertEqual(docstring.strip(), extracted_docs.doc) - self.assertDictEqual({}, extracted_docs.attr_docs) - self.assertEqual('', extracted_docs.example_doc) - self.assertDictEqual({}, extracted_docs.output_docs) - - def test_example(self): - docstring = ( - 'Documentation with example\n' - '\n' - 'Examples:\n' - ' An example of how to use this rule:\n' - '\n' - ' example_rule()\n' - '\n' - ' Note about this example.\n' - '\n' - 'Args:\n' - ' name: A unique name for this rule.\n' - ' visibility: The visibility of this rule.\n') - expected_attrs = { - 'name': 'A unique name for this rule.', - 'visibility': 'The visibility of this rule.' - } - expected_example_doc = ( - 'An example of how to use this rule:\n' - '\n' - ' example_rule()\n' - '\n' - 'Note about this example.') - - extracted_docs = common.parse_docstring(docstring) - self.assertEqual('Documentation with example', extracted_docs.doc) - self.assertDictEqual(expected_attrs, extracted_docs.attr_docs) - self.assertEqual(expected_example_doc, extracted_docs.example_doc) - self.assertDictEqual({}, extracted_docs.output_docs) - - def test_example_after_attrs(self): - docstring = ( - 'Documentation with example\n' - '\n' - 'Args:\n' - ' name: A unique name for this rule.\n' - ' visibility: The visibility of this rule.\n' - '\n' - 'Examples:\n' - ' An example of how to use this rule:\n' - '\n' - ' example_rule()\n' - '\n' - ' Note about this example.\n') - expected_attrs = { - 'name': 'A unique name for this rule.', - 'visibility': 'The visibility of this rule.' - } - expected_example_doc = ( - 'An example of how to use this rule:\n' - '\n' - ' example_rule()\n' - '\n' - 'Note about this example.') - - extracted_docs = common.parse_docstring(docstring) - self.assertEqual('Documentation with example', extracted_docs.doc) - self.assertDictEqual(expected_attrs, extracted_docs.attr_docs) - self.assertEqual(expected_example_doc, extracted_docs.example_doc) - self.assertDictEqual({}, extracted_docs.output_docs) - - def test_outputs(self): - docstring = ( - 'Documentation with outputs\n' - '\n' - 'Args:\n' - ' name: A unique name for this rule.\n' - ' visibility: The visibility of this rule.\n' - '\n' - 'Outputs:\n' - ' %{name}.jar: A Java archive.\n' - ' %{name}_deploy.jar: A Java archive suitable for deployment.\n' - '\n' - ' Only built if explicitly requested.\n') - expected_attrs = { - 'name': 'A unique name for this rule.', - 'visibility': 'The visibility of this rule.' - } - expected_outputs = { - '%{name}.jar': 'A Java archive.', - '%{name}_deploy.jar': ('A Java archive suitable for deployment.\n\n' - 'Only built if explicitly requested.'), - } - - extracted_docs = common.parse_docstring(docstring) - self.assertEqual('Documentation with outputs', extracted_docs.doc) - self.assertDictEqual(expected_attrs, extracted_docs.attr_docs) - self.assertEqual('', extracted_docs.example_doc) - self.assertDictEqual(expected_outputs, extracted_docs.output_docs) - - def _invalid_prefix(self, prefix, bzl_files): - self.assertRaises(common.InputError, - common.validate_strip_prefix, - prefix, - bzl_files) - - def test_strip_prefix(self): - bzl_files = ['foo/bar/bar.bzl', 'foo/bar/baz/baz.bzl'] - self.assertEqual('', common.validate_strip_prefix('', bzl_files)) - self.assertEqual('foo/', common.validate_strip_prefix('foo/', bzl_files)) - self.assertEqual('foo/bar/', - common.validate_strip_prefix('foo/bar', bzl_files)) - - self._invalid_prefix('bar', ['foo/bar.bzl']) - self._invalid_prefix('bar', ['foo/foo.bzl', 'bar/bar.bzl']) - self._invalid_prefix('bar', ['bar.bzl']) - self._invalid_prefix('bar', ['barfoo/bar.bzl']) - -if __name__ == '__main__': - unittest.main()
diff --git a/skydoc/load_extractor.py b/skydoc/load_extractor.py deleted file mode 100644 index e083a3d..0000000 --- a/skydoc/load_extractor.py +++ /dev/null
@@ -1,112 +0,0 @@ -# Copyright 2017 The Bazel Authors. 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. - -"""Extracts information about symbols loaded from other .bzl files.""" - -import ast -from collections import namedtuple - -LoadSymbol = namedtuple('LoadSymbol', ['label', 'symbol', 'alias']) -"""Information about a symbol loaded from another .bzl file.""" - - -class LoadExtractorError(Exception): - """Error raised by LoadExtractor""" - pass - - -class LoadExtractor(object): - """Extracts information on symbols load()ed from other .bzl files.""" - - def _extract_loads(self, bzl_file): - """Walks the AST and extracts information on loaded symbols.""" - load_symbols = [] - try: - tree = None - with open(bzl_file) as f: - tree = ast.parse(f.read(), bzl_file) - key = None - for node in ast.iter_child_nodes(tree): - if not isinstance(node, ast.Expr): - continue - call = node.value - if (not isinstance(call, ast.Call) or - not isinstance(call.func, ast.Name) or - call.func.id != 'load'): - continue - - args = [] - for arg in call.args: - if not isinstance(arg, ast.Str): - raise LoadExtractorError( - 'Only string literals in load statments are supported.') - args.append(arg.s) - kwargs = {} - for keyword in call.keywords: - if not isinstance(keyword.value, ast.Str): - raise LoadExtractorError( - 'Only string literals in load statments are supported.') - kwargs[keyword.arg] = keyword.value.s - - label = args[0] - for arg in args[1:]: - load_symbol = LoadSymbol(label, arg, None) - load_symbols.append(load_symbol) - for alias, symbol in kwargs.items(): - load_symbol = LoadSymbol(label, symbol, alias) - load_symbols.append(load_symbol) - - except IOError as e: - print("Failed to parse {0}: {1}".format(bzl_file, e.strerror)) - pass - - return load_symbols - - def _validate_loads(self, load_symbols): - """Checks that there are no collisions from the extracted symbols.""" - symbols = set() - for load in load_symbols: - if load.alias: - if load.alias in symbols: - raise LoadExtractorError( - "Load symbol conflict: %s (aliased from %s) loaded from %s" % - (load.alias, load.symbol, load.label)) - else: - symbols.add(load.alias) - elif load.symbol in symbols: - raise LoadExtractorError( - "Load symbol conflict: %s loaded from %s" % - (load.alias, load.label)) - else: - symbols.add(load.symbol) - - def extract(self, bzl_file): - """Extracts symbols loaded from other .bzl files. - - Walks the AST of the .bzl files and extracts information about symbols - loaded from other .bzl files from load() calls. Then, validate the - extracted symbols to check that all symbols are unique. - - Note that only load() calls where all arguments are string literals - (ast.Str) are supported. - - Args: - bzl_file: The .bzl file to extract load symbols from. - - Returns: - List of LoadSymbol objects. - """ - load_symbols = self._extract_loads(bzl_file) - self._validate_loads(load_symbols) - return load_symbols
diff --git a/skydoc/load_extractor_test.py b/skydoc/load_extractor_test.py deleted file mode 100644 index a38172e..0000000 --- a/skydoc/load_extractor_test.py +++ /dev/null
@@ -1,93 +0,0 @@ -# Copyright 2017 The Bazel Authors. 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. - -import os -import tempfile -import textwrap -import unittest - -from skydoc import load_extractor - -class LoadExtractorTest(unittest.TestCase): - - def check_symbols(self, src, expected): - tf = tempfile.NamedTemporaryFile(mode='w+', delete=False) - tf.write(src) - tf.flush() - tf.close() - extractor = load_extractor.LoadExtractor() - load_symbols = extractor.extract(tf.name) - os.remove(tf.name) - - self.assertEqual(expected, load_symbols) - - def test_load(self): - src = textwrap.dedent("""\ - load("//foo/bar:bar.bzl", "foo_library") - load("//foo/bar:baz.bzl", "foo_test", orig_foo_binary = "foo_binary") - """) - expected = [ - load_extractor.LoadSymbol('//foo/bar:bar.bzl', 'foo_library', None), - load_extractor.LoadSymbol('//foo/bar:baz.bzl', 'foo_test', None), - load_extractor.LoadSymbol('//foo/bar:baz.bzl', 'foo_binary', - 'orig_foo_binary'), - ] - self.check_symbols(src, expected) - - def raises_error(self, src): - tf = tempfile.NamedTemporaryFile(mode='w+', delete=False) - tf.write(src) - tf.flush() - tf.close() - - extractor = load_extractor.LoadExtractor() - self.assertRaises(load_extractor.LoadExtractorError, - extractor.extract, tf.name) - os.remove(tf.name) - - def test_invalid_non_string_literal_in_label(self): - src = textwrap.dedent("""\ - load(load_label, "foo_library") - """) - self.raises_error(src) - - def test_invalid_non_string_literal_in_keywords(self): - src = textwrap.dedent("""\ - load("//foo/bar:bar.bzl", loaded_symbol) - """) - self.raises_error(src) - - def test_invalid_symbol_conflict(self): - src = textwrap.dedent("""\ - load("//foo:bar.bzl", "foo_binary", "foo_library") - load("//foo:baz.bzl", "foo_library") - """) - self.raises_error(src) - - def test_invalid_symbol_alias_conflict(self): - src = textwrap.dedent("""\ - load("//foo:bar.bzl", foo_library="some_foo_library") - load("//foo:baz.bzl", "foo_library") - """) - self.raises_error(src) - - def test_invalid_duplicate_symbol_loaded(self): - src = textwrap.dedent("""\ - load("//foo:bar.bzl", "foo_library", "foo_library") - """) - self.raises_error(src) - - -if __name__ == '__main__': - unittest.main()
diff --git a/skydoc/macro_extractor.py b/skydoc/macro_extractor.py deleted file mode 100644 index 0be9709..0000000 --- a/skydoc/macro_extractor.py +++ /dev/null
@@ -1,143 +0,0 @@ -# Copyright 2016 The Bazel Authors. 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. - -"""Extractor for Skylark macro documentation.""" - -import ast -# internal imports - -from skydoc import build_pb2 -from skydoc import common - - -def get_type(expr): - """Find the type of an expression. - - Args: - expr: The expression to check. - - Returns: - The type of the expression. - """ - if isinstance(expr, ast.Num): - return build_pb2.Attribute.INTEGER - elif isinstance(expr, ast.Str): - return build_pb2.Attribute.STRING - elif isinstance(expr, ast.List): - return build_pb2.Attribute.STRING_LIST - elif isinstance(expr, ast.Name) and (expr.id == "True" or expr.id == "False"): - return build_pb2.Attribute.BOOLEAN - elif hasattr(ast, 'NameConstant') and isinstance(expr, ast.NameConstant) and (expr.value == True or expr.value == False): - return build_pb2.Attribute.BOOLEAN - else: - return build_pb2.Attribute.UNKNOWN - -class MacroDocExtractor(object): - """Extracts documentation for macros from a .bzl file""" - - def __init__(self): - """Inits MacroDocExtractor with a new BuildLanguage proto""" - self.__language = build_pb2.BuildLanguage() - self.title = "" - self.description = "" - - def _add_file_docs(self, tree): - """Extracts the file docstring of the .bzl file.""" - docstring = ast.get_docstring(tree) - if docstring == None: - return - lines = docstring.split("\n") - i = 0 - for line in lines: - if line != '': - i = i + 1 - else: - break - - self.title = " ".join(lines[:i]) - self.description = "\n".join(lines[i + 1:]) - - def _add_macro_doc(self, stmt): - # The defaults array contains default values for the last arguments. - # The first shift arguments are mandatory. - shift = len(stmt.args.args) - len(stmt.args.defaults) - - rule = self.__language.rule.add() - rule.name = stmt.name - rule.type = build_pb2.RuleDefinition.MACRO - - doc = ast.get_docstring(stmt) - if doc: - extracted_docs = common.parse_docstring(doc) - rule.documentation = extracted_docs.doc - if extracted_docs.example_doc: - rule.example_documentation = extracted_docs.example_doc - else: - extracted_docs = common.ExtractedDocs( - doc="", attr_docs={}, example_doc="", output_docs={}) - - for i in range(len(stmt.args.args)): - attr = rule.attribute.add() - attr_name = stmt.args.args[i].id if hasattr(stmt.args.args[i], 'id') else stmt.args.args[i].arg - attr.name = attr_name - - if attr_name in extracted_docs.attr_docs: - attr.documentation = extracted_docs.attr_docs[attr_name] - - if i < shift: # The first arguments are mandatory - attr.mandatory = True - attr.type = build_pb2.Attribute.UNKNOWN - else: - node = stmt.args.defaults[i - shift] - attr.mandatory = False - attr.type = get_type(node) - if attr.type == build_pb2.Attribute.BOOLEAN: - attr.default = str(node.value) if hasattr(node, 'value') else node.id - - if stmt.args.kwarg: - attr = rule.attribute.add() - attr_name = '**' + (stmt.args.kwarg.arg if hasattr(stmt.args.kwarg, 'arg') else stmt.args.kwarg) - attr.name = attr_name - attr.mandatory = False - attr.type = build_pb2.Attribute.UNKNOWN - if attr_name in extracted_docs.attr_docs: - attr.documentation = extracted_docs.attr_docs[attr_name] - - for template, doc in extracted_docs.output_docs.items(): - output = rule.output.add() - output.template = template - output.documentation = doc - - def parse_bzl(self, bzl_file): - """Extracts documentation for all public macros from the given .bzl file. - - Args: - bzl_file: The .bzl file to extract macro documentation from. - """ - try: - with open(bzl_file) as f: - tree = ast.parse(f.read(), bzl_file) - self._add_file_docs(tree) - for stmt in tree.body: - if isinstance(stmt, ast.FunctionDef) and not stmt.name.startswith("_"): - self._add_macro_doc(stmt) - except IOError as e: - # Ignore missing extension - print("Failed to parse {0}: {1}".format(bzl_file, e.strerror)) - pass - - def proto(self): - """Returns the proto containing the macro documentation.""" - return self.__language -
diff --git a/skydoc/macro_extractor_test.py b/skydoc/macro_extractor_test.py deleted file mode 100644 index 5a488c7..0000000 --- a/skydoc/macro_extractor_test.py +++ /dev/null
@@ -1,472 +0,0 @@ -# Copyright 2016 The Bazel Authors. 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. - - - -import os -import tempfile -import textwrap -import unittest -# internal imports - -from google.protobuf import text_format -from skydoc import build_pb2 -from skydoc import macro_extractor - - -class MacroExtractorTest(unittest.TestCase): - - def check_protos(self, src, expected): - tf = tempfile.NamedTemporaryFile(mode='w+', delete=False) - tf.write(src) - tf.flush() - tf.close() - - expected_proto = build_pb2.BuildLanguage() - text_format.Merge(expected, expected_proto) - - extractor = macro_extractor.MacroDocExtractor() - extractor.parse_bzl(tf.name) - proto = extractor.proto() - os.remove(tf.name) - self.assertEqual(expected_proto, proto) - - def test_multi_line_description(self): - src = textwrap.dedent("""\ - def multiline(name, foo=False, visibility=None): - \"\"\"A rule with multiline documentation. - - Some more documentation about this rule here. - - Args: - name: A unique name for this rule. - foo: A test argument. - - Documentation for foo continued here. - visibility: The visibility of this rule. - - Documentation for visibility continued here. - \"\"\" - native.genrule( - name = name, - out = ["foo"], - cmd = "touch $@", - visibility = visibility, - ) - """) - - expected = textwrap.dedent("""\ - rule { - name: "multiline" - documentation: "A rule with multiline documentation.\\n\\nSome more documentation about this rule here." - attribute { - name: "name" - type: UNKNOWN - mandatory: true - documentation: "A unique name for this rule." - } - attribute { - name: "foo" - type: BOOLEAN - mandatory: false - default: "False" - documentation: "A test argument.\\n\\nDocumentation for foo continued here." - } - attribute { - name: "visibility" - type: UNKNOWN - mandatory: false - documentation: "The visibility of this rule.\\n\\nDocumentation for visibility continued here." - } - type: MACRO - } - """) - - self.check_protos(src, expected) - - def test_kwargs(self): - src = textwrap.dedent("""\ - def with_keyword_args(name, foo=False, **kwargs): - \"\"\"A rule with keyword args. - - Args: - name: A unique name for this rule. - foo: A test argument. - **kwargs: Keyword arguments. - \"\"\" - native.genrule( - name = name, - out = ["foo"], - cmd = "touch $@", - visibility = visibility, - **kwargs - ) - """) - - expected = textwrap.dedent("""\ - rule { - name: "with_keyword_args" - documentation: "A rule with keyword args." - attribute { - name: "name" - type: UNKNOWN - mandatory: true - documentation: "A unique name for this rule." - } - attribute { - name: "foo" - type: BOOLEAN - mandatory: false - default: "False" - documentation: "A test argument." - } - attribute { - name: "**kwargs" - type: UNKNOWN - mandatory: false - documentation: "Keyword arguments." - } - type: MACRO - } - """) - - self.check_protos(src, expected) - - def test_undocumented(self): - src = textwrap.dedent("""\ - def undocumented(name, visibility=None): - native.genrule( - name = name, - out = ["foo"], - cmd = "touch $@", - visibility = visibility, - ) - """) - - expected = textwrap.dedent("""\ - rule { - name: "undocumented" - attribute { - name: "name" - type: UNKNOWN - mandatory: true - } - attribute { - name: "visibility" - type: UNKNOWN - mandatory: false - } - type: MACRO - } - """) - - self.check_protos(src, expected) - - def test_private_macros_skipped(self): - src = textwrap.dedent("""\ - def _private(name, visibility=None): - \"\"\"A private macro that should not appear in docs. - - Args: - name: A unique name for this rule. - visibility: The visibility of this rule. - \"\"\" - native.genrule( - name = name, - out = ["foo"], - cmd = "touch $@", - visibility = visibility, - ) - - def public(name, visibility=None): - \"\"\"A public macro that should appear in docs. - - Args: - name: A unique name for this rule. - visibility: The visibility of this rule. - \"\"\" - native.genrule( - name = name, - out = ["foo"], - cmd = "touch $@", - visibility = visibility, - ) - """) - - expected = textwrap.dedent("""\ - rule { - name: "public" - documentation: "A public macro that should appear in docs." - attribute { - name: "name" - type: UNKNOWN - mandatory: true - documentation: "A unique name for this rule." - } - attribute { - name: "visibility" - type: UNKNOWN - mandatory: false - documentation: "The visibility of this rule." - } - type: MACRO - } - """) - - self.check_protos(src, expected) - - def test_rule_macro_mix(self): - src = textwrap.dedent("""\ - def _impl(ctx): - return struct() - - example_rule = rule( - implementation = _impl, - attrs = { - "arg_label": attr.label(), - "arg_string": attr.string(), - }, - ) - \"\"\"An example rule. - - Args: - name: A unique name for this rule. - arg_label: A label argument. - arg_string: A string argument. - \"\"\" - - def example_macro(name, foo, visibility=None): - \"\"\"An example macro. - - Args: - name: A unique name for this rule. - foo: A test argument. - visibility: The visibility of this rule. - \"\"\" - native.genrule( - name = name, - out = ["foo"], - cmd = "touch $@", - visibility = visibility, - ) - """) - - expected = textwrap.dedent("""\ - rule { - name: "example_macro" - documentation: "An example macro." - attribute { - name: "name" - type: UNKNOWN - mandatory: true - documentation: "A unique name for this rule." - } - attribute { - name: "foo" - type: UNKNOWN - mandatory: true - documentation: "A test argument." - } - attribute { - name: "visibility" - type: UNKNOWN - mandatory: false - documentation: "The visibility of this rule." - } - type: MACRO - } - """) - - self.check_protos(src, expected) - - def test_macro_with_example_doc(self): - src = textwrap.dedent("""\ - def macro_with_example(name, foo, visibility=None): - \"\"\"Macro with examples. - - Args: - name: A unique name for this rule. - foo: A test argument. - visibility: The visibility of this rule. - - Example: - Here is an example of how to use this rule. - \"\"\" - native.genrule( - name = name, - out = ["foo"], - cmd = "touch $@", - visibility = visibility, - ) - """) - - expected = textwrap.dedent("""\ - rule { - name: "macro_with_example" - documentation: "Macro with examples." - example_documentation: "Here is an example of how to use this rule." - attribute { - name: "name" - type: UNKNOWN - mandatory: true - documentation: "A unique name for this rule." - } - attribute { - name: "foo" - type: UNKNOWN - mandatory: true - documentation: "A test argument." - } - attribute { - name: "visibility" - type: UNKNOWN - mandatory: false - documentation: "The visibility of this rule." - } - type: MACRO - } - """) - - self.check_protos(src, expected) - - def test_macro_with_output_doc(self): - src = textwrap.dedent("""\ - def macro_with_outputs(name, foo, visibility=None): - \"\"\"Macro with output documentation. - - Outputs: - %{name}.jar: A Java archive. - %{name}_deploy.jar: A Java archive suitable for deployment. - - Only built if explicitly requested. - - Args: - name: A unique name for this rule. - foo: A test argument. - visibility: The visibility of this rule. - \"\"\" - native.genrule( - name = name, - out = ["foo"], - cmd = "touch $@", - visibility = visibility, - ) - """) - - expected = textwrap.dedent("""\ - rule { - name: "macro_with_outputs" - documentation: "Macro with output documentation." - attribute { - name: "name" - type: UNKNOWN - mandatory: true - documentation: "A unique name for this rule." - } - attribute { - name: "foo" - type: UNKNOWN - mandatory: true - documentation: "A test argument." - } - attribute { - name: "visibility" - type: UNKNOWN - mandatory: false - documentation: "The visibility of this rule." - } - output { - template: "%{name}.jar" - documentation: "A Java archive." - } - output { - template: "%{name}_deploy.jar" - documentation: "A Java archive suitable for deployment.\\n\\nOnly built if explicitly requested." - } - type: MACRO - } - """) - - self.check_protos(src, expected) - - def test_file_doc_title_only(self): - src = textwrap.dedent("""\ - \"\"\"Example rules\"\"\" - """) - tf = tempfile.NamedTemporaryFile(mode='w+', delete=False) - tf.write(src) - tf.flush() - tf.close() - - extractor = macro_extractor.MacroDocExtractor() - extractor.parse_bzl(tf.name) - os.remove(tf.name) - self.assertEqual('Example rules', extractor.title) - self.assertEqual('', extractor.description) - - def test_file_doc_title_description(self): - src = textwrap.dedent("""\ - \"\"\"Example rules - - This file contains example Bazel rules. - - Documentation continued here. - \"\"\" - """) - tf = tempfile.NamedTemporaryFile(mode='w+', delete=False) - tf.write(src) - tf.flush() - tf.close() - - extractor = macro_extractor.MacroDocExtractor() - extractor.parse_bzl(tf.name) - os.remove(tf.name) - self.assertEqual('Example rules', extractor.title) - self.assertEqual('This file contains example Bazel rules.' - '\n\nDocumentation continued here.', - extractor.description) - - def test_file_doc_title_multiline(self): - src = textwrap.dedent("""\ - \"\"\"Example rules - for Bazel - - This file contains example Bazel rules. - - Documentation continued here. - \"\"\" - """) - tf = tempfile.NamedTemporaryFile(mode='w+', delete=False) - tf.write(src) - tf.flush() - tf.close() - - extractor = macro_extractor.MacroDocExtractor() - extractor.parse_bzl(tf.name) - os.remove(tf.name) - self.assertEqual('Example rules for Bazel', extractor.title) - self.assertEqual('This file contains example Bazel rules.' - '\n\nDocumentation continued here.', - extractor.description) - - def test_loads_ignored(self): - src = textwrap.dedent("""\ - load("//foo/bar:baz.bzl", "foo_library") - load("//foo/bar:baz.bzl", "foo_test", orig_foo_binary = "foo_binary") - """) - expected = '' - self.check_protos(src, expected) - -if __name__ == '__main__': - unittest.main()
diff --git a/skydoc/main.py b/skydoc/main.py deleted file mode 100755 index 408cd8e..0000000 --- a/skydoc/main.py +++ /dev/null
@@ -1,334 +0,0 @@ -# Copyright 2016 The Bazel Authors. 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. - -"""Documentation generator for Skylark""" - -from __future__ import print_function -# internal imports -import jinja2 -import mistune -import os -import posixpath -import re -import shutil -import sys -import tempfile -import zipfile - -from optparse import OptionParser - -from bazel_tools.tools.python.runfiles import runfiles as runfiles_lib -from skydoc import common -from skydoc import load_extractor -from skydoc import macro_extractor -from skydoc import rule -from skydoc import rule_extractor - -DEFAULT_OUTPUT_DIR = '.' -DEFAULT_OUTPUT_FILE = 'skydoc.zip' - -WORKSPACE_DIR = 'io_bazel_skydoc' -TEMPLATE_PATH = 'skydoc/templates' -CSS_PATH = 'skydoc/sass' - -CSS_FILE = 'main.css' - -def _create_jinja_environment(runfiles, site_root, link_ext): - def _Load(path): - loc = runfiles.Rlocation(posixpath.join(WORKSPACE_DIR, TEMPLATE_PATH, path)) - if loc: - with open(loc, "rb") as f: - return f.read().decode("utf-8") - return None - - env = jinja2.Environment( - loader=jinja2.FunctionLoader(_Load), - keep_trailing_newline=True, - line_statement_prefix='%') - env.filters['markdown'] = lambda text: jinja2.Markup(mistune.markdown(text)) - env.filters['doc_link'] = ( - lambda fname: site_root + '/' + fname + '.' + link_ext) - env.filters['link'] = lambda fname: site_root + '/' + fname - return env - - -# TODO(dzc): Remove this workaround once we switch to a self-contained Python -# binary format such as PEX. -def _runfile_path(runfiles, path): - return runfiles.Rlocation(posixpath.join(WORKSPACE_DIR, path)) - -def merge_languages(macro_language, rule_language): - for rule in rule_language.rule: - new_rule = macro_language.rule.add() - new_rule.CopyFrom(rule) - return macro_language - -class WriterOptions(object): - def __init__(self, output_dir, output_file, output_zip, overview, - overview_filename, link_ext, site_root): - self.output_dir = output_dir - self.output_file = output_file - self.output_zip = output_zip - self.overview = overview - self.overview_filename = overview_filename - self.link_ext = link_ext - - self.site_root = site_root - if len(self.site_root) > 0 and self.site_root.endswith('/'): - self.site_root = self.site_root[:-1] - -class MarkdownWriter(object): - """Writer for generating documentation in Markdown.""" - - def __init__(self, writer_options, runfiles): - self.__options = writer_options - self.__env = _create_jinja_environment(runfiles, - self.__options.site_root, - self.__options.link_ext) - - def write(self, rulesets): - """Write the documentation for the rules contained in rulesets.""" - try: - temp_dir = tempfile.mkdtemp() - output_files = [] - for ruleset in rulesets: - if not ruleset.empty(): - output_files.append(self._write_ruleset(temp_dir, ruleset)) - if self.__options.overview: - output_files.append(self._write_overview(temp_dir, rulesets)) - - if self.__options.output_zip: - # We are generating a zip archive containing all the documentation. - # Write each documentation file generated in the temp directory to the - # zip file. - with zipfile.ZipFile(self.__options.output_file, 'w') as zf: - for output_file, output_path in output_files: - zf.write(output_file, output_path) - else: - # We are generating documentation in the output_dir directory. Copy each - # documentation file to output_dir. - for output_file, output_path in output_files: - dest_file = os.path.join(self.__options.output_dir, output_path) - dest_dir = os.path.dirname(dest_file) - if not os.path.exists(dest_dir): - os.makedirs(dest_dir) - shutil.copyfile(output_file, dest_file) - - finally: - # Delete temporary directory. - shutil.rmtree(temp_dir) - - def _write_ruleset(self, output_dir, ruleset): - # Load template and render Markdown. - template = self.__env.get_template('markdown.jinja') - out = template.render(ruleset=ruleset) - - # Write output to file. Output files are created in a directory structure - # that matches that of the input file. - output_path = ruleset.output_file + '.md' - output_file = "%s/%s" % (output_dir, output_path) - file_dirname = os.path.dirname(output_file) - if not os.path.exists(file_dirname): - os.makedirs(file_dirname) - with open(output_file, "w") as f: - f.write(out) - return (output_file, output_path) - - def _write_overview(self, output_dir, rulesets): - template = self.__env.get_template('markdown_overview.jinja') - out = template.render(rulesets=rulesets) - - output_file = "%s/%s.md" % (output_dir, self.__options.overview_filename) - with open(output_file, "w") as f: - f.write(out) - return (output_file, "%s.md" % self.__options.overview_filename) - -class HtmlWriter(object): - """Writer for generating documentation in HTML.""" - - def __init__(self, options, runfiles): - self.__runfiles = runfiles - self.__options = options - self.__env = _create_jinja_environment(runfiles, - self.__options.site_root, - self.__options.link_ext) - - def write(self, rulesets): - # Generate navigation used for all rules. - nav_template = self.__env.get_template('nav.jinja') - nav = nav_template.render( - rulesets=rulesets, - overview=self.__options.overview, - overview_filename=self.__options.overview_filename) - - try: - temp_dir = tempfile.mkdtemp() - output_files = [] - for ruleset in rulesets: - if not ruleset.empty(): - output_files.append(self._write_ruleset(temp_dir, ruleset, nav)) - if self.__options.overview: - output_files.append(self._write_overview(temp_dir, rulesets, nav)) - - if self.__options.output_zip: - with zipfile.ZipFile(self.__options.output_file, 'w') as zf: - for output_file, output_path in output_files: - zf.write(output_file, output_path) - zf.write(_runfile_path(self.__runfiles, - posixpath.join(CSS_PATH, CSS_FILE)), - CSS_FILE) - else: - for output_file, output_path in output_files: - dest_file = os.path.join(self.__options.output_dir, output_path) - dest_dir = os.path.dirname(dest_file) - if not os.path.exists(dest_dir): - os.makedirs(dest_dir) - shutil.copyfile(output_file, dest_file) - - # Copy CSS file. - shutil.copyfile(_runfile_path(self.__runfiles, - posixpath.join(CSS_PATH, CSS_FILE)), - os.path.join(self.__options.output_dir, CSS_FILE)) - finally: - # Delete temporary directory. - shutil.rmtree(temp_dir) - - def _write_ruleset(self, output_dir, ruleset, nav): - # Load template and render markdown. - template = self.__env.get_template('html.jinja') - out = template.render(title=ruleset.title, ruleset=ruleset, nav=nav) - - # Write output to file. Output files are created in a directory structure - # that matches that of the input file. - output_path = ruleset.output_file + '.html' - output_file = "%s/%s" % (output_dir, output_path) - file_dirname = os.path.dirname(output_file) - if not os.path.exists(file_dirname): - os.makedirs(file_dirname) - with open(output_file, "w") as f: - f.write(out) - return (output_file, output_path) - - def _write_overview(self, output_dir, rulesets, nav): - template = self.__env.get_template('html_overview.jinja') - out = template.render(title='Overview', rulesets=rulesets, nav=nav) - - output_file = "%s/%s.html" % (output_dir, self.__options.overview_filename) - with open(output_file, "w") as f: - f.write(out) - return (output_file, "%s.html" % self.__options.overview_filename) - -def main(argv): - parser = OptionParser() - parser.add_option('--output_dir', default='', - help='The directory to write the output generated documentation to if --zip=false') - parser.add_option('--output_file', default='', - help='The output zip archive file to write if --zip=true.') - parser.add_option('--format', default='markdown', - help='The output format. Possible values are markdown and html') - parser.add_option('--zip', action='store_true', default=True, - help='Whether to generate a ZIP arhive containing the output files. If ' - '--zip is true, then skydoc will generate a zip file, skydoc.zip by ' - 'default or as specified by --output_file. If --zip is false, then ' - 'skydoc will generate documentation, either in Markdown or HTML as ' - 'specifed by --format, in the current directory or --output_dir if set.') - parser.add_option('--strip_prefix', default='', - help='The directory prefix to strip from all generated docs, which are ' - 'generated in subdirectories that match the package structure of the ' - 'input .bzl files. The prefix to strip must be common to all .bzl files; ' - 'otherwise, skydoc will raise an error.') - parser.add_option('--overview', action='store_true', - help='Whether to generate an overview page') - parser.add_option('--overview_filename', default='index', - help='The file name to use for the overview page.') - parser.add_option('--link_ext', default='html', - help='The file extension used for links in the generated documentation') - parser.add_option('--site_root', default='', - help='The site root to be prepended to all URLs in the generated documentation') - (options, args) = parser.parse_args(argv) - - if options.output_dir and options.output_file: - sys.stderr.write('Only one of --output_dir or --output_file can be set.') - sys.exit(1) - - if not options.output_dir: - options.output_dir = DEFAULT_OUTPUT_DIR - if not options.output_file: - options.output_file = DEFAULT_OUTPUT_FILE - - bzl_files = args[1:] - - try: - strip_prefix = common.validate_strip_prefix(options.strip_prefix, bzl_files) - except common.InputError as err: - print(err.message) - sys.exit(1) - - runfiles = runfiles_lib.Create() - if not runfiles: - # TODO(laszlocsomor): fix https://github.com/bazelbuild/bazel/issues/6212 - # and remove this if-block once Bazel is released with that bugfix. - if (not os.environ.get("RUNFILES_DIR") and - not os.environ.get("RUNFILES_MANIFEST_FILE")): - argv0 = sys.argv[0] - pos = argv0.rfind('%s%s%s' % (os.sep, WORKSPACE_DIR, os.sep)) - if pos > -1: - dirpath = argv0[0:pos] - if not os.path.isdir(dirpath): - print("ERROR: Cannot access runfiles directory (%s)" % dirpath) - sys.exit(1) - runfiles = runfiles_lib.CreateDirectoryBased(dirpath) - - if not runfiles: - print("ERROR: Cannot load runfiles") - sys.exit(1) - - rulesets = [] - load_sym_extractor = load_extractor.LoadExtractor() - for bzl_file in bzl_files: - load_symbols = [] - try: - load_symbols = load_sym_extractor.extract(bzl_file) - except load_extractor.LoadExtractorError as e: - print("ERROR: Error extracting loaded symbols from %s: %s" % - (bzl_file, str(e))) - sys.exit(2) - - # TODO(dzc): Make MacroDocExtractor and RuleDocExtractor stateless. - macro_doc_extractor = macro_extractor.MacroDocExtractor() - rule_doc_extractor = rule_extractor.RuleDocExtractor() - macro_doc_extractor.parse_bzl(bzl_file) - rule_doc_extractor.parse_bzl(bzl_file, load_symbols) - merged_language = merge_languages(macro_doc_extractor.proto(), - rule_doc_extractor.proto()) - rulesets.append( - rule.RuleSet(bzl_file, merged_language, macro_doc_extractor.title, - macro_doc_extractor.description, strip_prefix, - options.format)) - writer_options = WriterOptions( - options.output_dir, options.output_file, options.zip, options.overview, - options.overview_filename, options.link_ext, options.site_root) - if options.format == "markdown": - markdown_writer = MarkdownWriter(writer_options, runfiles) - markdown_writer.write(rulesets) - elif options.format == "html": - html_writer = HtmlWriter(writer_options, runfiles) - html_writer.write(rulesets) - else: - sys.stderr.write( - 'Invalid output format: %s. Possible values are markdown and html' - % options.format) - -if __name__ == '__main__': - main(sys.argv)
diff --git a/skydoc/rule.py b/skydoc/rule.py deleted file mode 100644 index b4a1ecc..0000000 --- a/skydoc/rule.py +++ /dev/null
@@ -1,173 +0,0 @@ -# Copyright 2016 The Bazel Authors. 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. - -"""Representations used for rendering documentation templates.""" - - -# internal imports -import os -from skydoc import build_pb2 - - -class Attribute(object): - """Representation of an attribute used to render documentation templates.""" - - NAME_LINK = ( - '<a href="https://bazel.build/docs/build-ref.html#name">Name</a>') - LABEL_LINK = ( - '<a href="https://bazel.build/docs/build-ref.html#labels">Label</a>') - LABELS_LINK = ( - '<a href="https://bazel.build/docs/build-ref.html#labels">labels</a>') - - def __init__(self, proto): - self.__proto = proto - self.name = proto.name - self.type = self._get_type_str(proto) - if proto.name == 'name' and not proto.documentation: - self.documentation = 'A unique name for this rule.' - else: - self.documentation = proto.documentation - - def _get_type_str(self, proto): - type_str = '' - if proto.type == build_pb2.Attribute.INTEGER: - type_str = 'Integer' - elif proto.type == build_pb2.Attribute.STRING: - type_str = 'String' - elif proto.type == build_pb2.Attribute.LABEL: - type_str = self.LABEL_LINK - elif proto.type == build_pb2.Attribute.OUTPUT: - type_str = 'Output' - elif proto.type == build_pb2.Attribute.STRING_LIST: - type_str = 'List of strings' - elif proto.type == build_pb2.Attribute.LABEL_LIST: - type_str = 'List of %s' % self.LABELS_LINK - elif proto.type == build_pb2.Attribute.OUTPUT_LIST: - type_str = 'List of outputs' - elif proto.type == build_pb2.Attribute.DISTRIBUTION_SET: - type_str = 'Distribution Set' - elif proto.type == build_pb2.Attribute.LICENSE: - type_str = 'License' - elif proto.type == build_pb2.Attribute.STRING_DICT: - type_str = 'Dictionary mapping strings to string' - elif proto.type == build_pb2.Attribute.FILESET_ENTRY_LIST: - type_str = 'List of FilesetEntry' - elif proto.type == build_pb2.Attribute.LABEL_LIST_DICT: - type_str = 'Dictionary mapping strings to lists of %s' % self.LABELS_LINK - elif proto.type == build_pb2.Attribute.STRING_LIST_DICT: - type_str = 'Dictionary mapping strings to lists of strings' - elif proto.type == build_pb2.Attribute.BOOLEAN: - type_str = 'Boolean' - elif proto.type == build_pb2.Attribute.TRISTATE: - type_str = 'Tristate' - elif proto.type == build_pb2.Attribute.INTEGER_LIST: - type_str = 'List of integers' - elif proto.type == build_pb2.Attribute.LABEL_DICT_UNARY: - type_str = 'Label Dict Unary' - elif proto.type == build_pb2.Attribute.SELECTOR_LIST: - type_str = 'Selector List' - elif proto.type == build_pb2.Attribute.LABEL_KEYED_STRING_DICT: - type_str = 'Dictionary mapping %s to strings' % self.LABELS_LINK - else: - if proto.name == 'name': - type_str = self.NAME_LINK - else: - type_str = 'Unknown' - - type_str += '; Required' if proto.mandatory else '; Optional' - if proto.HasField('default') and not proto.mandatory: - type_str += '; Default is ' + proto.default - return type_str - - -class Output(object): - """Representation of an output used to render documentation templates.""" - - def __init__(self, proto): - self.__proto = proto - self.template = proto.template - self.documentation = proto.documentation - -class Rule(object): - """Representation of a rule used to render documentation templates.""" - - def __init__(self, proto): - self.__proto = proto - self.name = proto.name - self.type = proto.type - self.documentation = proto.documentation - self.example_documentation = proto.example_documentation - self.signature = self._get_signature(proto) - self.attributes = [] - for attribute in proto.attribute: - self.attributes.append(Attribute(attribute)) - self.outputs = [] - for output in proto.output: - self.outputs.append(Output(output)) - - parts = proto.documentation.split("\n\n") - self.short_documentation = parts[0] - - def _get_signature(self, proto): - """Returns the rule signature for this rule.""" - signature = proto.name + '(' - for i in range(len(proto.attribute)): - attr = proto.attribute[i] - signature += '<a href="#%s.%s">%s</a>' % (proto.name, attr.name, - attr.name) - if i < len(proto.attribute) - 1: - signature += ', ' - signature += ')' - return signature - - -class RuleSet(object): - """Representation of a rule set used to render documentation templates.""" - - def __init__(self, bzl_file, language, title, description, strip_prefix, - format): - self.bzl_file = bzl_file - file_basename = os.path.basename(bzl_file) - self.name = file_basename.replace('.bzl', '') - self.language = language - self.title = title if title else "%s Rules" % self.name - self.description = description - - # Generate output file name. - file_extension = 'html' if format == 'html' else 'md' - assert self.bzl_file.startswith(strip_prefix) - output_path = self.bzl_file.replace('.bzl', '') - self.output_file = output_path[len(strip_prefix):] - - # Populate all rules in this ruleset. - self.definitions = [] - self.rules = [] - self.repository_rules = [] - self.macros = [] - for rule_proto in language.rule: - definition = Rule(rule_proto) - self.definitions.append(definition) - if rule_proto.type == build_pb2.RuleDefinition.RULE: - self.rules.append(definition) - elif rule_proto.type == build_pb2.RuleDefinition.MACRO: - self.macros.append(definition) - else: - assert rule_proto.type == build_pb2.RuleDefinition.REPOSITORY_RULE - self.repository_rules.append(definition) - - def empty(self): - """Return True if there is nothing to document.""" - return not any([self.rules, - self.macros, - self.repository_rules])
diff --git a/skydoc/rule_extractor.py b/skydoc/rule_extractor.py deleted file mode 100644 index abb6134..0000000 --- a/skydoc/rule_extractor.py +++ /dev/null
@@ -1,259 +0,0 @@ -# Copyright 2016 The Bazel Authors. 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. - -"""Extractor for Skylark rule documentation.""" - -import ast -import functools -# internal imports - -from skydoc import build_pb2 -from skydoc import common -from skydoc.stubs import attr -from skydoc.stubs import skylark_globals - - -SKYLARK_STUBS = { - "attr": attr, - "aspect": skylark_globals.aspect, - "DATA_CFG": skylark_globals.DATA_CFG, - "HOST_CFG": skylark_globals.HOST_CFG, - "PACKAGE_NAME": skylark_globals.PACKAGE_NAME, - "REPOSITORY_NAME": skylark_globals.REPOSITORY_NAME, - "provider": skylark_globals.provider, - "FileType": skylark_globals.FileType, - "Label": skylark_globals.Label, - "native": skylark_globals.native, - "select": skylark_globals.select, - "struct": skylark_globals.struct, - "repository_rule": skylark_globals.repository_rule, - "rule": skylark_globals.rule, - "load": skylark_globals.load, -} -"""Stubs for Skylark globals to be used to evaluate the .bzl file.""" - - -SKYLARK_GLOBAL_SYMBOLS = set(SKYLARK_STUBS.keys()) - - -def create_stubs(skylark_stubs, load_symbols): - """Combines Skylark stubs with loaded symbols. - - This function creates a copy of the global Skylark stubs and combines them - with symbols from the list of load_extractor.LoadSymbol, which contain - information about symbols extracted from other .bzl files. The stubs created - for the loaded symbols are global variables set to the empty string. - - Args: - skylark_stubs: Dict containing the Skylark global stubs. - load_symbols: List of load_extractor.LoadSymbol objects containing - information about symbols extracted from other .bzl files. - - Returns: - Dictionary containing both the Skylark global stubs and stubs created for - the loaded symbols. - """ - stubs = dict(skylark_stubs) - for load_symbol in load_symbols: - if load_symbol.alias: - stubs[load_symbol.alias] = "" - else: - stubs[load_symbol.symbol] = "" - return stubs - - -class RuleDocExtractor(object): - """Extracts documentation for rules from a .bzl file.""" - - def __init__(self): - """Inits RuleDocExtractor with a new BuildLanguage proto""" - self.__language = build_pb2.BuildLanguage() - self.__extracted_rules = {} - self.__load_symbols = [] - - def _exec_code(self, compiled, global_stubs): - """Executes compiled code with a copy of the global stubs. - - This has to be extracted into a separate function in order to be compatible - with the exec statement in older Python versions, which otherwise throws a - syntax error: "unqualified exec is not allowed in function". - - Returns: - The modified environment after the execution is finished. - """ - env = global_stubs.copy() - exec(compiled, env) - return env - - def _process_skylark(self, bzl_file, load_symbols): - """Evaluates the Skylark code in the .bzl file. - - This function evaluates the Skylark code in the .bzl file as Python against - Skylark stubs to extract the rules and attributes defined in the file. The - extracted rules are kept in the __extracted_rules map keyed by rule name. - - Args: - bzl_file: The .bzl file to evaluate. - load_symbols: List of load_extractor.LoadSymbol objects containing info - about symbols load()ed from other .bzl files. - """ - with open(bzl_file) as f: - compiled = compile(f.read(), bzl_file, 'exec') - global_stubs = create_stubs(SKYLARK_STUBS, load_symbols) - env = self._exec_code(compiled, global_stubs) - - new_globals = ( - defn for defn in env.items() if not defn[0] in global_stubs - ) - for name, obj in new_globals: - if (isinstance(obj, skylark_globals.RuleDescriptor) and - not name.startswith('_')): - obj.attrs['name'] = attr.AttrDescriptor( - type=build_pb2.Attribute.UNKNOWN, mandatory=True, name='name') - self.__extracted_rules[name] = obj - - def _add_rule_doc(self, name, doc): - """Parses the attribute documentation from the docstring. - - Parses the attribute documentation in the given docstring and associates the - rule and attribute documentation with the corresponding rule extracted from - the .bzl file. - - Args: - name: The name of the rule. - doc: The docstring extracted for the rule. - """ - extracted_docs = common.parse_docstring(doc) - if name in self.__extracted_rules: - rule = self.__extracted_rules[name] - rule.doc = extracted_docs.doc - rule.example_doc = extracted_docs.example_doc - for attr_name, desc in extracted_docs.attr_docs.items(): - if attr_name in rule.attrs: - rule.attrs[attr_name].doc = desc - - # Match the output name from the docstring with the corresponding output - # template name extracted from rule() and store a mapping of output - # template name to documentation. - for output_name, desc in extracted_docs.output_docs.items(): - if output_name in rule.outputs: - output_template = rule.outputs[output_name] - rule.output_docs[output_template] = desc - - def _extract_docstrings(self, bzl_file): - """Extracts the docstrings for all public rules in the .bzl file. - - This function parses the .bzl file and extracts the docstrings for all - public rules in the file that were extracted in _process_skylark. It calls - _add_rule_doc for to parse the attribute documentation in each docstring - and associate them with the extracted rules and attributes. - - Args: - bzl_file: The .bzl file to extract docstrings from. - """ - try: - tree = None - with open(bzl_file) as f: - tree = ast.parse(f.read(), bzl_file) - key = None - for node in ast.iter_child_nodes(tree): - if isinstance(node, ast.Assign): - name = node.targets[0].id - if not name.startswith("_"): - key = name - continue - elif isinstance(node, ast.Expr) and key: - # Python itself does not treat strings defined immediately after a - # global variable definition as a docstring. Only extract string and - # parse as docstring if it is defined. - if hasattr(node.value, 's'): - self._add_rule_doc(key, node.value.s.strip()) - key = None - except IOError: - print("Failed to parse {0}: {1}".format(bzl_file, e.strerror)) - pass - - def _assemble_protos(self): - """Builds the BuildLanguage protos for the extracted rule documentation. - - Iterates through the map of extracted rule documentation and builds a - BuildLanguage proto containing the documentation for public rules extracted - from the .bzl file. - """ - rules = [] - for rule_name, rule_desc in self.__extracted_rules.items(): - rule_desc.name = rule_name - rules.append(rule_desc) - rules = sorted(rules, key=lambda rule_desc: rule_desc.name) - - for rule_desc in rules: - rule = self.__language.rule.add() - rule.name = rule_desc.name - if rule_desc.type == 'rule': - rule.type = build_pb2.RuleDefinition.RULE - else: - rule.type = build_pb2.RuleDefinition.REPOSITORY_RULE - if rule_desc.doc: - rule.documentation = rule_desc.doc - if rule_desc.example_doc: - rule.example_documentation = rule_desc.example_doc - - if hasattr(functools, 'cmp_to_key'): - # Python 2.7 and 3.x - attrs = sorted(rule_desc.attrs.values(), key=functools.cmp_to_key(attr.attr_compare)) - else: - # Python <2.7 - attrs = sorted(rule_desc.attrs.values(), cmp=attr.attr_compare) - - for attr_desc in attrs: - if attr_desc.name.startswith("_"): - continue - attr_proto = rule.attribute.add() - attr_proto.name = attr_desc.name - if attr_desc.doc: - attr_proto.documentation = attr_desc.doc - attr_proto.type = attr_desc.type - attr_proto.mandatory = attr_desc.mandatory - if attr_desc.default != None: - attr_proto.default = attr_desc.default - - for template, doc in rule_desc.output_docs.items(): - output = rule.output.add() - output.template = template - output.documentation = doc - - for load_symbol in self.__load_symbols: - load = self.__language.load.add() - load.label = load_symbol.label - load.symbol = load_symbol.symbol - load.alias = load_symbol.alias - - def parse_bzl(self, bzl_file, load_symbols): - """Extracts the documentation for all public rules from the given .bzl file. - - The Skylark code is first evaluated against stubs to extract rule and - attributes with complete type information. Then, the .bzl file is parsed - to extract the docstrings for each of the rules. Finally, the BuildLanguage - proto is assembled with the extracted rule documentation. - - Args: - bzl_file: The .bzl file to extract rule documentation from. - """ - self._process_skylark(bzl_file, load_symbols) - self._extract_docstrings(bzl_file) - self._assemble_protos() - - def proto(self): - """Returns the proto containing the macro documentation.""" - return self.__language
diff --git a/skydoc/rule_extractor_test.py b/skydoc/rule_extractor_test.py deleted file mode 100644 index 230ee4e..0000000 --- a/skydoc/rule_extractor_test.py +++ /dev/null
@@ -1,686 +0,0 @@ -# Copyright 2016 The Bazel Authors. 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. - - -import os -import tempfile -import textwrap -import unittest -# internal imports - -from google.protobuf import text_format -from skydoc import build_pb2 -from skydoc import load_extractor -from skydoc import rule_extractor - - -class RuleExtractorTest(unittest.TestCase): - - def test_create_stubs(self): - stubs = { - 'foo': 'bar', - 'bar': 'baz', - } - load_symbols = [ - load_extractor.LoadSymbol('//foo:bar.bzl', 'bar_library', None), - load_extractor.LoadSymbol('//foo:bar.bzl', 'foo_bar_binary', - 'bar_binary'), - ] - expected = { - 'foo': 'bar', - 'bar': 'baz', - 'bar_library': '', - 'bar_binary': '', - } - self.assertEqual(expected, rule_extractor.create_stubs(stubs, load_symbols)) - - - def check_protos(self, src, expected, load_symbols=[]): - tf = tempfile.NamedTemporaryFile(mode='w+', delete=False) - tf.write(src) - tf.flush() - tf.close() - - expected_proto = build_pb2.BuildLanguage() - text_format.Merge(expected, expected_proto) - - extractor = rule_extractor.RuleDocExtractor() - extractor.parse_bzl(tf.name, load_symbols) - os.remove(tf.name) - proto = extractor.proto() - self.assertEqual(expected_proto, proto) - - def test_all_types(self): - src = textwrap.dedent("""\ - def impl(ctx): - return struct() - - all_types = rule( - implementation = impl, - attrs = { - "arg_bool": attr.bool(default=True), - "arg_int": attr.int(default=10), - "arg_int_list": attr.int_list(default=[1, 2]), - "arg_label": attr.label( - default=Label("//foo:bar", - relative_to_caller_repository=True)), - "arg_label_list": attr.label_list( - default=[Label("//foo:bar"), Label("//bar:baz")]), - "arg_license": attr.license(), - "arg_output": attr.output(default=Label("//foo:bar")), - "arg_output_list": attr.output_list( - default=[Label("//foo:bar"), Label("//bar:baz")]), - "arg_string": attr.string(default="foo"), - "arg_string_dict": attr.string_dict(default={"foo": "bar"}), - "arg_string_list": attr.string_list(default=["foo", "bar"]), - "arg_string_list_dict": attr.string_list_dict( - default={"foo": ["bar", "baz"]}), - }, - ) - \"\"\"Test rule with all types. - - Args: - name: A unique name for this rule. - arg_bool: A boolean argument. - arg_int: An integer argument. - arg_int_list: A list of integers argument. - arg_label: A label argument. - arg_label_list: A list of labels argument. - arg_license: A license argument. - arg_output: An output argument. - arg_output_list: A list of outputs argument. - arg_string: A string argument. - arg_string_dict: A dictionary mapping string to string argument. - arg_string_list: A list of strings argument. - arg_string_list_dict: A dictionary mapping string to list of string argument. - \"\"\" - """) - - expected = textwrap.dedent(""" - rule { - name: "all_types" - documentation: "Test rule with all types." - attribute { - name: "name" - type: UNKNOWN - mandatory: true - documentation: "A unique name for this rule." - } - attribute { - name: "arg_bool" - type: BOOLEAN - mandatory: false - documentation: "A boolean argument." - default: "True" - } - attribute { - name: "arg_int" - type: INTEGER - mandatory: false - documentation: "An integer argument." - default: "10" - } - attribute { - name: "arg_int_list" - type: INTEGER_LIST - mandatory: false - documentation: "A list of integers argument." - default: "[1, 2]" - } - attribute { - name: "arg_label" - type: LABEL - mandatory: false - documentation: "A label argument." - default: "//foo:bar" - } - attribute { - name: "arg_label_list" - type: LABEL_LIST - mandatory: false - documentation: "A list of labels argument." - default: "[\'//foo:bar\', \'//bar:baz\']" - } - attribute { - name: "arg_license" - type: LICENSE - mandatory: false - documentation: "A license argument." - } - attribute { - name: "arg_output" - type: OUTPUT - mandatory: false - documentation: "An output argument." - default: "//foo:bar" - } - attribute { - name: "arg_output_list" - type: OUTPUT_LIST - mandatory: false - documentation: "A list of outputs argument." - default: "[\'//foo:bar\', \'//bar:baz\']" - } - attribute { - name: "arg_string" - type: STRING - mandatory: false - documentation: "A string argument." - default: "\'foo\'" - } - attribute { - name: "arg_string_dict" - type: STRING_DICT - mandatory: false - documentation: "A dictionary mapping string to string argument." - default: "{\'foo\': \'bar\'}" - } - attribute { - name: "arg_string_list" - type: STRING_LIST - mandatory: false - documentation: "A list of strings argument." - default: "[\'foo\', \'bar\']" - } - attribute { - name: "arg_string_list_dict" - type: STRING_LIST_DICT - mandatory: false - documentation: "A dictionary mapping string to list of string argument." - default: "{\'foo\': [\'bar\', \'baz\']}" - } - type: RULE - } - """) - - self.check_protos(src, expected) - - def test_undocumented(self): - src = textwrap.dedent("""\ - def _impl(ctx): - return struct() - - undocumented = rule( - implementation = _impl, - attrs = { - "arg_label": attr.label(), - "arg_string": attr.string(), - }, - ) - """) - - expected = textwrap.dedent("""\ - rule { - name: "undocumented" - attribute { - name: "name" - type: UNKNOWN - mandatory: true - } - attribute { - name: "arg_label" - type: LABEL - mandatory: false - } - attribute { - name: "arg_string" - type: STRING - mandatory: false - default: "''" - } - type: RULE - } - """) - - self.check_protos(src, expected) - - def test_private_rules_skipped(self): - src = textwrap.dedent("""\ - def _private_impl(ctx): - return struct() - - def _public_impl(ctx): - return struct() - - _private = rule( - implementation = _private_impl, - attrs = { - "arg_label": attr.label(), - "arg_string": attr.string(), - }, - ) - \"\"\"A private rule that should not appear in documentation. - - Args: - name: A unique name for this rule. - arg_label: A label argument. - arg_string: A string argument. - \"\"\" - - public = rule( - implementation = _public_impl, - attrs = { - "arg_label": attr.label(), - "arg_string": attr.string(), - }, - ) - \"\"\"A public rule that should appear in documentation. - - Args: - name: A unique name for this rule. - arg_label: A label argument. - arg_string: A string argument. - \"\"\" - """) - - expected = textwrap.dedent(""" - rule { - name: "public" - documentation: "A public rule that should appear in documentation." - attribute { - name: "name" - type: UNKNOWN - mandatory: true - documentation: "A unique name for this rule." - } - attribute { - name: "arg_label" - type: LABEL - mandatory: false - documentation: "A label argument." - } - attribute { - name: "arg_string" - type: STRING - mandatory: false - documentation: "A string argument." - default: "''" - } - type: RULE - } - """) - - self.check_protos(src, expected) - - def test_rule_with_generated_impl(self): - src = textwrap.dedent("""\ - def real_impl(ctx): - return struct() - - def macro(): - return real_impl - - impl = macro() - - thisrule = rule( - implementation = impl, - ) - """) - - expected = textwrap.dedent("""\ - rule { - name: "thisrule" - attribute { - name: "name" - type: UNKNOWN - mandatory: true - } - type: RULE - } - """) - - self.check_protos(src, expected) - - def test_multi_line_description(self): - src = textwrap.dedent("""\ - def _impl(ctx): - return struct() - - multiline = rule( - implementation = _impl, - attrs = { - "arg_bool": attr.bool(), - "arg_label": attr.label(), - }, - ) - \"\"\"A rule with multiline documentation. - - Some more documentation about this rule here. - - Args: - name: A unique name for this rule. - arg_bool: A boolean argument. - - Documentation for arg_bool continued here. - arg_label: A label argument. - - Documentation for arg_label continued here. - \"\"\" - """) - - expected = textwrap.dedent("""\ - rule { - name: "multiline" - documentation: "A rule with multiline documentation.\\n\\nSome more documentation about this rule here." - attribute { - name: "name" - type: UNKNOWN - mandatory: true - documentation: "A unique name for this rule." - } - attribute { - name: "arg_bool" - type: BOOLEAN - mandatory: false - documentation: "A boolean argument.\\n\\nDocumentation for arg_bool continued here." - default: "False" - } - attribute { - name: "arg_label" - type: LABEL - mandatory: false - documentation: "A label argument.\\n\\nDocumentation for arg_label continued here." - } - type: RULE - } - """) - - self.check_protos(src, expected) - - def test_rule_macro_mix(self): - src = textwrap.dedent("""\ - def _impl(ctx): - return struct() - - example_rule = rule( - implementation = _impl, - attrs = { - "arg_label": attr.label(), - "arg_string": attr.string(), - }, - ) - \"\"\"An example rule. - - Args: - name: A unique name for this rule. - arg_label: A label argument. - arg_string: A string argument. - \"\"\" - - def example_macro(name, foo, visibility=None): - \"\"\"An example macro. - - Args: - name: A unique name for this rule. - foo: A test argument. - visibility: The visibility of this rule. - \"\"\" - native.genrule( - name = name, - out = ["foo"], - cmd = "touch $@", - visibility = visibility, - ) - """) - - expected = textwrap.dedent("""\ - rule { - name: "example_rule" - documentation: "An example rule." - attribute { - name: "name" - type: UNKNOWN - mandatory: true - documentation: "A unique name for this rule." - } - attribute { - name: "arg_label" - type: LABEL - mandatory: false - documentation: "A label argument." - } - attribute { - name: "arg_string" - type: STRING - mandatory: false - documentation: "A string argument." - default: "''" - } - type: RULE - } - """) - - self.check_protos(src, expected) - - def test_rule_with_example_doc(self): - src = textwrap.dedent("""\ - def _impl(ctx): - return struct() - - rule_with_example = rule( - implementation = _impl, - attrs = { - "arg_label": attr.label(), - "arg_string": attr.string(), - }, - ) - \"\"\"Rule with example. - - Example: - Here is an example of how to use this rule. - - Args: - name: A unique name for this rule. - arg_label: A label argument. - arg_string: A string argument. - \"\"\" - """) - - expected = textwrap.dedent("""\ - rule { - name: "rule_with_example" - documentation: "Rule with example." - example_documentation: "Here is an example of how to use this rule." - attribute { - name: "name" - type: UNKNOWN - mandatory: true - documentation: "A unique name for this rule." - } - attribute { - name: "arg_label" - type: LABEL - mandatory: false - documentation: "A label argument." - } - attribute { - name: "arg_string" - type: STRING - mandatory: false - documentation: "A string argument." - default: "''" - } - type: RULE - } - """) - - self.check_protos(src, expected) - - def test_rule_with_output_doc(self): - src = textwrap.dedent("""\ - def _impl(ctx): - return struct() - - rule_with_outputs = rule( - implementation = _impl, - attrs = { - "arg_label": attr.label(), - "arg_string": attr.string(), - }, - outputs = { - "jar": "%{name}.jar", - "deploy_jar": "%{name}_deploy.jar", - }, - ) - \"\"\"Rule with output documentation. - - Outputs: - jar: A Java archive. - deploy_jar: A Java archive suitable for deployment. - - Only built if explicitly requested. - - Args: - name: A unique name for this rule. - arg_label: A label argument. - arg_string: A string argument. - \"\"\" - """) - - expected = textwrap.dedent("""\ - rule { - name: "rule_with_outputs" - documentation: "Rule with output documentation." - attribute { - name: "name" - type: UNKNOWN - mandatory: true - documentation: "A unique name for this rule." - } - attribute { - name: "arg_label" - type: LABEL - mandatory: false - documentation: "A label argument." - } - attribute { - name: "arg_string" - type: STRING - mandatory: false - documentation: "A string argument." - default: "''" - } - output { - template: "%{name}.jar" - documentation: "A Java archive." - } - output { - template: "%{name}_deploy.jar" - documentation: "A Java archive suitable for deployment.\\n\\nOnly built if explicitly requested." - } - type: RULE - } - """) - - self.check_protos(src, expected) - - def test_loads(self): - src = textwrap.dedent("""\ - load("//foo/bar:bar.bzl", "foo_library") - load("//foo/bar:baz.bzl", "foo_test", orig_foo_binary = "foo_binary") - - _references_foo_library = foo_library - _references_orig_foo_binary = orig_foo_binary - """) - load_symbols = [ - load_extractor.LoadSymbol('//foo/bar:bar.bzl', 'foo_library', None), - load_extractor.LoadSymbol('//foo/bar:baz.bzl', 'foo_test', None), - load_extractor.LoadSymbol('//foo/bar:baz.bzl', 'foo_binary', - 'orig_foo_binary'), - ] - expected = "" - self.check_protos(src, expected, load_symbols) - - def test_repository_rule(self): - src = textwrap.dedent("""\ - def _impl(repository_ctx): - return struct() - - repo_rule = repository_rule( - implementation = _impl, - local = True, - attrs = { - "path": attr.string(mandatory=True) - }, - ) - \"\"\"A repository rule. - - Args: - name: A unique name for this rule. - path: The path of the external dependency. - \"\"\" - """) - - expected = textwrap.dedent("""\ - rule { - name: "repo_rule" - documentation: "A repository rule." - attribute { - name: "name" - type: UNKNOWN - mandatory: true - documentation: "A unique name for this rule." - } - attribute { - name: "path" - type: STRING - mandatory: true - documentation: "The path of the external dependency." - default: "\'\'" - } - type: REPOSITORY_RULE - } - """) - - self.check_protos(src, expected) - - def test_doc_arg(self): - src = textwrap.dedent("""\ - def _impl(ctx): - return struct() - - rule_with_doc = rule( - implementation = _impl, - attrs = { - "foo": attr.string(doc = "Attribute documentation.") - }, - ) - \"\"\"A rule. - \"\"\" - """) - - expected = textwrap.dedent("""\ - rule { - name: "rule_with_doc" - documentation: "A rule." - attribute { - name: "name" - type: UNKNOWN - mandatory: true - } - attribute { - name: "foo" - type: STRING - mandatory: false - documentation: "Attribute documentation." - default: "\'\'" - } - type: RULE - } - """) - - self.check_protos(src, expected) - -if __name__ == '__main__': - unittest.main()
diff --git a/skydoc/sass/BUILD b/skydoc/sass/BUILD deleted file mode 100644 index fa0cbed..0000000 --- a/skydoc/sass/BUILD +++ /dev/null
@@ -1,10 +0,0 @@ -licenses(["notice"]) # Apache 2.0 - -package(default_visibility = ["//skydoc:__pkg__"]) - -load("@io_bazel_rules_sass//sass:sass.bzl", "sass_binary") - -sass_binary( - name = "main", - src = "main.scss", -)
diff --git a/skydoc/sass/main.scss b/skydoc/sass/main.scss deleted file mode 100644 index 5b3ecf2..0000000 --- a/skydoc/sass/main.scss +++ /dev/null
@@ -1,258 +0,0 @@ -// Copyright 2016 The Bazel Authors. 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. - -$primary-color: #4caf50; - -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; - - 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-title { - border-bottom: 1px solid #e0e0e0; - padding-left: 24px; - } -} - -.drawer-nav { - ul { - list-style: none; - padding-left: 0; - - li { - display: block; - padding: 0; - - ul { - li { - a { - padding-left: 44px; - font-weight: 400; - } - } - } - - 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; - - &:active, - &:hover { - background-color: #f0f0f0; - } - } - - &.active { - a { - color: $primary-color; - font-weight: 500; - } - } - } - } -} - -h1.page-title { - font-size: 34px; - font-weight: 400; - line-height: 40px; - margin-bottom: 30px; - color: $primary-color; -} - -p.lead { - font-size: 20px; - line-height: 32px; -} - -table { - border-collapse: collapse; - border-spacing: 0; - background-color: #fff; - table-layout: auto; - - thead { - th { - background-color: #fafafa; - border: 1px solid #eee; - color: #757575; - padding: 12px 12px 12px 24px; - vertical-align: top; - } - } - - tbody { - td { - border: 1px solid #eee; - padding: 12px 12px 12px 24px; - vertical-align: top; - } - } -} - -table.params-table { - width: 100%; - - col.col-param { - width: 25%; - } - - col.col-description { - width: 75%; - } -} - -table.overview-table { - width: 100%; - - col.col-name { - width: 25%; - } - - col.col-description { - width: 75%; - } - - td { - p { - margin: 0; - } - } -} - -hr { - margin-top: 40px; - margin-bottom: 40px; -} - -nav.toc { - border-left: 5px solid $primary-color; - padding-left: 20px; - margin-bottom: 48px; - - h1, - h2 { - font-size: 15px; - line-height: 16px; - padding-bottom: 12px; - margin-bottom: 0; - font-weight: 400; - color: #757575; - } - - ul { - list-style: none; - margin-top: 0; - padding-left: 0; - - li { - font-size: 20px; - line-height: 40px; - - a { - color: $primary-color; - } - } - } -} - -.page-content { - margin-left: auto; - margin-right: auto; - padding-top: 60px; - padding-bottom: 60px; - width: 760px; - - a { - text-decoration: none; - } - - h1 { - font-size: 34px; - font-weight: 400; - line-height: 40px; - margin-bottom: 30px; - color: $primary-color; - } - - h2 { - font-size: 24px; - font-weight: 400; - line-height: 32px; - margin-bottom: 30px; - color: $primary-color; - } - - h3 { - font-size: 20px; - font-weight: 400; - line-height: 32px; - margin-bottom: 30px; - color: $primary-color; - } -} - -@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; -}
diff --git a/skydoc/stubs/BUILD b/skydoc/stubs/BUILD deleted file mode 100644 index 485b149..0000000 --- a/skydoc/stubs/BUILD +++ /dev/null
@@ -1,16 +0,0 @@ -licenses(["notice"]) # Apache 2.0 - -package(default_visibility = ["//skydoc:__pkg__"]) - -load("@rules_python//python:defs.bzl", "py_library") - -py_library( - name = "stubs", - srcs = [ - "attr.py", - "skylark_globals.py", - ], - deps = [ - "//skydoc:build_pb_py", - ], -)
diff --git a/skydoc/stubs/attr.py b/skydoc/stubs/attr.py deleted file mode 100644 index 8b8c10d..0000000 --- a/skydoc/stubs/attr.py +++ /dev/null
@@ -1,187 +0,0 @@ -# Copyright 2016 The Bazel Authors. 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. - -# internal imports -from skydoc import build_pb2 - - -def strcmp(s1, s2): - if s1 > s2: - return 1 - elif s1 < s2: - return -1 - else: - return 0 - - -def attr_compare(a, b): - if a.compare_priority() > b.compare_priority(): - return 1 - elif a.compare_priority() < b.compare_priority(): - return -1 - else: - return strcmp(a.name, b.name) - - -class AttrDescriptor(object): - ATTRIBUTE_ORDERING = { - "name": -99, - "deps": -98, - "src": -97, - "srcs": -86, - "data": -95, - "resource": -94, - "resources": -93, - "out": -92, - "outs": -91, - "hdrs": -90, - } - - def __init__(self, - type=build_pb2.Attribute.UNKNOWN, - default=None, - mandatory=False, - doc="", - name=""): - """Constructor for AttrDescriptor - - Args: - self: The current instance - type: The type of attribute based on the enum in the Attribute proto. - default: The default value of the attribute. - mandatory: True if the attribute is required, false if optional. - doc: Documentation for this attribute. This parameter is used internally - by skydoc and is not set by any Skylark code in .bzl files. - name: Name of this attribute. This parameter is used internally by skydoc - and is not set by any Skylark code in .bzl files. - """ - self.type = type - self.default = default - self.mandatory = mandatory - self.doc = doc - self.name = name - - def compare_priority(self): - if self.name in AttrDescriptor.ATTRIBUTE_ORDERING: - return AttrDescriptor.ATTRIBUTE_ORDERING[self.name] - else: - return 0 - - -def bool(default=False, mandatory=False, doc=""): - return AttrDescriptor( - build_pb2.Attribute.BOOLEAN, default=repr(default), mandatory=mandatory, doc=doc) - - -def int(default=0, mandatory=False, values=[], doc=""): - return AttrDescriptor(build_pb2.Attribute.INTEGER, repr(default), mandatory, doc=doc) - - -def int_list(default=[], mandatory=False, non_empty=False, allow_empty=True, doc=""): - return AttrDescriptor(build_pb2.Attribute.INTEGER_LIST, repr(default), - mandatory, doc) - - -def label(default=None, - executable=False, - allow_files=False, - allow_single_file=False, - mandatory=False, - providers=[], - allow_rules=None, - single_file=False, - cfg=None, - aspects=[], - doc=""): - if default != None: - default = repr(default) - return AttrDescriptor(build_pb2.Attribute.LABEL, default, mandatory, doc) - - -def label_list(default=[], - allow_files=False, - allow_rules=None, - providers=[], - flags=[], - mandatory=False, - non_empty=False, - allow_empty=True, - cfg=None, - aspects=[], - doc=""): - default_val = [] - for label in default: - default_val.append(repr(label)) - return AttrDescriptor(build_pb2.Attribute.LABEL_LIST, repr(default_val), - mandatory, doc) - - -def license(default=None, mandatory=False, doc=""): - if default != None: - default = repr(default) - return AttrDescriptor(build_pb2.Attribute.LICENSE, default, mandatory, doc) - - -def output(default=None, mandatory=False, doc=""): - if default != None: - default = repr(default) - return AttrDescriptor(build_pb2.Attribute.OUTPUT, default, mandatory, doc) - - -def output_list(default=[], mandatory=False, non_empty=False, allow_empty=True, doc=""): - default_val = [] - for label in default: - default_val.append(repr(label)) - return AttrDescriptor(build_pb2.Attribute.OUTPUT_LIST, repr(default_val), - mandatory, doc) - - -def string(default="", mandatory=False, values=[], doc=""): - return AttrDescriptor(build_pb2.Attribute.STRING, repr(default), mandatory, doc) - - -def string_dict(default={}, - mandatory=False, - non_empty=False, - allow_empty=True, - doc=""): - return AttrDescriptor(build_pb2.Attribute.STRING_DICT, repr(default), - mandatory, doc) - - -def string_list(default=[], - mandatory=False, - non_empty=False, - allow_empty=True, - doc=""): - return AttrDescriptor(build_pb2.Attribute.STRING_LIST, repr(default), - mandatory, doc) - - -def string_list_dict(default={}, - mandatory=False, - non_empty=False, - allow_empty=True, - doc=""): - return AttrDescriptor(build_pb2.Attribute.STRING_LIST_DICT, repr(default), - mandatory, doc) - -def label_keyed_string_dict(default={}, - mandatory=False, - allow_files=False, - non_empty=False, - allow_empty=True, - doc=""): - return AttrDescriptor(build_pb2.Attribute.LABEL_KEYED_STRING_DICT, repr(default), - mandatory, doc)
diff --git a/skydoc/stubs/skylark_globals.py b/skydoc/stubs/skylark_globals.py deleted file mode 100644 index 021cd95..0000000 --- a/skydoc/stubs/skylark_globals.py +++ /dev/null
@@ -1,109 +0,0 @@ -# Copyright 2016 The Bazel Authors. 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. - -"""Stubs for Skylark globals""" - -import collections - - -def FileType(filetypes=[]): - return filetypes - -HOST_CFG = 'HOST_CFG' -DATA_CFG = 'DATA_CFG' -PACKAGE_NAME = 'PACKAGE_NAME' -REPOSITORY_NAME = 'REPOSITORY_NAME' - -native = '' - -def aspect(implementation, attr_aspects=[], attrs=None, fragments=[], - host_fragments=[], toolchains=[]): - return None - -def provider(doc='', fields=None): - return None - -def select(x): - return None - -def struct(**kwargs): - return None - -def load(label, *args, **kwargs): - return None - -class Label(object): - def __init__(self, label_string, relative_to_caller_repository=False): - self.label_string = label_string - self.relative_to_caller_repository = relative_to_caller_repository - - def __repr__(self): - return self.label_string - -class RuleDescriptor(object): - def __init__(self, implementation, test=False, attrs={}, outputs={}, - executable=False, output_to_genfiles=False, fragments=[], - host_fragments=[], local=False, doc='', type='rule', toolchains=[]): - """Constructor for RuleDescriptor - - Args: - self: The current instance. - implementation: The implementation function for the rule (not used). - test: Whether this is a test rule - attrs: Dictionary mapping attribute name to attribute descriptor - outputs: Outputs for this rule as a mapping from string to template name. - The dictionary keys are used to refer to the output in the docstring - documentation. - executable: Whether this rule produces an executable. - output_to_genfiles: Whether the rule generates files in the genfiles - directory rather than the bin directory (not used). - fragments: List of names of configuration fragments the rule requires in - the target configuration (not used). - host_fragments: List of names of configuration fragments that the rule - requires in the host configuration (not used). - local: Indicates that the rule fetches everything from the local system. - (Only used if type='repository'). - doc: Documentation for this rule. This parameter is used internally by - skydoc and is not set by any Skylark code in .bzl files. - example_doc: Example documentation for this rule. This parameter is used - internally by skydoc and is not set by any Skylark code in .bzl files. - type: The type of rule (rule, repository_rule). This parameter is used - by skydoc and is not set by any Skylark code in .bzl files. - """ - self.implementation = implementation - self.test = test - self.attrs = attrs - self.outputs = outputs - self.executable = executable - self.output_to_genfiles = output_to_genfiles - self.fragments = fragments - self.host_fragments = host_fragments - self.local = local - self.doc = doc - self.example_doc = '' - self.outputs = outputs - self.output_docs = collections.OrderedDict() if hasattr(collections, 'OrderedDict') else {} - self.type = type - for name, attr in self.attrs.items(): - attr.name = name - -def rule(implementation, test=False, attrs={}, outputs=None, - executable=False, output_to_genfiles=False, fragments=[], - host_fragments=[], toolchains=[]): - return RuleDescriptor(implementation, test, attrs, outputs, executable, - output_to_genfiles, fragments, host_fragments, toolchains) - -def repository_rule(implementation, attrs={}, local=False, environ=[]): - return RuleDescriptor(implementation, attrs=attrs, local=local, - type='repository')
diff --git a/skydoc/templates/BUILD b/skydoc/templates/BUILD deleted file mode 100644 index ade6211..0000000 --- a/skydoc/templates/BUILD +++ /dev/null
@@ -1,20 +0,0 @@ -licenses(["notice"]) # Apache 2.0 - -package(default_visibility = ["//skydoc:__pkg__"]) - -filegroup( - name = "templates", - srcs = [ - "attributes.jinja", - "html.jinja", - "html_footer.jinja", - "html_header.jinja", - "html_overview.jinja", - "markdown.jinja", - "markdown_overview.jinja", - "nav.jinja", - "outputs.jinja", - "overview.jinja", - "toc.jinja", - ], -)
diff --git a/skydoc/templates/attributes.jinja b/skydoc/templates/attributes.jinja deleted file mode 100644 index 6d58577..0000000 --- a/skydoc/templates/attributes.jinja +++ /dev/null
@@ -1,32 +0,0 @@ -{# -Copyright 2016 The Bazel Authors. 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. -#} -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> -% for attribute in rule.attributes: - <tr id="{{ rule.name }}.{{ attribute.name }}"> - <td><code>{{ attribute.name }}</code></td> - <td> - <p><code>{{ attribute.type }}</code></p> - {{ attribute.documentation|markdown|trim }} - </td> - </tr> -% endfor - </tbody> -</table>
diff --git a/skydoc/templates/html.jinja b/skydoc/templates/html.jinja deleted file mode 100644 index 15d9fa9..0000000 --- a/skydoc/templates/html.jinja +++ /dev/null
@@ -1,53 +0,0 @@ -{# -Copyright 2016 The Bazel Authors. 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. -#} -% include "html_header.jinja" - - <h1>{{ ruleset.title }}</h1> -% include "toc.jinja" -% if ruleset.description: - <hr> - <h2 id="overview">Overview</h2> - {{ ruleset.description|markdown }} -% endif -% for rule in ruleset.definitions - <hr> - - <h2 id="{{ rule.name }}">{{ rule.name }}</h2> - - <pre>{{ rule.signature }}</pre> - - {{ rule.documentation|markdown }} - -% if rule.outputs[0] is defined: - <h3 id="{{ rule.name }}_outputs"> - Outputs - </h3> -% include "outputs.jinja" -% endif - -% if rule.attributes[0] is defined: - <h3 id="{{ rule.name }}_args">Attributes</h3> -% include "attributes.jinja" -% endif - -% if rule.example_documentation - <h3 id="{{ rule.name }}_examples">Examples</h3> - {{ rule.example_documentation|markdown }} -% endif - -% endfor - -% include "html_footer.jinja"
diff --git a/skydoc/templates/html_footer.jinja b/skydoc/templates/html_footer.jinja deleted file mode 100644 index 82987da..0000000 --- a/skydoc/templates/html_footer.jinja +++ /dev/null
@@ -1,31 +0,0 @@ -{# -Copyright 2016 The Bazel Authors. 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. -#} - - </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="https://bazel.build">Home</a></li> - <li><a href="https://github.com/bazelbuild">GitHub</a></li> - </ul> - </div> - </footer> - </main> - </div> - </body> -</html>
diff --git a/skydoc/templates/html_header.jinja b/skydoc/templates/html_header.jinja deleted file mode 100644 index 135bdc6..0000000 --- a/skydoc/templates/html_header.jinja +++ /dev/null
@@ -1,52 +0,0 @@ -{# -Copyright 2016 The Bazel Authors. 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. -#} -<!-- -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>{{ title }}</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="{{ 'main.css' | link }}"> - </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">{{ title }}</span> - </div> - </header> - <div class="mdl-layout__drawer"> - <span class="mdl-layout-title">Bazel</span> - <nav class="drawer-nav"> - <ul class="drawer-nav"> - {{ nav }} - </ul> - </nav> - </div> - - <main class="mdl-layout__content"> - <div class="page-content">
diff --git a/skydoc/templates/html_overview.jinja b/skydoc/templates/html_overview.jinja deleted file mode 100644 index 7abdcfd..0000000 --- a/skydoc/templates/html_overview.jinja +++ /dev/null
@@ -1,22 +0,0 @@ -{# -Copyright 2016 The Bazel Authors. 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. -#} -% include "html_header.jinja" - -<h1>Overview</h1> - -% include "overview.jinja" - -% include "html_footer.jinja"
diff --git a/skydoc/templates/markdown.jinja b/skydoc/templates/markdown.jinja deleted file mode 100644 index 5545bc0..0000000 --- a/skydoc/templates/markdown.jinja +++ /dev/null
@@ -1,67 +0,0 @@ -{# -Copyright 2016 The Bazel Authors. 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. -#} -<!--- -Documentation generated by Skydoc ---> -<h1>{{ ruleset.title }}</h1> - -% include "toc.jinja" - -% if ruleset.description: -<hr> - -<a name="overview"></a> -## Overview - -{{ ruleset.description }} -{# I want a blank line here #} -% endif - -% for rule in ruleset.definitions: -<a name="{{ rule.name }}"></a> -## {{ rule.name }} - -<pre> -{{ rule.signature }} -</pre> - -{{ rule.documentation }} - -% if rule.outputs[0] is defined: -{# I want a blank line here #} -<a name="{{ rule.name }}_outputs"></a> -### Outputs - -% include "outputs.jinja" -% endif - -% if rule.attributes[0] is defined: -{# I want a blank line here #} -<a name="{{ rule.name }}_args"></a> -### Attributes - -% include "attributes.jinja" -% endif - -% if rule.example_documentation -{# I want a blank line here #} -<a name="{{ rule.name }}_examples"></a> -### Examples - -{{ rule.example_documentation }} -% endif - -% endfor
diff --git a/skydoc/templates/markdown_overview.jinja b/skydoc/templates/markdown_overview.jinja deleted file mode 100644 index f810a7e..0000000 --- a/skydoc/templates/markdown_overview.jinja +++ /dev/null
@@ -1,18 +0,0 @@ -{# -Copyright 2016 The Bazel Authors. 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. -#} -# Overview - -% include "overview.jinja"
diff --git a/skydoc/templates/nav.jinja b/skydoc/templates/nav.jinja deleted file mode 100644 index 9fc5447..0000000 --- a/skydoc/templates/nav.jinja +++ /dev/null
@@ -1,35 +0,0 @@ -{# -Copyright 2016 The Bazel Authors. 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. -#} -% if overview: -<li><a href="{{ overview_filename | doc_link }}">Overview</a></li> -% endif -% for ruleset in rulesets: -<li> - <a href="{{ ruleset.output_file | doc_link }}">{{ ruleset.title }}</a> - <ul> -% if ruleset.description: - <li><a href="{{ ruleset.output_file | doc_link }}#overview">Overview</a></li> -% endif -% for rule in ruleset.rules: - <li> - <a href="{{ ruleset.output_file | doc_link }}#{{ rule.name }}"> - {{ rule.name }} - </a> - </li> -% endfor - </ul> -</li> -% endfor
diff --git a/skydoc/templates/outputs.jinja b/skydoc/templates/outputs.jinja deleted file mode 100644 index 68a3c19..0000000 --- a/skydoc/templates/outputs.jinja +++ /dev/null
@@ -1,31 +0,0 @@ -{# -Copyright 2016 The Bazel Authors. 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. -#} -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> -% for output in rule.outputs: - <tr> - <td><code>{{ output.template }}</code></td> - <td> - {{ output.documentation|markdown|trim }} - </td> - </tr> -% endfor - </tbody> -</table>
diff --git a/skydoc/templates/overview.jinja b/skydoc/templates/overview.jinja deleted file mode 100644 index 81a469e..0000000 --- a/skydoc/templates/overview.jinja +++ /dev/null
@@ -1,100 +0,0 @@ -{# -Copyright 2016 The Bazel Authors. 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. -#} -<nav class="toc"> - <h2>Rule sets</h2> - <ul> -% for ruleset in rulesets: - <li><a href="#{{ ruleset.name }}">{{ ruleset.title }}</a></li> -% endfor - </ul> -</nav> - -% for ruleset in rulesets: -<h2><a href="{{ ruleset.output_file | doc_link }}" id="{{ ruleset.name }}">{{ ruleset.title }}</a></h2> - -% if ruleset.rules[0] is defined: -<h3>Rules</h3> -<table class="overview-table"> - <colgroup> - <col class="col-name" /> - <col class="col-description" /> - </colgroup> - <tbody> -% for rule in ruleset.rules: - <tr> - <td> - <a href="{{ ruleset.output_file | doc_link }}#{{ rule.name }}"> - <code>{{ rule.name }}</code> - </a> - </td> - <td> - {{ rule.short_documentation | markdown }} - </td> - </tr> -% endfor - </tbody> -</table> -% endif - -% if ruleset.macros[0] is defined: -<h3>Macros</h3> -<table class="overview-table"> - <colgroup> - <col class="col-name" /> - <col class="col-description" /> - </colgroup> - <tbody> -% for rule in ruleset.macros: - <tr> - <td> - <a href="{{ ruleset.output_file | doc_link }}#{{ rule.name }}"> - <code>{{ rule.name }}</code> - </a> - </td> - <td> - {{ rule.short_documentation | markdown }} - </td> - </tr> -% endfor - </tbody> -</table> -% endif - -% if ruleset.repository_rules[0] is defined: -<h3>Repository Rules</h3> -<table class="overview-table"> - <colgroup> - <col class="col-name" /> - <col class="col-description" /> - </colgroup> - <tbody> -% for rule in ruleset.repository_rules: - <tr> - <td> - <a href="{{ ruleset.output_file | doc_link }}#{{ rule.name }}"> - <code>{{ rule.name }}</code> - </a> - </td> - <td> - {{ rule.short_documentation | markdown }} - </td> - </tr> -% endfor - </tbody> -</table> -% endif - -% endfor
diff --git a/skydoc/templates/toc.jinja b/skydoc/templates/toc.jinja deleted file mode 100644 index f6642af..0000000 --- a/skydoc/templates/toc.jinja +++ /dev/null
@@ -1,44 +0,0 @@ -{# -Copyright 2016 The Bazel Authors. 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. -#} -<nav class="toc"> -% if ruleset.description: - <h2><a href="#overview">Overview</a></h2> -% endif -% if ruleset.repository_rules[0] is defined: - <h2>Repository Rules</h2> - <ul> -% for rule in ruleset.repository_rules: - <li><a href="#{{ rule.name }}">{{ rule.name }}</a></li> -% endfor - </ul> -% endif -% if ruleset.rules[0] is defined: - <h2>Rules</h2> - <ul> -% for rule in ruleset.rules: - <li><a href="#{{ rule.name }}">{{ rule.name }}</a></li> -% endfor - </ul> -% endif -% if ruleset.macros[0] is defined: - <h2>Macros</h2> - <ul> -% for macro in ruleset.macros: - <li><a href="#{{ macro.name }}">{{ macro.name }}</a></li> -% endfor - </ul> -% endif -</nav>
diff --git a/skylark/BUILD b/skylark/BUILD deleted file mode 100644 index 29e4dbf..0000000 --- a/skylark/BUILD +++ /dev/null
@@ -1,22 +0,0 @@ -licenses(["notice"]) # Apache 2.0 - -package(default_visibility = ["//visibility:public"]) - -load("@bazel_skylib//:bzl_library.bzl", "bzl_library") -load("//skylark:skylark.bzl", "skylark_doc") - -bzl_library( - name = "skylark", - srcs = ["skylark.bzl"], - deps = [ - "@bazel_skylib//:bzl_library", - ], -) - -skylark_doc( - name = "skylark-docs", - srcs = ["skylark.bzl"], - overview = False, - strip_prefix = "skylark", - deps = [":skylark"], -)
diff --git a/skylark/skylark.bzl b/skylark/skylark.bzl deleted file mode 100644 index fd7a697..0000000 --- a/skylark/skylark.bzl +++ /dev/null
@@ -1,172 +0,0 @@ -# Copyright 2016 The Bazel Authors. 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. - -"""Skylark rules""" - -load("@bazel_skylib//:bzl_library.bzl", "StarlarkLibraryInfo") - -_SKYLARK_FILETYPE = [".bzl"] - -ZIP_PATH = "/usr/bin/zip" - -def _skydoc(ctx): - for f in ctx.files.skydoc: - if not f.path.endswith(".py"): - return f - fail("no valid .py file") - -def _skylark_doc_impl(ctx): - """Implementation of the skylark_doc rule.""" - skylark_doc_zip = ctx.outputs.skylark_doc_zip - direct = [] - transitive = [] - skydoc = _skydoc(ctx) - for dep in ctx.attr.srcs: - if StarlarkLibraryInfo in dep: - direct.extend(dep[StarlarkLibraryInfo].srcs) - transitive.append(dep[StarlarkLibraryInfo].transitive_srcs) - else: - direct.extend(dep.files.to_list()) - inputs = depset(order = "postorder", direct = direct, transitive = transitive + [ - dep[StarlarkLibraryInfo].transitive_srcs - for dep in ctx.attr.deps - ]) - sources = [source.path for source in direct] - flags = [ - "--format=%s" % ctx.attr.format, - "--output_file=%s" % ctx.outputs.skylark_doc_zip.path, - ] - if ctx.attr.strip_prefix: - flags += ["--strip_prefix=%s" % ctx.attr.strip_prefix] - if ctx.attr.overview: - flags += ["--overview"] - if ctx.attr.overview_filename: - flags += ["--overview_filename=%s" % ctx.attr.overview_filename] - if ctx.attr.link_ext: - flags += ["--link_ext=%s" % ctx.attr.link_ext] - if ctx.attr.site_root: - flags += ["--site_root=%s" % ctx.attr.site_root] - ctx.actions.run( - inputs = inputs, - tools = [skydoc], - executable = skydoc, - arguments = flags + sources, - outputs = [skylark_doc_zip], - mnemonic = "Skydoc", - use_default_shell_env = True, - progress_message = ("Generating Skylark doc for %s (%d files)" % - (ctx.label.name, len(sources))), - ) - -skylark_doc = rule( - _skylark_doc_impl, - attrs = { - "srcs": attr.label_list( - providers = [StarlarkLibraryInfo], - allow_files = _SKYLARK_FILETYPE, - ), - "deps": attr.label_list( - providers = [StarlarkLibraryInfo], - allow_files = False, - ), - "format": attr.string(default = "markdown"), - "strip_prefix": attr.string(), - "overview": attr.bool(default = True), - "overview_filename": attr.string(), - "link_ext": attr.string(), - "site_root": attr.string(), - "skydoc": attr.label( - default = Label("//skydoc"), - cfg = "host", - executable = True, - ), - }, - outputs = { - "skylark_doc_zip": "%{name}-skydoc.zip", - }, -) -# buildozer: disable=no-effect -"""Generates Skylark rule documentation. - -Documentation is generated in directories that follows the package structure -of the input `.bzl` files. For example, suppose the set of input files are -as follows: - -* `foo/foo.bzl` -* `foo/bar/bar.bzl` - -The archive generated by `skylark_doc` will contain the following generated -docs: - -* `foo/foo.html` -* `foo/bar/bar.html` - -Args: - srcs: List of `.bzl` files that are processed to create this target. - deps: List of other `skylark_library` targets that are required by the Skylark - files listed in `srcs`. - format: The type of output to generate. Possible values are `"markdown"` and - `"html"`. - strip_prefix: The directory prefix to strip from the generated output files. - - The directory prefix to strip must be common to all input files. Otherwise, - skydoc will raise an error. - overview: If set to `True`, then generate an overview page. - overview_filename: The file name to use for the overview page. By default, - the page is named `index.md` or `index.html` for Markdown and HTML output - respectively. - link_ext: The file extension used for links in the generated documentation. - By default, skydoc uses `.html`. - site_root: The site root to be prepended to all URLs in the generated - documentation, such as links, style sheets, and images. - - This is useful if the generated documentation is served from a subdirectory - on the web server. For example, if the skydoc site is to served from - `https://host.com/rules`, then by setting - `site_root = "https://host.com/rules"`, all links will be prefixed with - the site root, for example, `https://host.com/rules/index.html`. - -Outputs: - skylark_doc_zip: A zip file containing the generated documentation. - -Example: - Suppose you have a project containing Skylark rules you want to document: - - ``` - [workspace]/ - WORKSPACE - checkstyle/ - BUILD - checkstyle.bzl - ``` - - To generate documentation for the rules and macros in `checkstyle.bzl`, add the - following target to `rules/BUILD`: - - ```python - load("@io_bazel_skydoc//skylark:skylark.bzl", "skylark_doc") - - skylark_doc( - name = "checkstyle-docs", - srcs = ["checkstyle.bzl"], - ) - ``` - - Running `bazel build //checkstyle:checkstyle-docs` will generate a zip file - containing documentation for the public rules and macros in `checkstyle.bzl`. - - By default, Skydoc will generate documentation in Markdown. To generate - a set of HTML pages that is ready to be served, set `format = "html"`. -""" -
