Stardoc generates extras.md #2992

cvarier · 2021-10-28T23:18:22Z

What type of PR is this?

Documentation

What does this PR do? Why is it needed?
This is a mirror of the content in extras.rst, allowing us to manually inspect the delta between them:
LHS: https://github.com/bazelbuild/rules_go/blob/master/go/extras.rst
RHS: master...aspect-dev:stardoc-chai#diff-facb0b3aafba052f3e5fe16fbe02d2c2f6b2c2c30c443fd08f4617d4c5d38532

As soon as we are satisfied that the generated content is correct, we'll delete extras.rst and update any links to it.
(This could happen as part of this PR, or subsequent)

Technique:

Converted RST to Github-flavored MD using pandoc (https://pandoc.org/try)
Filled in gaps by copying doc strings out of existing RST file into the starlark files (converting to MD syntax).

First step in addressing #2437
Remaining steps will be to rinse-and-repeat for other .rst files containing rule APIs

Which issues(s) does this PR fix?

Fixes #2437

…cked-in restructuredtext doc

google-cla · 2021-10-28T23:18:29Z

All (the pull request submitter and all commit authors) CLAs are signed, but one or more commits were authored or co-authored by someone other than the pull request submitter.

We need to confirm that all authors are ok with their commits being contributed to this project. Please have them confirm that by leaving a comment that contains only @googlebot I consent. in this pull request.

Note to project maintainer: There may be cases where the author cannot leave a comment, or the comment is not properly detected as consent. In those cases, you can manually confirm consent of the commit author(s), and set the cla label to yes (if enabled on your project).

ℹ️ Googlers: Go here for more info.

alexeagle · 2021-10-28T23:19:31Z

@googlebot I consent.

achew22

@cvarier, thanks so much for sending this in. This is a great start on the process of modernizing the documentation in rules_go!

achew22 · 2021-10-29T00:41:12Z

docs/BUILD.bazel

+  [core go rules]: core.rst
+"""
+
+# Workaround https://github.com/bazelbuild/stardoc/issues/25


Hrm... looking at the linked issue, it's possible that it is actually resolved and the workaround isn't necessary. See alexeagle/stardoc@586650b.

If you are 100% sure that this is necessary, what would you think about writing the template.vm file out in the //docs directory itself and just referring to it rather than generating? I don't see anything in here that's only knowable at build time, so I would like to understand the advantages you see in generating the file instead of checking it in.

Yes, you are totally right about this, thank you for pointing it out!

achew22 · 2021-10-29T00:43:43Z

docs/BUILD.bazel

+------------------------------------------------------------------------
+"""
+
+_NAV_FOOTER = """


The purpose of these in .rst files is to make it possible to conveniently link many times to the same place, sort of like a reusable consts. While these values defined like this are kind of nice to have, it seems to me that since none of them are used more than once, we should probably just inline the link in the .bzl that is being used to generate.

I think that would give us all the content we need on the page and simplify the BUILD file a great deal since we wouldn't need to generate a template at all.

What do you think?

Good point, after a bit of finagling I was able to get it to work without the template and by transferring over the consts to docstring comments.

achew22 · 2021-10-29T00:47:06Z

docs/BUILD.bazel

+        name = file.replace(":", "_") + "_doc",
+        out = file.replace(":", "_") + ".md_",
+        header_template = ":header.vm",
+        input = "//%s.bzl" % file,


Please move the // to the dictionary above. I was staring at that for quite a while trying to figure out if it was a target or if this was some additional syntax that I needed to learn.

achew22 · 2021-10-29T00:47:42Z

docs/BUILD.bazel

+)
+
+_DOC_SRCS = {
+    "extras:embed_data": "//go:extras.rst",


What is the //go:extras.rst supposed to be? I thought this was generating extras.md?

Yes, you're right, updating this.

achew22 · 2021-10-29T00:50:17Z

docs/BUILD.bazel

+    ] + [
+        "cp -fv bazel-bin/docs/{0} {1}".format(
+            k.replace(":", "_") + ".md_",
+            v[2:].replace(":", "/").replace(".rst", ".md"),


Here and above. This feels like a lot of work to avoid writing .md in the _DOC_SRCS dict. I think you should just write the file that you want to compare against instead of doing some translation at the comparison point.

go/extras.rst

cvarier · 2021-10-29T18:33:03Z

@achew22 Thank you for your review! I addressed your comments and updated the PR again, let me know what you think!

extras/embed_data.bzl

achew22

Two little ones then I think we can merge this

achew22 · 2021-10-29T20:53:32Z

.bazelci/presubmit.yml

@@ -327,3 +327,6 @@ tasks:
    - "-//tests/legacy/test_chdir:go_default_test"
    - "-//tests/legacy/test_rundir:go_default_test"
    - "-//tests/legacy/transitive_data:go_default_test"
+    # Stardoc produces different line-endings on windows,
+    # so the documentation it generates doesn't match the checked in files


Sorry, one more thing. Can you add a comment here identifying the issue tracking this so we can recover it when that's resolved

achew22 · 2021-10-29T23:54:05Z

go/extras.rst

@@ -1,95 +0,0 @@
-Extra rules


Please don't delete the file, instead leave a stub file that says "This file has moved, please look at it here"

… problems

cvarier · 2021-10-30T04:45:14Z

@achew22 updated again

achew22 · 2021-10-30T05:12:32Z

@cvarier, thanks for the great PR! This is a big win for the project and progress for the whole ecosystem.

alexeagle and others added 5 commits October 20, 2021 14:06

WIP: generate stardoc output for embed_data rule and compare with che…

070b8dd

…cked-in restructuredtext doc

Kinda generate restructuredtext

5a586ff

add updater

3fb42b1

stardoc generates extras.md

2cb268a

fixed difftest to only compare generated md and current md

153aa82

google-cla bot added the cla: no label Oct 28, 2021

google-cla bot added cla: yes and removed cla: no labels Oct 28, 2021

achew22 requested changes Oct 29, 2021

View reviewed changes

address comments

ac60362

achew22 reviewed Oct 29, 2021

View reviewed changes

extras/embed_data.bzl Show resolved Hide resolved

Chai Varier added 2 commits October 29, 2021 16:25

add additional resources section

fd820da

remove todo

f670ebb

achew22 requested changes Oct 29, 2021

View reviewed changes

convert go/extras.rst to stub, add issue tracking windows line ending…

82c60b9

… problems

achew22 merged commit 2474a1e into bazel-contrib:master Oct 30, 2021

cvarier deleted the stardoc-chai branch November 1, 2021 17:23

alexeagle mentioned this pull request Nov 9, 2021

Stardoc generates API docs for core rules #3000

Merged

JamyDev mentioned this pull request Jan 18, 2022

Release rules_go v0.30.0 #3049

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Stardoc generates extras.md #2992

Stardoc generates extras.md #2992

cvarier commented Oct 28, 2021

google-cla bot commented Oct 28, 2021

alexeagle commented Oct 28, 2021

achew22 left a comment

achew22 Oct 29, 2021

cvarier Oct 29, 2021

achew22 Oct 29, 2021

cvarier Oct 29, 2021

achew22 Oct 29, 2021

achew22 Oct 29, 2021

cvarier Oct 29, 2021

achew22 Oct 29, 2021

cvarier commented Oct 29, 2021

achew22 left a comment

achew22 Oct 29, 2021

achew22 Oct 29, 2021

cvarier commented Oct 30, 2021

achew22 commented Oct 30, 2021

Stardoc generates extras.md #2992

Stardoc generates extras.md #2992

Conversation

cvarier commented Oct 28, 2021

google-cla bot commented Oct 28, 2021

alexeagle commented Oct 28, 2021

achew22 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cvarier commented Oct 29, 2021

achew22 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cvarier commented Oct 30, 2021

achew22 commented Oct 30, 2021