Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(godocfx): create Go DocFX YAML generator #2854

Merged
merged 8 commits into from Sep 15, 2020
Merged

feat(godocfx): create Go DocFX YAML generator #2854

merged 8 commits into from Sep 15, 2020

Conversation

@tbpg
Copy link
Collaborator

@tbpg tbpg commented Sep 14, 2020

There is a some code copied from https://github.com/golang/pkgsite for getting type/function synopses. Because of those license headers, I put the code in third_party.

I included a script we can hopefully use from a Kokoro job. That shows how the generator is intended to be used.

Eventually, we may publish this as a standalone tool. We may end up wanting to publish docs for other modules (outside google-cloud-go). It's also possible others in the community would be interested.

cc @dmitshur @julieqiu @JustinBeckwith @spf13 @SurferJeffAtGoogle @jskeet

@tbpg tbpg requested review from broady, codyoss and noahdietz Sep 14, 2020
@google-cla google-cla bot added the cla: yes label Sep 14, 2020
outDir := flag.String("out", "obj/api", "Output directory (default obj/api)")
flag.Parse()
if flag.NArg() != 1 {
log.Fatalf("%s expected 1 arg, got %d", os.Args[0], flag.NArg())

This comment has been minimized.

@noahdietz

noahdietz Sep 14, 2020
Contributor

Nit: could this error message be improved? %s missing required argument: module path

This comment has been minimized.

@tbpg

tbpg Sep 14, 2020
Author Collaborator

Done.

third_party/internal/godocfx/main.go Outdated Show resolved Hide resolved
third_party/internal/godocfx/main.go Outdated Show resolved Hide resolved
third_party/internal/godocfx/parse.go Outdated Show resolved Hide resolved
third_party/internal/godocfx/parse.go Outdated Show resolved Hide resolved
pages := map[string]*page{}
toc := tableOfContents{}

module := pkgs[0].Module

This comment has been minimized.

@codyoss

codyoss Sep 14, 2020
Member

Will at least one pkg always exist?

This comment has been minimized.

@tbpg

tbpg Sep 14, 2020
Author Collaborator

Yes. len(pkgs) == 0 is checked above.

third_party/internal/godocfx/parse.go Outdated Show resolved Hide resolved
internal/godocfx/go.mod Outdated Show resolved Hide resolved
Copy link
Collaborator Author

@tbpg tbpg left a comment

Thanks! Please take another look.

outDir := flag.String("out", "obj/api", "Output directory (default obj/api)")
flag.Parse()
if flag.NArg() != 1 {
log.Fatalf("%s expected 1 arg, got %d", os.Args[0], flag.NArg())

This comment has been minimized.

@tbpg

tbpg Sep 14, 2020
Author Collaborator

Done.

third_party/internal/godocfx/main.go Outdated Show resolved Hide resolved
third_party/internal/godocfx/main.go Outdated Show resolved Hide resolved
third_party/internal/godocfx/parse.go Outdated Show resolved Hide resolved
third_party/internal/godocfx/parse.go Outdated Show resolved Hide resolved
pages := map[string]*page{}
toc := tableOfContents{}

module := pkgs[0].Module

This comment has been minimized.

@tbpg

tbpg Sep 14, 2020
Author Collaborator

Yes. len(pkgs) == 0 is checked above.

third_party/internal/godocfx/parse.go Outdated Show resolved Hide resolved
@dmitshur
Copy link

@dmitshur dmitshur commented Sep 14, 2020

FYI, there is a tracking issue golang/go#39883 for making that API available to for external use; mentioning it here so that this use case can be considered as part of that work. You may also want to leave a 👍 reaction and/or subscribe to it.

@tbpg
Copy link
Collaborator Author

@tbpg tbpg commented Sep 14, 2020

Thanks! I gave a 👍 to golang/go#39883.

tbpg added 3 commits Sep 14, 2020
@tbpg tbpg requested review from noahdietz and codyoss Sep 15, 2020
Copy link
Member

@codyoss codyoss left a comment

LGTM

@tbpg tbpg merged commit 37c70ac into master Sep 15, 2020
3 checks passed
3 checks passed
@google-cla
cla/google All necessary CLAs are signed
@conventional-commit-lint-gcf
conventionalcommits.org
Details
@kokoro-team
kokoro Kokoro CI build successful
Details
@tbpg tbpg deleted the godocfx branch Sep 15, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

4 participants