Generate manpages #2373

alban · 2016-04-04T12:58:07Z

manpages: generate manpages with cobra

To update the manpages, use:

    $ make manpages

It will generate the manpages in dist/manpages/.

Also the bash completion file is no longer built manually, but you can
use:

    $ make bash-completion

It will generate dist/bash_completion/rkt.bash.

The release guide (release.md) is updated to make sure that each release
contains an up-to-date version of the manpages and the bash completion
file.

Fixes #2370

iaguis · 2016-04-04T13:02:10Z

rkt/rkt.go

+		os.Exit(0)
+	}
+
+	// update rkt.bash


wrong comment

iaguis · 2016-04-04T13:03:51Z

rkt/rkt.go

+			Section: "1",
+		}
+
+		doc.GenManTree(cmdRkt, header, "dist/manpages")


Maybe we should not ignore errors?

I will fix.

alban · 2016-04-04T13:04:07Z

Assigning to @s-urbaniak to get a review.

s-urbaniak · 2016-04-04T13:16:15Z

Seems odd that we are using the rkt binary to generate man pages by setting a magic env var and also checking in generated files. Generation of man pages is something we should rather do at build time only and not pollute the runtime behavior of rkt?!

How about having a separate man.go file having a +man build flag being invoked as a make target make doc to generate the man pages explicitly using go run?

s-urbaniak · 2016-04-04T13:29:55Z

rkt/rkt.go

-	// // Uncomment to update rkt.bash
-	// stdout.Print("Generating rkt.bash")
-	// cmdRkt.GenBashCompletionFile("dist/bash_completion/rkt.bash")
-	// os.Exit(0)


👍 for removing commented code

alban · 2016-04-04T15:03:29Z

@s-urbaniak PR updated. I also updated the description above. PTAL.

s-urbaniak · 2016-04-04T15:26:51Z

rkt/manpages_gen.go

+
+	err := doc.GenManTree(cmdRkt, header, "dist/manpages")
+	if err != nil {
+		fmt.Printf("Failed to generate the man pages: %v\n", err)


nit: use stderr instead?

s-urbaniak · 2016-04-04T15:30:00Z

@alban small nits, I am still unsure of checking in the generated man files (@jonboulle, comments?), else LGTM :-)

jonboulle · 2016-04-04T16:01:11Z

I agree with @s-urbaniak that we should avoid committing the generated artefacts - otherwise we're inevitably going to have rot between them. Can't we just keep the generation as part of the release process and in notes for distributors?

alban · 2016-04-04T16:43:08Z

