doc: Add generate_git.sh, which updates the checked-in generated docs

doc: Add generate_git.sh, which updates the checked-in generated docs

BUG=crashpad:67
R=agable@chromium.org

Committed: https://chromium.googlesource.com/crashpad/crashpad/+/3ac40a54d0e8e7bbccfcf88cabd67b9659032865

[agable, 2015-10-08 22:22:03]

agable@chromium.org changed reviewers:
+ agable@chromium.org

[agable, 2015-10-08 22:22:03]

Personally, I'd prefer to do this as a recipe running on a continuous builder on
your waterfall, watching for changes to the doc/ subdirectory and landing the
compiled version on tip-of-tree master, rather than maintaining a separate
branch. This makes it easier to keep docs in-sync when you do things like cut a
release branch.

If you want it to be a tiny script run manually by humans, I'd recommend adding
a pre-commit check to make sure the current documentation matches the generated
documentation, and have humans keep them in sync in real-time with their own
CLs.

But if you really want to go this route, the git commands look essentially sane.
LGTM.

https://codereview.chromium.org/1399623002/diff/1/doc/support/generate_git.sh
File doc/support/generate_git.sh (right):

https://codereview.chromium.org/1399623002/diff/1/doc/support/generate_git.sh...
doc/support/generate_git.sh:33: git commit -m "Update documentation to
${remote_master_name} ${master_hash}"
might want to use the short form (7 or 8 characters) of the hash in the commit
message.

https://codereview.chromium.org/1399623002/diff/1/doc/support/generate_git.sh...
doc/support/generate_git.sh:37: # TODO(mark): switch back to the original branch
and the original directory

[Mark Mentovai, 2015-10-08 22:42:40]

Thanks for the comments!

I’d like to keep it on a separate branch so that we don’t pollute master’s
source history with silly little auto-commits in between each real commit.

But yes, I would ultimately like to have this run automatically as a job on some
kind of continuous builder. I was thinking that whatever that recipe would be
should just call this thing that lives in our tree.

https://codereview.chromium.org/1399623002/diff/1/doc/support/generate_git.sh
File doc/support/generate_git.sh (right):

https://codereview.chromium.org/1399623002/diff/1/doc/support/generate_git.sh...
doc/support/generate_git.sh:37: # TODO(mark): switch back to the original branch
agable wrote:
> and the original directory

Why? The script’s done here. cd doesn’t bubble out to the parent (unless someone
wanted to source this script).

[agable, 2015-10-08 22:53:53]

I guess it depends on how often you expect these autocommits to be needed. If
the doxygen updates every time someone touches basically anything, then yeah I
guess this makes sense. But if the docs really only update when big changes are
made, then I think it is easier for developers to have the docs on their normal
master branch. Putting it in a pre-commit check (not pre-upload, that should be
fast) can force developers to keep documentation up-to-date with code
automatically, similarly to how recipes force developers to keep expectations
up-to-date with code. Does generate.sh take too long for that to be realistic?

https://codereview.chromium.org/1399623002/diff/1/doc/support/generate_git.sh
File doc/support/generate_git.sh (right):

https://codereview.chromium.org/1399623002/diff/1/doc/support/generate_git.sh...
doc/support/generate_git.sh:37: # TODO(mark): switch back to the original branch
On 2015/10/08 at 22:42:40, Mark Mentovai wrote:
> agable wrote:
> > and the original directory
> 
> Why? The script’s done here. cd doesn’t bubble out to the parent (unless
someone wanted to source this script).

Exactly. I don't trust bash to not get reused eventually and sourced by someone
who is moving too fast and not paying attention. It's pretty easy to clean up
after oneself, so I think it's advisable to do so even when not strictly
necessary.

[Mark Mentovai, 2015-10-09 03:39:04]

agable wrote:
> I guess it depends on how often you expect these autocommits to be needed. If
> the doxygen updates every time someone touches basically anything, then yeah I
> guess this makes sense.

We Doxygenate pretty much every class, so the documentation tends to move with
nearly every change.

> But if the docs really only update when big changes are
> made, then I think it is easier for developers to have the docs on their
normal
> master branch. Putting it in a pre-commit check (not pre-upload, that should
be
> fast) can force developers to keep documentation up-to-date with code
> automatically, similarly to how recipes force developers to keep expectations
> up-to-date with code. Does generate.sh take too long for that to be realistic?

10-15 seconds. It’d be a little annoying.

[scottmg, 2015-10-09 03:45:39]

On 2015/10/09 03:39:04, Mark Mentovai wrote:
> agable wrote:
> > I guess it depends on how often you expect these autocommits to be needed.
If
> > the doxygen updates every time someone touches basically anything, then yeah
I
> > guess this makes sense.
> 
> We Doxygenate pretty much every class, so the documentation tends to move with
> nearly every change.
> 
> > But if the docs really only update when big changes are
> > made, then I think it is easier for developers to have the docs on their
> normal
> > master branch. Putting it in a pre-commit check (not pre-upload, that should
> be
> > fast) can force developers to keep documentation up-to-date with code
> > automatically, similarly to how recipes force developers to keep
expectations
> > up-to-date with code. Does generate.sh take too long for that to be
realistic?
> 
> 10-15 seconds. It’d be a little annoying.

(I also would like to be able to continue to land from Windows, I'm not sure if
these scripts/tools work there.)

[agable, 2015-10-09 16:26:37]

On 2015/10/09 at 03:45:39, scottmg wrote:
> On 2015/10/09 03:39:04, Mark Mentovai wrote:
> > agable wrote:
> > > I guess it depends on how often you expect these autocommits to be needed.
If
> > > the doxygen updates every time someone touches basically anything, then
yeah I
> > > guess this makes sense.
> > 
> > We Doxygenate pretty much every class, so the documentation tends to move
with
> > nearly every change.
> > 
> > > But if the docs really only update when big changes are
> > > made, then I think it is easier for developers to have the docs on their
> > normal
> > > master branch. Putting it in a pre-commit check (not pre-upload, that
should
> > be
> > > fast) can force developers to keep documentation up-to-date with code
> > > automatically, similarly to how recipes force developers to keep
expectations
> > > up-to-date with code. Does generate.sh take too long for that to be
realistic?
> > 
> > 10-15 seconds. It’d be a little annoying.
> 
> (I also would like to be able to continue to land from Windows, I'm not sure
if these scripts/tools work there.)

Totally good points. LGTM stands!

[Mark Mentovai, 2015-10-21 15:23:50]

mark@chromium.org changed reviewers:
+ scottmg@chromium.org

[Mark Mentovai, 2015-10-21 15:23:51]

Scott, are you comfortable with sh? I’ll probably want to tweak this more as
time goes on, but it’s in a nice, working, usable state now so we should get it
checked in.

[scottmg, 2015-10-21 16:58:31]

On 2015/10/21 15:23:51, Mark Mentovai wrote:
> Scott, are you comfortable with sh? I’ll probably want to tweak this more as
> time goes on, but it’s in a nice, working, usable state now so we should get
it
> checked in.

Sure, I can run on Mac. Better to have it checked in than not.

[Mark Mentovai, 2015-10-21 17:22:21]

We can switch to py if it becomes a problem, but I don’t know if or how well
doxygen and asciidoc and the docbook-xml stuff work on Windows.

[Mark Mentovai, 2015-10-21 17:22:56]

Committed patchset #6 (id:90001) manually as
3ac40a54d0e8e7bbccfcf88cabd67b9659032865 (presubmit successful).