Autogenerate API documentation using Skydoc

[mboes]

Our API documentation is currently handwritten in Markdown, separate from the code. But this is error-prone. It would be better if there existed a tool to do this for us (like Haddock, doxygen, etc). Such a tool does exist, it's called Skydoc. But it's not used by many rule sets currently for some reason.

If we auto-generate docs, we should auto-deploy the generated doc on a website upon any update of the master branch.

Possibly blocked on bazelbuild/skydoc#71.

[mrkkrp]

Skydoc does not build for me because of this bug: bazelbuild/bazel#4572. This time rules_sass breaks (needed for Skydoc):

ERROR: /home/mark/.cache/bazel/_bazel_mark/c9fbb95e6d5f934486004f4c79ab9586/external/sassc/BUILD.bazel:4:1: undeclared inclusion(s) in rule '@sassc//:sassc':
this rule is missing dependency declarations for the following files included by 'external/libsass/src/cencode.c':
  '/usr/include/stdc-predef.h'

I have seen this bug several times already, but wasn't sure it's not a problem in my code. But if I have Bazel working and I pull official rules_sass which fail to build, something must be wrong with Bazel?

[mboes]

Why not downgrade to 0.9? That's the version that seems to be working for everybody.

[mrkkrp]

I just checked, I'm actually using 0.9 from nix:

[mark@arch rules_sass]$ bazel version
Build label: 0.9.0- (@non-git)
Build target: bazel-out/k8-opt/bin/src/main/java/com/google/devtools/build/lib/bazel/BazelServer_deploy.jar
Build time: Sat Nov 2 00:00:00 +11968 (315532800000)
Build timestamp: 315532800000
Build timestamp as int: 315532800000
[mark@arch rules_sass]$ which bazel
/home/mark/.nix-profile/bin/bazel

I have uninstalled system-level bazel installation (which was 0.10 actually). But still everything is the same... I'll keep trying.

[mrkkrp]

Opened an issue: bazelbuild/bazel#4612. I spent about 2 hours today (untracked, as I suppose it's some sort of issue with my setup) trying to fix this to no avail.