Skylark docs

[ittaiz]

Stumbled on to skydoc and thought it could be useful.
Honestly I don't have time and I'm guessing @ianoc-stripe or @johnynek don't have either but I thought this could be an interesting task for someone wanting to learn the repository.
WDYT?

[johnynek]

Sounds good to me. Would welcome PRs and work to publish the documentation to the GitHub site.

…

On Wed, Feb 1, 2017 at 10:19 Ittai Zeidman ***@***.***> wrote: Stumbled on to skydoc <https://skydoc.bazel.build/> and thought it could be useful. Honestly I don't have time and I'm guessing @ianoc-stripe <https://github.com/ianoc-stripe> or @johnynek <https://github.com/johnynek> don't have either but I thought this could be an interesting task for someone wanting to learn the repository. WDYT? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#133>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAEJdrLFa0fXJrIjJ2saa9VBnGjCM-aZks5rYOjtgaJpZM4L0Vnx> .

[beala-stripe]

@long-stripe and I tried this, but we hit two issues:

1. Stardoc does not currently support generating docs for any bzl file that has a transitive dep on @bazel_tools (Transitive dependencies on @bazel_tools make it impossible to use Stardoc skydoc#166)

   rules_scala/scala/scala.bzl

   Line 15 in 725dc35

   load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file", "http_archive")

   rules_scala/scala/scala.bzl

   Lines 494 to 498 in 725dc35

   	http_archive(
   	name = "java_stub_template",
   	sha256 = "1859a37dccaee8c56b98869bf1f22f6f5b909606aff74ddcfd59e9757a038dd5",
   	urls = ["https://github.com/bazelbuild/rules_scala/archive/8b8271e3ee5709e1340b19790d0b396a0ff3dd0f.tar.gz"],
   	strip_prefix = "rules_scala-8b8271e3ee5709e1340b19790d0b396a0ff3dd0f/java_stub_template",

2. Stardoc only generates markdown, and does not generate HTML. We could dump the md files to a docs/ directory, but it makes for a less nice presentation. stardoc has no html output support skydoc#148