bazelbuild/skydoc

Documentation generator for Skylark

Skydoc - Skydoc Documentation Generator

Skydoc is a heavily deprecated Python tool to generate documentation for Bazel build rules written in Starlark.

This repository is no longer maintained.

Please use Stardoc instead, which now resides under bazelbuild/stardoc.

For details on the deprecation: Skydoc Deprecation

skydoc's Issues

Support documenting Implicit Output Targets

Add support for documenting Implicit Output Targets. Some of examples of this in existing documentation:

• java_binary
• sass_binary

toolchain attribute on rules cause Skydoc to fall over.

I am adding toolchains to rules_kotlin and skydoc considers not recognising the toolchain attribute on a rule() a terminal condition -- there isn't a work around for this for #71 we can simply not use new rule modelling features.

In general skydoc needs a bit of work to be suitable for large rule repos. Is such work planned or am I better of switching to RST ?

skydoc crashes when parsing provider() calls

I've got several providers defined, like so:

MyAppInfo = provider()
MyOptionalInfo = provider()

When I try to run skydoc against the file containing those providers, I get the following error (full stack trace:

provider() takes exactly 2 arguments (0 given)

I then try to add the doc and fields arguments to provider(), like so:

MyAppInfo = provider(doc="foo", fields={"bar": "baz"})
MyOptionalInfo = provider(doc="qux", fields={"quux": "quuz"})

But doing so just causes skydoc to crash with a different error (full stack trace:

TypeError: provider() got an unexpected keyword argument 'doc'

TypeError: label_list() got an unexpected keyword argument 'doc'

I'm trying to add skydoc on my rules, but it fails with this "got an unexpected keyword argument 'doc'". In fact, I can reproduce with any other existing repository

bazel release 0.18.0
Python 2.7.13 (default, Nov 24 2017, 17:33:09)
[GCC 6.3.0 20170516] on linux2

Steps:

git clone https://github.com/georgeliaw/rules_wheel.git
cd rules_wheel
bazel build //:wheel-docs

WORKSPACE

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 = "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()

Ability to pass in custom templates to Stardoc

The output of Stardoc is rather prescriptive and not modifiable. I would like to be able to restructure the generated docs in such a way that looks similar to my already existing documentation.

load_extractor leaks file descriptors

tree = ast.parse(open(bzl_file).read(), bzl_file)

leaks file descriptors and would be better written as

with open(bzl_file) as f:
  tree = ast.parse(f.read(), bzl_file)

/via @fweikert

Unexport skylark_library

Since #64, skydoc's version of skylark_library has been a transparent passthrough to skylib's version. Remove it, and have clients refer to skylib directly.

Please move from native to Skylark rules for external git/http repositories

Bazel is planning to move away from native rules for external repositories to Skylark rules, mainly because bundling every version control system in bazel does not scale. As part of this effort, we plan to submit https://bazel-review.googlesource.com/c/bazel/+/55932 soon, which will cause bazel by default to insist that the skylark versions the git and http rules for external repositories be used. This can be disabled by a flag for at least the next 6 months, but we still would appreciate if you could adopt your repository to use the Skylark versions of those rules soon.

A test run of downstream projects with that flag flip in bazel enabled can be found at https://buildkite.com/bazel/bazel-with-downstream-projects-bazel/builds/286

For more background, see

• the original announcement https://groups.google.com/d/topic/bazel-discuss/dO2MHQLwJF0/discussion
• and the documentation of the incompatible changes https://docs.bazel.build/versions/master/skylark/backward-compatibility.html#remove-native-git-repository

Thanks.

skydoc_library will generate docs for transitive dependencies

Found this while trying to refactor skylib_library into bazelbuild/bazel_skylib for use beyond documentation generation.

_skylark_doc_impl defines sources as the set of transitive dependencies (inputs) vs using ctx.files.srcs to limit generation to just the .bzl files specified at the srcs attribute. You need them as inputs for parsing, but not for generation.

https://github.com/bazelbuild/skydoc/blob/master/skylark/skylark.bzl#L50

attr.label lacks allow_single_file

Bazel added the allow_single_file attribute to attr.label at some point, and the older single_file one is now deprecated. Skydoc breaks on rules using the new form:

Traceback (most recent call last):
  File "/private/var/tmp/_bazel_bstaffin/26abb02a80899f40a981f66c2d82ca06/execroot/ops/bazel-out/host/bin/external/io_bazel_skydoc/skydoc/skydoc.runfiles/com_fitbit_ops/../io_bazel_skydoc/skydoc/main.py", line 245, in <module>
    main(FLAGS(sys.argv))
  File "/private/var/tmp/_bazel_bstaffin/26abb02a80899f40a981f66c2d82ca06/execroot/ops/bazel-out/host/bin/external/io_bazel_skydoc/skydoc/skydoc.runfiles/com_fitbit_ops/../io_bazel_skydoc/skydoc/main.py", line 224, in main
    rule_doc_extractor.parse_bzl(bzl_file)
  File "/private/var/tmp/_bazel_bstaffin/26abb02a80899f40a981f66c2d82ca06/execroot/ops/bazel-out/host/bin/external/io_bazel_skydoc/skydoc/skydoc.runfiles/io_bazel_skydoc/skydoc/rule_extractor.py", line 179, in parse_bzl
    self._process_skylark(bzl_file)
  File "/private/var/tmp/_bazel_bstaffin/26abb02a80899f40a981f66c2d82ca06/execroot/ops/bazel-out/host/bin/external/io_bazel_skydoc/skydoc/skydoc.runfiles/io_bazel_skydoc/skydoc/rule_extractor.py", line 65, in _process_skylark
    exec(compiled) in SKYLARK_STUBS, skylark_locals
  File "tools/build_rules/build_data.bzl", line 41, in <module>
    allow_single_file = True,
TypeError: label() got an unexpected keyword argument 'allow_single_file'

Allow linking/delegating/appending docs of a rule to macro definition when kwarg is used

Hi,
We often have macros which add a few shims on top of existing rules and so use the kwargs pattern. We use it since the macros mostly add our own organizational conventions on top of community rules.
Alternatively we have a macro which constructs a few targets but one of them is primary and so the kwargs is passed to that.

The FR here is to allow us to annotate the macro and link to the rule so that we can reuse that documentation and not duplicate it.
Honestly I'd love this to be also relevant for code completion when it comes for the same reasons but not sure where to add such an issue (cc @laurentlb who'll probably have an answer)

getting started is out of date

https://skydoc.bazel.build/docs/getting_started.html does not refer to the latest version of the repos and bumping them up does not seem to do enough to make the recommended setup work. I think this might be related to moving bazel_skylib to a separate repo but still trying to work out the necessary configuration

There's no way to differentiate between multiple same-named files across your repo.

If a skylark_doc definition contains two targets with the same filename, the resulting zip has a duplicate file and is challenging to extract.

Static code analysis needs to process or fail silently on`attr` parameters which it is unaware of.

The rules bork out on providers=[JavaInfo] or if doc="" is provided (#59). The current design forces the rule writer to design un-idiomatic rule libraries.

If the attributes are documented in the declarations --i.e., if doc="" is provided then the attr doc should not need to be provided in rules.

Please consider prioritising fixes for this -- not being able to set the providers is a big deal, I am actually considering using restructuredtext like the go rules for the Kotlin rules.

Add `licenses()` to `BUILD` files

licenses(["notice"]) # Apache 2.0
https://docs.bazel.build/versions/master/be/functions.html#licenses

Windows Support

I've run into issues with dependencies pulled in by skydoc in several repos I collaborate on, you can see a sample error here.

This being clean on Windows is blocking Windows support on at least google/subpar and bazelbuild/rules_python. To be clear: we can comment this stuff out to uncover other issues, but we cannot enable Windows CI or declare support without this working.

@davidstanke @davidzchen @dslomov FYI.

Support syntax for documenting examples

Add support for documenting examples in the docstrings. For example:

"""An example rule

Example:
  Here is an example of how to use this rule:

  ```python
  example_rule(name = "example")
  ```

Args:
  name: A unique name for this rule
  ...
"""

Use of git repository breaks old TLS implementation

On CircleCI, the ssh implementation doesn't support the newer TLS needed to make GitHub connections work. Therefore installing the skydoc repo causes an error:

ERROR: /home/circleci/.cache/bazel/_bazel_circleci/9ce5c2144ecf75d11717c0aa41e45a8d/external/io_bazel_skydoc/skylark/skylark.bzl:289:3: no such package '@gflags_repo//': Error cloning repository: ssh://[email protected]/google/python-gflags: Algorithm negotiation fail caused by ssh://[email protected]/google/python-gflags: Algorithm negotiation fail caused by Algorithm negotiation fail and referenced by '//external:gflags'

https://circleci.com/gh/bazelbuild/rules_nodejs/462

There is no good reason to ever clone a git repo in a repository rule, as we don't want all the commit history.

"Rule sets" is confusing to users if a repo has one-rule-per-file

I prefer the convention where each file is just the code for one rule (and is named after the rule)

The generated documentation has a header "Rule Sets" which doesn't make sense when each set always contains a single rule.

Unexpected keyword argument 'relative_to_caller_repository'

I'm interested in trying skydoc for github.com/bazelbuild/rules_go. Maybe we can generate part of our README.md from doc comments in our go/def.bzl file.

I imported Skydoc by adding this to WORKSPACE:

# Documentation generation
git_repository(
    name = "io_bazel_rules_sass",
    remote = "https://github.com/bazelbuild/rules_sass.git",
    tag = "0.0.2",
)
load("@io_bazel_rules_sass//sass:sass.bzl", "sass_repositories")
sass_repositories()

git_repository(
    name = "io_bazel_skydoc",
    remote = "https://github.com/bazelbuild/skydoc",
    tag = "0.1.3",
)
load("@io_bazel_skydoc//skylark:skylark.bzl", "skydoc_repositories")
skydoc_repositories()

I added a BUILD file with this:

load("@io_bazel_skydoc//skylark:skylark.bzl", "skylark_doc")

skylark_doc(
    name = "docs",
    srcs = ["def.bzl"],
)

When I run bazel build go:docs, I get the following error:

ERROR: /usr/local/google/home/jayconrod/Code/rules_go/go/BUILD:3:1: Generating Skylark doc for docs (1 files) failed: Process exited with status 1 [sandboxed].
Traceback (most recent call last):
  File "/usr/local/google/home/jayconrod/.cache/bazel/_bazel_jayconrod/05c35472541ec3c4670f66aa89b6cabb/bazel-sandbox/119b7aa7-9ac7-481d-bd96-6aabd55c18c8-0/execroot/rules_go/bazel-out/host/bin/external/io_bazel_skydoc/skydoc/skydoc.runfiles/io_bazel_rules_go/../io_bazel_skydoc/skydoc/main.py", line 330, in <module>
    main(FLAGS(sys.argv))
  File "/usr/local/google/home/jayconrod/.cache/bazel/_bazel_jayconrod/05c35472541ec3c4670f66aa89b6cabb/bazel-sandbox/119b7aa7-9ac7-481d-bd96-6aabd55c18c8-0/execroot/rules_go/bazel-out/host/bin/external/io_bazel_skydoc/skydoc/skydoc.runfiles/io_bazel_rules_go/../io_bazel_skydoc/skydoc/main.py", line 308, in main
    rule_doc_extractor.parse_bzl(bzl_file, load_symbols)
  File "/usr/local/google/home/jayconrod/.cache/bazel/_bazel_jayconrod/05c35472541ec3c4670f66aa89b6cabb/bazel-sandbox/119b7aa7-9ac7-481d-bd96-6aabd55c18c8-0/execroot/rules_go/bazel-out/host/bin/external/io_bazel_skydoc/skydoc/skydoc.runfiles/io_bazel_skydoc/skydoc/rule_extractor.py", line 227, in parse_bzl
    self._process_skylark(bzl_file, load_symbols)
  File "/usr/local/google/home/jayconrod/.cache/bazel/_bazel_jayconrod/05c35472541ec3c4670f66aa89b6cabb/bazel-sandbox/119b7aa7-9ac7-481d-bd96-6aabd55c18c8-0/execroot/rules_go/bazel-out/host/bin/external/io_bazel_skydoc/skydoc/skydoc.runfiles/io_bazel_skydoc/skydoc/rule_extractor.py", line 99, in _process_skylark
    exec(compiled) in global_stubs, skylark_locals
  File "go/def.bzl", line 554, in <module>
    relative_to_caller_repository = True,
TypeError: __init__() got an unexpected keyword argument 'relative_to_caller_repository'
Use --strategy=Skydoc=standalone to disable sandboxing for the failing actions.
blaze: Leaving directory `/usr/local/google/home/jayconrod/.cache/bazel/_bazel_jayconrod/05c35472541ec3c4670f66aa89b6cabb/execroot/rules_go/'
Target //go:docs failed to build
Use --verbose_failures to see the command lines of failed build steps.
____Elapsed time: 1.820s, Critical Path: 0.69s

It looks like Skydoc isn't recognizing the relative_to_caller_repository keyword argument to Label. This is a documented parameter, but probably used infrequently. Maybe it would be better to ignore unknown parameters?

Skydoc depends on protobuf.bzl in bazel_tools

As with bazelbuild/dash#12, this is now broken at HEAD since bazelbuild/bazel commit 285112c9b61ca3782e00ccf6411339da7291a3c3 removed protobuf from bazel_tools.

+cc @damienmg @lberki @kchodorow

Reduce blank lines in generated documentation

Currently, the generated documentation has a lot of blank lines, and the blank lines in the TOC in the generated Markdown causes it not to render correctly. We should switch to using Jinja Line Statements so that the lines with Jinja statements would not be rendered as empty lines.

Do not generate page for .bzl file with no public documentation

Currently, if a .bzl file contains no public rules or macros, we still generate a page for it.

Simplify README.md

Now that the Skydoc website is up and running, we can simplify the README.md file to avoid repeating information.

Support platform_common and ToolchainInfo

Hi!

I'm trying to use skydoc in some rules I'm writing for ReasonML but I'm having trouble with platform_common being undefined.

  File "external/com_github_ostera_rules_reason/reason/private/bs_module.bzl", line 127, in <module>
    providers = [platform_common.ToolchainInfo],
NameError: name 'platform_common' is not defined

From looking around I saw the fix for provider and I think I can add to the rule_extractor.py another stub for platform_common so that I can generate docs.

What do you think? :)

Generated doc pages should have 'edit' link

We should treat the documentation similar to a wiki - if a user finds out-of-date documentation, I want it to be so easy to contribute the fix that they tend to send PRs rather than open issues.

Broken links on getting started page

The links at the bottom of the getting started page under "Next Steps" go to the markdown files instead of the html.

https://skydoc.bazel.build/docs/getting_started.html

better support for new style `provider()`s

skydoc fails to parse both of the following for no clear reason:

foo = provider()

(says it needs 2 params, despite both having default values)

foo = provider(
  doc = 'x', fields = {'y': 'z'}
)

The only form of providers that works at head is if the params are specified and passed as positional arguments, e.g. like

foo = provider('x', {'y': 'z'})

I looked through the skydoc source code and couldn't tell why the provider function was being misunderstood.

New 'doc' arguments throw an error.

I am getting these errors when trying to generate skydoc rules at skydoc release 0.1.3. The rules themselves work fine with bazel 0.5.3 and up.

TypeError: string() got an unexpected keyword argument 'doc'
TypeError: label_list() got an unexpected keyword argument 'doc'

Should I expect these errors to go away in a release in near future, or should I remove all doc arguments from my attributes?

Thank you.

Support load() statements

Skylark sources that load() other Skylark sources is currently not supported, and references to load()ed symbols in the global scope result in errors.

Some possible approaches:

• Evaluate load() statements and create mock definitions of symbols in the global scope. See if we can do this using the stub for load().
• Parse the label and evaluate the file that load() is pointing to.

Eventually, this problem (and other problems caused by incompatibility with Python) will be solved by Skylark-as-a-library.

Issue Tracker link in skydoc.bazel.build side drawer points to Tulsi

I noticed on https://skydoc.bazel.build/docs/getting_started.html that the "Issue Tracker" link in the side drawer points to https://github.com/bazelbuild/tulsi/issues instead of https://github.com/bazelbuild/skydoc/issues

I looked at the code and noticed it has been fixed on master:

skydoc/site/_includes/drawer.html

Line 24 in 1a4c284

<li><a href="https://github.com/bazelbuild/skydoc/issues">Issue tracker</a></li>

This was originally brought up in #27, but I don't think the site has been updated since it was fixed.

Wrong URL of issue tracker in https://skydoc.bazel.io/contributing.html

The "Issue Tracker" link at https://skydoc.bazel.io/contributing.html points Tulsi.

I suspect if it should have been https://github.com/bazelbuild/skydoc/issues.

Flakiness in macro_extractor_test and rule_extractor_test

If the elements in the protos, such as attribute definitions, are parsed into a different ordering, the tests will fail.

Run pylint in CI to keep style consistent

Currently, we do not run pylint in the CI for skydoc, which results in the style diverging from the internal Python style and causing pylint to raise errors when we import changes into the internal repo.

+cc @damienmg @fweikert

Support skylark + operator for dicts

Skylark has the + operator defined for merging dicts, but this currently breaks skydoc:

Traceback (most recent call last):
  File "/private/var/tmp/_bazel_bstaffin/fe5f64f9e55476a949b9dc1d4a94e1b8/execroot/bazel_rules_pex/bazel-out/host/bin/external/io_bazel_skydoc/skydoc/skydoc.runfiles/io_bazel_rules_pex/../io_bazel_skydoc/skydoc/main.py", line 245, in <module>
    main(FLAGS(sys.argv))
  File "/private/var/tmp/_bazel_bstaffin/fe5f64f9e55476a949b9dc1d4a94e1b8/execroot/bazel_rules_pex/bazel-out/host/bin/external/io_bazel_skydoc/skydoc/skydoc.runfiles/io_bazel_rules_pex/../io_bazel_skydoc/skydoc/main.py", line 224, in main
    rule_doc_extractor.parse_bzl(bzl_file)
  File "/private/var/tmp/_bazel_bstaffin/fe5f64f9e55476a949b9dc1d4a94e1b8/execroot/bazel_rules_pex/bazel-out/host/bin/external/io_bazel_skydoc/skydoc/skydoc.runfiles/io_bazel_skydoc/skydoc/rule_extractor.py", line 179, in parse_bzl
    self._process_skylark(bzl_file)
  File "/private/var/tmp/_bazel_bstaffin/fe5f64f9e55476a949b9dc1d4a94e1b8/execroot/bazel_rules_pex/bazel-out/host/bin/external/io_bazel_skydoc/skydoc/skydoc.runfiles/io_bazel_skydoc/skydoc/rule_extractor.py", line 65, in _process_skylark
    exec(compiled) in SKYLARK_STUBS, skylark_locals
  File "pex/pex_rules.bzl", line 249, in <module>
    executable = True,
TypeError: unsupported operand type(s) for +: 'dict' and 'dict'

The bazel docs suggest using dict(a.items() + b.items()) as a workaround, so this isn't disastrous, but it would be nice if it just worked :-)

Tests are failing on ci.bazel.io

See http://ci.bazel.io/job/skydoc/3/

Create skydoc.bazel.io and add push job for Skydoc site

This is a follow-up to #14:

• Set up skydoc.bazel.io.
• Add the Skydoc site to the automated push job for publishing the site.

Damien - feel free to set this up when you get a chance. :)

label_keyed_string_dict attribute type is not supported

The label_keyed_string_dict attribute type for rules was added in Bazel 0.5.0, but isn't supported by skydoc (as of e9be81c). Executing skylark_doc for rules that use that attr.label_keyed_string_dict fail with an error like:

.../io_bazel_skydoc/skydoc/rule_extractor.py", line 99, in _process_skylark
    exec(compiled) in global_stubs, skylark_locals
  File "tools/build_rules/stage.bzl", line 104, in <module>
    "srcs": attr.label_keyed_string_dict(allow_files=True, mandatory=True),
AttributeError: 'module' object has no attribute 'label_keyed_string_dict'

All attribute types should be supported.

Generate overview page

Generating an overview page will be useful, especially for rules projects that generate a set of HTML docs and serve them as the website for the project.

rules_kotlin: Remove usages of FileType and don't fail on toolchains attribute.

After quite a bit of trial and error I've got the docs generating again -- toolchains is the only problem currently (have to comment them out when generating the docs).

Also FileType usages need to be removed.

Add integration tests

We have unit tests for most of the skydoc tool, but we should add integration tests for verifying end-to-end use cases.

Stardoc generates HTML

Stardoc documentation:

        "out": attr.output(
            doc = "The (markdown) file to which documentation will be output.",
            mandatory = True,
        ),

However, the file contains HTML, not markdown.

skydoc code doesn't run under Python 3

To reproduce, use the new --python_path flag to force Python 3:

bazel test --python_path=/usr/bin/python3 //...

Gives an error message shown below:

ERROR: /path/skydoc/skylark/BUILD:5:1: Generating Skylark doc for skylark-docs (1 files) failed (Exit 1).
Traceback (most recent call last):
  File "/longpath/execroot/io_bazel_skydoc/bazel-out/host/bin/skydoc/skydoc.runfiles/io_bazel_skydoc/skydoc/main.py", line 18, in <module>
    import gflags
  File "/longpath/execroot/io_bazel_skydoc/bazel-out/host/bin/skydoc/skydoc.runfiles/gflags_repo/gflags.py", line 1091
    except gflags_validators.Error, e:
                                  ^
SyntaxError: invalid syntax

Markdown output seems broken, is mostly HTML

With tag 0.1.4 of skydoc, and skylark_doc(format="markdown") I am getting output that's mostly HTML with a few markdown-looking headers:

<!---
Documentation generated by Skydoc
-->
<h1>jasmine_node_test Rules</h1>


<nav class="toc">
  <h2>Macros</h2>
  <ul>
    <li><a href="#jasmine_node_test">jasmine_node_test</a></li>
  </ul>
</nav>
<a name="jasmine_node_test"></a>
## jasmine_node_test

<pre>
jasmine_node_test(<a href="#jasmine_node_test.name">name</a>, <a href="#jasmine_node_test.srcs">srcs</a>, <a href="#jasmine_node_test.data">data</a>, <a href="#jasmine_node_test.deps">deps</a>)
</pre>




<a name="jasmine_node_test_args"></a>
### Attributes

feature request: tar output

skylark_doc produces a ZIP file containing the generated documentation. It would be useful if it could instead produce a TAR archive. That would be more compatible with consuming rules, such as docker_build; unpacking TARs as inputs seems to be more common in the bazel ecosystem than ZIPs.

Fix multiple target generation using skylark_library

I'm fairly sure I broke multiple targets as described in the docs in #64. That commit amended the behavior to only generate output for the srcs, and the docs describe the rule as generating output for all the Skylark in the skylark_library deps.

I think this is fixable by extending srcs to allow SkylarkLibraryInfo providers in srcs and generating only direct dependencies of those skylark_library targets. deps would only be necessary if your sources specify exact .bzl files that rely on those dependencies.

Extract and document default values for attributes

Add support for extracting default values for rule and macro attributes. Skylark rules generally provide this information, though for Macros, we could extract this information from default argument values from the AST.

Dummy binding for python_headers breaks bazel query

Querying against a skylark_doc rule breaks bazel query.

Details

bazel version

$ bazel version
Build label: 0.6.0-homebrew
Build target: bazel-out/darwin_x86_64-opt/bin/src/main/java/com/google/devtools/build/lib/bazel/BazelServer_deploy.jar
Build time: Fri Sep 29 05:33:07 2017 (1506663187)
Build timestamp: 1506663187
Build timestamp as int: 1506663187

WORKSPACE

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 = "io_bazel_skydoc",
    remote = "https://github.com/bazelbuild/skydoc.git",
    commit = "e9be81cf5be41e4200749f5d8aa2db7955f8aacc",
)
load("@io_bazel_skydoc//skylark:skylark.bzl", "skydoc_repositories")
skydoc_repositories()

//tools/BUILD

load("@io_bazel_skydoc//skylark:skylark.bzl", "skylark_library", "skylark_doc")

skylark_library(
    name = "rules",
    srcs = glob(["*.bzl"]),
)

skylark_doc(
    name = "docs",
    deps = [
        ":rules",
    ],
    format = "html",
)

Results in this error:

$ bazel query 'deps(//tools:docs)'
ERROR: /private/var/tmp/_bazel_bdouglas/db632a97ad204802c994aaf0f9f9d66b/external/io_bazel_skydoc/skylark/skylark.bzl:316:3: no such target '//:dummy': target 'dummy' not declared in package '' defined by /Users/bdouglas/work/crm/BUILD and referenced by '//external:python_headers'.
ERROR: /private/var/tmp/_bazel_bdouglas/db632a97ad204802c994aaf0f9f9d66b/external/io_bazel_skydoc/skylark/skylark.bzl:316:3: no such target '//:dummy': target 'dummy' not declared in package '' defined by /Users/bdouglas/work/crm/BUILD and referenced by '//external:python_headers'.
ERROR: Evaluation of query "deps(//tools:docs)" failed: errors were encountered while computing transitive closure.

Rewrite of Skydoc

We plan to rewrite Skydoc using a real Skylark interpreter (instead of Python).

Commit 4b71d2e1bc3afa0ce0a5b6e68dac3c559654d975 of Bazel enforce workspace name which breaks skydoc

skydoc should have a workspace name and fix the various imports.

/cc @davidzchen