8032b983fa
bookmaker is a tool that generates documentation backends from a canonical markup. Documentation for bookmaker itself is evolving at docs/usingBookmaker.bmh, which is visible online at skia.org/user/api/bmh_usingBookmaker Change-Id: Ic76ddf29134895b5c2ebfbc84603e40ff08caf09 Reviewed-on: https://skia-review.googlesource.com/28000 Commit-Queue: Cary Clark <caryclark@google.com> Reviewed-by: Cary Clark <caryclark@google.com>
96 lines
2.5 KiB
Plaintext
96 lines
2.5 KiB
Plaintext
#External
|
|
SkXXX
|
|
bmh_SkXXX
|
|
CL
|
|
C
|
|
Visual_Studio
|
|
##
|
|
|
|
#Topic Bookmaker
|
|
|
|
How to use the Bookmaker utility.
|
|
|
|
Get the fiddle command line interface tool.
|
|
|
|
#Code
|
|
$ go get go.skia.org/infra/fiddle/go/fiddlecli
|
|
##
|
|
|
|
Get the Bookmaker CL and build it.
|
|
|
|
#Code
|
|
$ git cl patch 9919
|
|
$ ninja -C out/dir bookmaker
|
|
##
|
|
|
|
Generate an starter Bookmaker file from an existing include.
|
|
This writes SkXXX.bmh in the current directory, which is
|
|
out/dir/obj/ from an IDE.
|
|
|
|
#Code
|
|
$ ./out/dir/bookmaker -t -i include/core/SkXXX.h
|
|
##
|
|
|
|
Use your favorite editor to fill out SkXXX.bmh.
|
|
|
|
Generate fiddle.json from all examples, including the ones you just wrote.
|
|
Error checking is syntatic: starting keywords are closed, keywords have the
|
|
correct parents.
|
|
If you run Bookmaker inside Visual_Studio, you can click on errors and it
|
|
will take you to the source line in question.
|
|
|
|
#Code
|
|
$ ./out/dir/bookmaker -e fiddle.json -b current_directory
|
|
##
|
|
|
|
Once complete, run fiddlecli to generate the example hashes.
|
|
Errors are contained by the output but aren't reported yet.
|
|
|
|
#Code
|
|
$ $GOPATH/bin/fiddlecli --input fiddle.json --output fiddleout.json
|
|
##
|
|
|
|
Generate bmh_SkXXX.md from SkXXX.bmh and fiddleout.json.
|
|
Error checking includes: undefined references, fiddle compiler errors,
|
|
missing or mismatched printf output.
|
|
Again, you can click on any errors inside Visual_Studio.
|
|
|
|
#Code
|
|
$ ./out/dir/bookmaker -r site/user/api -b current_directory -f fiddleout.json
|
|
##
|
|
|
|
The original include may have changed since you started creating the markdown.
|
|
Check to see if it is up to date.
|
|
This reports if a method no longer exists or its parameters have changed.
|
|
|
|
#Code
|
|
$ ./out/dir/bookmaker -x -b current_directory/SkXXX.bmh -i include/core/SkXXX.h
|
|
##
|
|
|
|
#Topic Bugs
|
|
#List
|
|
overaggressive reference finding in code block
|
|
missing examples
|
|
redundant examples -- got tired so used the same one more than once
|
|
some examples need vertical resizing
|
|
list doesn't work (ironic, huh)
|
|
##
|
|
##
|
|
|
|
#Topic To_Do
|
|
#List
|
|
check that all methods have one line descriptions in overview
|
|
see also -- anything that can be done automatically? maybe any ref shows up everywhere
|
|
index by example png
|
|
generate pdf or pdf-like out
|
|
generate b/w out instead of color -- have b/w versions of examples?
|
|
formalize voice / syntax for parts of topic and method
|
|
write bmh data back into include
|
|
have a way to write one block that covers multiple nearly indentical methods?
|
|
may want to do this for pdf view as well
|
|
write a one-method-per-page online view?
|
|
##
|
|
##
|
|
|
|
#Topic Bookmaker ##
|