@s-urbaniak @jonboulle Updated. I added new commits and I will squash them once it looks good to you. I removed the generated files from the git repository (except the protobuf generated files, see #2004 - to be done in a different PR), and updated the build scripts.

s-urbaniak · 2016-04-04T17:15:33Z

CHANGELOG.md

@@ -1,3 +1,12 @@
+## vUNRELEASED


the v is superfluous.

We usually prepend v to version number, so I think it's ok.

got it, thanks!

s-urbaniak · 2016-04-04T17:16:51Z

LGTM

krnowak · 2016-04-04T17:44:32Z

scripts/build-rkt.sh

 set -e

-./autogen.sh && ./configure --enable-tpm=no --with-stage1-default-images-directory=/usr/lib/rkt/stage1-images --with-stage1-default-location=/usr/lib/rkt/stage1-images/stage1-coreos.aci && make -j4
+./autogen.sh && \


Hm, we have the set -e call above so chaining everything with && is not really necessary. Could you simplify it by removing those && and removing one level of indentation in the lines below?

krnowak · 2016-04-04T18:12:42Z

rkt/rkt.mk

 # RKT_STAMP deliberately not cleared
 # RKT_BINARY deliberately not cleared
+
+manpages:


/me turns a blind eye on this. The concerns I have, and which maybe I'll address later when I simplify some bits and document them, are:

I would make it a part of make all.

I would prefer the files to be generated inside $(BUILDDIR)

That would require passing that directory to the generator, so it would know where to put the files.

But that complicates things (make clean, deps, forwarding variables, blah blah blah), so don't bother with it for now.

Pretty printers could be used there.

No big deal, since the output is rather short.

These additions should be put above the $(call undefine-namespaces,LOCAL) line.

I would make it a part of make all.

It would make the compilation quite slow if we run make manpages/bash-completion at each make though... On my laptop:

time make manpages: 25 seconds

time make bash-completion: 24 seconds

total: 49 seconds

I would prefer the files to be generated inside $(BUILDDIR)
That would require passing that directory to the generator, so it would know where to put the files.
But that complicates things (make clean, deps, forwarding variables, blah blah blah), so don't bother with it for now.

Ok, I'll skip that for now.

Pretty printers could be used there.
No big deal, since the output is rather short.

How to do that?

These additions should be put above the $(call undefine-namespaces,LOCAL) line.

Will do in the next update.

It would make the compilation quite slow if we run make manpages/bash-completion at each make though... On my laptop:

time make manpages: 25 seconds

time make bash-completion: 24 seconds

total: 49 seconds

I wanted it to be a part of make all, because it is about building everything. Possibly this could be controlled with --enable-man and --enable-bash-completion flags which could be disabled by default.

Pretty printers could be used there.
No big deal, since the output is rather short.

How to do that?

manpages: $(VQ) \ <- this expands to @ when pretty printing (V=0,1,2) or to nothing for raw output (V=3) set -e; \ $(call vb,vt,GEN,manpages) \ <- this will print "GEN manpages" for V=1,2, nothing otherwise) ls rkt/*.go | blah blah blah

alban · 2016-04-05T11:10:24Z

Updated. PTAL.

iaguis · 2016-04-05T11:24:47Z

Running

$ ./autogen.sh && ./configure --enable-tpm=no && make manpages

doesn't work for me because before make, there's nothing in $BUILDDIR/gopath:

mkdir -p dist/manpages/
ls rkt/*.go | grep -vE '_test.go|main.go|_gen.go' | xargs go run rkt/manpages_gen.go
rkt/image_cmd_common.go:24:2: cannot find package "github.com/appc/spec/discovery" in any of:
    /usr/lib/go/src/github.com/appc/spec/discovery (from $GOROOT)
    /home/iaguis/work/coreos/go/src/github.com/coreos/rkt/build-rkt-1.3.0+git/gopath/src/github.com/coreos/rkt/Godeps/_workspace/src/github.com/appc/spec/discovery (from $GOPATH)
    /home/iaguis/work/coreos/go/src/github.com/coreos/rkt/build-rkt-1.3.0+git/gopath/src/github.com/appc/spec/discovery
rkt/api_service.go:28:2: cannot find package "github.com/appc/spec/schema" in any of:
    /usr/lib/go/src/github.com/appc/spec/schema (from $GOROOT)
    /home/iaguis/work/coreos/go/src/github.com/coreos/rkt/build-rkt-1.3.0+git/gopath/src/github.com/coreos/rkt/Godeps/_workspace/src/github.com/appc/spec/schema (from $GOPATH)
    /home/iaguis/work/coreos/go/src/github.com/coreos/rkt/build-rkt-1.3.0+git/gopath/src/github.com/appc/spec/schema

[...]

krnowak · 2016-04-05T11:34:54Z

Meh, as a workaround for this issue (./autogen.sh && ./configure && make manpages) just do:

manpages: | $(GOPATH_TO_CREATE)/src/$(REPO_PATH)
bash-completion: | $(GOPATH_TO_CREATE)/src/$(REPO_PATH)

iaguis · 2016-04-05T11:48:14Z

The workaround works 👷

krnowak · 2016-04-05T11:48:39Z

Cool.

iaguis · 2016-04-05T11:49:21Z

LGTM

alban · 2016-04-05T11:53:05Z

Ok, commits squashed.

iaguis · 2016-04-05T11:55:34Z

LGTMTMOG

iaguis · 2016-04-05T11:56:19Z

Nit: actually you don't update the release guide but the release script (commit message).

To update the manpages, use: $ make manpages It will generate the manpages in dist/manpages/. Also the bash completion file is no longer built manually, but you can use: $ make bash-completion It will generate dist/bash_completion/rkt.bash. The release scripts are updated to make sure that each release contains an up-to-date version of the manpages and the bash completion file.

alban added area/usability kind/documentation needs/review labels Apr 4, 2016

alban added this to the v1.4.0 milestone Apr 4, 2016

iaguis reviewed Apr 4, 2016
View reviewed changes

rkt/rkt.go Outdated

os.Exit(0)

}

// update rkt.bash

Copy link

Member

iaguis Apr 4, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

wrong comment

alban assigned s-urbaniak Apr 4, 2016

iaguis reviewed Apr 4, 2016
View reviewed changes

s-urbaniak added needs/some-changes and removed needs/review labels Apr 4, 2016

alban assigned alban and unassigned s-urbaniak Apr 4, 2016

s-urbaniak reviewed Apr 4, 2016
View reviewed changes

alban force-pushed the alban/manpages branch from 2201c9e to a069ae5 Compare April 4, 2016 15:00

Godeps: add cobra/doc

d4cc75b

alban force-pushed the alban/manpages branch from a069ae5 to 9be7a38 Compare April 4, 2016 15:05

s-urbaniak reviewed Apr 4, 2016
View reviewed changes

krnowak reviewed Apr 4, 2016
View reviewed changes

alban force-pushed the alban/manpages branch from 29260f7 to e71c149 Compare April 5, 2016 11:52

alban force-pushed the alban/manpages branch from e71c149 to cb0d5e2 Compare April 5, 2016 12:23

alban added reviewed/lgtm and removed needs/some-changes labels Apr 5, 2016

alban merged commit 7b347bb into rkt:master Apr 5, 2016

Uh oh!

Generate manpages #2373

Generate manpages #2373

Uh oh!

Conversation

alban commented Apr 4, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alban commented Apr 4, 2016

Uh oh!

s-urbaniak commented Apr 4, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alban commented Apr 4, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

s-urbaniak commented Apr 4, 2016

Uh oh!

jonboulle commented Apr 4, 2016

Uh oh!

alban commented Apr 4, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

s-urbaniak commented Apr 4, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alban commented Apr 5, 2016

Uh oh!

iaguis commented Apr 5, 2016

Uh oh!

krnowak commented Apr 5, 2016

Uh oh!

iaguis commented Apr 5, 2016

Uh oh!

krnowak commented Apr 5, 2016

Uh oh!

iaguis commented Apr 5, 2016

Uh oh!

alban commented Apr 5, 2016

Uh oh!

iaguis commented Apr 5, 2016

Uh oh!

iaguis commented Apr 5, 2016

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants