Migrate documentation to skydoc

[mattmoor]

See #30 for more details.

[mattmoor]

@damienmg I'm hitting the following trying to use skydoc.

I pushed the repro to the skydoc branch on my fork.

$ bazel build //docs/...
INFO: Found 8 targets...
ERROR: /home/mattmoor/rules_docker/docs/BUILD:82:1: Generating Skylark doc for docs-html (13 files) failed: Process exited with status 1 [sandboxed].
Traceback (most recent call last):
  File "/home/mattmoor/.cache/bazel/_bazel_mattmoor/5c340bb9d399314dffbfbc3c347e19fb/bazel-sandbox/8331154761733958341/execroot/rules_docker/bazel-out/host/bin/external/io_bazel_skydoc/skydoc/skydoc.runfiles/io_bazel_rules_docker/../io_bazel_skydoc/skydoc/main.py", line 330, in <module>
    main(FLAGS(sys.argv))
  File "/home/mattmoor/.cache/bazel/_bazel_mattmoor/5c340bb9d399314dffbfbc3c347e19fb/bazel-sandbox/8331154761733958341/execroot/rules_docker/bazel-out/host/bin/external/io_bazel_skydoc/skydoc/skydoc.runfiles/io_bazel_rules_docker/../io_bazel_skydoc/skydoc/main.py", line 308, in main
    rule_doc_extractor.parse_bzl(bzl_file, load_symbols)
  File "/home/mattmoor/.cache/bazel/_bazel_mattmoor/5c340bb9d399314dffbfbc3c347e19fb/bazel-sandbox/8331154761733958341/execroot/rules_docker/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 "/home/mattmoor/.cache/bazel/_bazel_mattmoor/5c340bb9d399314dffbfbc3c347e19fb/bazel-sandbox/8331154761733958341/execroot/rules_docker/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 "docker/build.bzl", line 275, in <module>
    } + _hash_tools + _layer_tools,
TypeError: unsupported operand type(s) for +: 'dict' and 'str'
Use --strategy=Skydoc=standalone to disable sandboxing for the failing actions.
INFO: Elapsed time: 1.089s, Critical Path: 0.39s

[damienmg]

/cc @davidzchen for Skydoc

[mattmoor]

@davidzchen what's going on?

[mattmoor]

I've updated my repro branch to HEAD, and the issue persists. I verified that my repro is on the latest release of the skydoc and sass repos.

I'd put documenting certain parts of the repo (e.g. contrib) on hold in an effort to move to skydoc, which is blocked on this issue. However, I keep getting requests for things that exist, but aren't yet documented, so if we can't get this resolved soon, I think I'm going to have to document things the old way. :(

Ping @davidzchen .
FYI @ulfjack .

[davidzchen]

Sorry for the wait.

The reason why you are getting this error is because Skydoc evaluates Skylark code as Python, and Python does not support the + operator for dictionaries. The way to work around this is to combine the dictionaries using a way that is supported by Python, for example: https://github.com/bazelbuild/rules_rust/blob/master/rust/rust.bzl#L672

AFAIU, we do have plans to disallow + for dictionaries in Skylark so that Skylark is a proper subset of Python: bazelbuild/bazel#1086

[mattmoor]

Thanks, I will try that out and see if it unblocks me.

[mattmoor]

I have pushed an update that rewrites to use dict(foo.items() + bar.items() + baz.items()) and there is a new error:

$ bazel build //docs/...
INFO: Analysed 8 targets (18 packages loaded).
INFO: Found 8 targets...
ERROR: /home/mattmoor/rules_docker/docs/BUILD:81:1: Generating Skylark doc for docs-html (12 files) failed (Exit 1)
Traceback (most recent call last):
  File "/home/mattmoor/.cache/bazel/_bazel_mattmoor/5c340bb9d399314dffbfbc3c347e19fb/bazel-sandbox/5977716226292821528/execroot/io_bazel_rules_docker/bazel-out/host/bin/external/io_bazel_skydoc/skydoc/skydoc.runfiles/io_bazel_rules_docker/../io_bazel_skydoc/skydoc/main.py", line 330, in <module>
    main(FLAGS(sys.argv))
  File "/home/mattmoor/.cache/bazel/_bazel_mattmoor/5c340bb9d399314dffbfbc3c347e19fb/bazel-sandbox/5977716226292821528/execroot/io_bazel_rules_docker/bazel-out/host/bin/external/io_bazel_skydoc/skydoc/skydoc.runfiles/io_bazel_rules_docker/../io_bazel_skydoc/skydoc/main.py", line 308, in main
    rule_doc_extractor.parse_bzl(bzl_file, load_symbols)
  File "/home/mattmoor/.cache/bazel/_bazel_mattmoor/5c340bb9d399314dffbfbc3c347e19fb/bazel-sandbox/5977716226292821528/execroot/io_bazel_rules_docker/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 "/home/mattmoor/.cache/bazel/_bazel_mattmoor/5c340bb9d399314dffbfbc3c347e19fb/bazel-sandbox/5977716226292821528/execroot/io_bazel_rules_docker/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 "docker/build.bzl", line 332, in <module>
    }.items() + _hash_tools.items() + _layer_tools.items())
AttributeError: 'str' object has no attribute 'items'
INFO: Elapsed time: 2.277s, Critical Path: 0.61s
FAILED: Build did NOT complete successfully

It looks like the load of the dict from another .bzl file is being interpreted as a string.

[mattmoor]

This is blocked on: bazelbuild/skydoc#21