skia2/site/user/api/usingBookmaker.md

usingBookmaker

Bookmaker

Bookmaker generates markdown files to view documentation on skia.org, and generates includes for use in C++. Bookmaker reads canonical documentation from files suffixed with bmh in the docs directory. These bmh files describe how public interfaces work, and generate Skia fiddle examples to illustrate them.

The docs files must be manually edited to stay current with Skia as it evolves.

Broken Build

The bots Housekeeper-PerCommit-Bookmaker and Housekeeper-Nightly-Bookmaker verify that Bookmaker data in docs builds without error and is consistent with include files it documents.

Possible failures include:

Public interface in include directory does not match documented interface in docs directory.

Example in bookmaker bmh file does not compile, or does not produce expected output.

Undocumented but referenced interface is missing from undocumented bookmaker file in docs directory.

Editing comments in includes or editing private interfaces will not break the bots. Bookmaker detects that comments edited in includes do not match comments in docs; it will generate an updated include in the directory where it is run.

If Housekeeper-PerCommit-Bookmaker bot is red, the error is usually related to an edit to an include which has not been reflected in docs.

To fix this, edit the docs file corresponding to the changed include file.

For instance, if the change was made to SkIRect, edit docs/SkIRect_Reference.bmh. Checking in the edited docs/SkIRect_Reference.bmh will fix the bot.

If the interface is deprecated, but still present in the interface, mark-up the documentation to be deprecated as well.

#Method void someMethodThatIsNowDeprecated()
#Deprecated
##

Use

#Deprecated soon

if the change is soon to be deprecated.

If Housekeeper-Nightly-Bookmaker bot is red, one of several things may have gone wrong:

A change to include broke documentation examples.

Something changed the examples that output text.

Some interface was added, deleted, edited.

Documentation is malformed.

The bot output describes what changed, and includes the file and line where the error occurred.

To regenerate the documentation, follow the Installing and Regenerate steps below.

Editing Comments

Edit docs instead of include/core files to update comments if possible.

The Bookmaker bots do not complain if the docs file does not match the corresponding include comments. Running Bookmaker include generation will report when docs and includes comments do not match.

For instance, if include/core/SkSurface.h comments do not match docs/SkSurface_Reference.bmh, running:

$ ./out/dir/bookmaker -b docs -i include/core/SkSurface.h -p

generates

wrote updated SkSurface.h

The updated SkSurface.h is written to the root to avoid subsequent runs of Bookmaker from recompiling. if SkSurface.h was not changed, it is not written, and Bookmaker will not generate any output.

Broken Example

An example may cause Bookmaker or a bot running Bookmaker to fail if it fails to compile.

Fix the example by pasting it into Skia Fiddle and editing it until it runs successfully.

If the example cannot be fixed, it can be commented out by changing

#Example

to

#NoExample

. The disabled example can contain additional markup, which will be ignored.

Installing

Install Go if needed. Check the version. The results should be 1.10 or greater.

$ go version

Get the fiddle command line interface tool. By default this will appear in your home directory.

$ go get go.skia.org/infra/fiddlek/go/fiddlecli

Build Bookmaker.

$ ninja -C out/dir bookmaker

Regenerate

Complete rebuilding of all bookmaker output looks like:

$ ./out/dir/bookmaker -a docs/status.json -e fiddle.json
$ ~/go/bin/fiddlecli --input fiddle.json --output fiddleout.json
$ ./out/dir/bookmaker -a docs/status.json -f fiddleout.json -r site/user/api -c
$ ./out/dir/bookmaker -a docs/status.json -f fiddleout.json -r site/user/api
$ ./out/dir/bookmaker -a docs/status.json -x
$ ./out/dir/bookmaker -a docs/status.json -p

New Documentation

Generate an starter Bookmaker file from an existing include.

$ ./out/dir/bookmaker -i include/core/SkXXX.h -t docs

If a method or function has an unnamed parameter, bookmaker generates an error:

C:/puregit/include/core/SkPixmap.h(208): error: #Method missing param name
bool erase(const SkColor4f&, const SkIRect* subset = nullptr) const
           ^

All parameters require names to allow markdown and doxygen documents to refer to them. After naming all parameters, check in the include before continuing.

A successful run generates

docs/SkXXX_Reference.bmh

.

Next, use your favorite editor to fill out

docs/SkXXX_Reference.bmh

.

Style

Documentation consists of cross references, descriptions, and examples. All structs, classes, enums, their members and methods, functions, and so on, require descriptions. Most also require examples.

All methods and functions should include examples if practical. It's difficult to think of a meaningful example for class destructors. In cases like these, change the placeholder:

#Example

to:

#NoExample

Descriptions start with an active verb. Descriptions are complete, punctuated sentences unless they describe parameters or return values. Parameters and returned values are described by phrases that start lower case and do not include trailing punctuation.

Descriptions are not self-referential; they do not include the thing they describe. Descriptions may contain upper case or camel case references to definitions but otherwise should be free of jargon.

Descriptions may contain code and formulas, each bracketed by markup.

Similar items may be grouped into topics. Topics may include subtopics.

Each document begins with one or more indices that include the contents of that file. A class reference includes an index listing contained topics, a separate listing for constructors, one for methods, and so on.

Class methods contain a description, any parameters, any return value, an example, and any cross references.

Each method must contain either one or more examples or markup indicating that there is no example.

After editing is complete, searching for "" should fail, assuming "" is not the perfect word to use in a description or example!

Adding Documentation

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.

$ ./out/dir/bookmaker -e fiddle.json -b docs

Once complete, run fiddlecli to generate the example hashes. Errors are contained by the output but aren't reported yet.

$ $GOPATH/bin/fiddlecli --input fiddle.json --output fiddleout.json

Generate 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.

$ ./out/dir/bookmaker -r site/user/api -b docs -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.

$ ./out/dir/bookmaker -x -b docs/SkXXX.bmh -i include/core/SkXXX.h

Generate an updated include header. Run:

$ ./out/dir/bookmaker -p -b docs -i include/core/SkXXX.h

to write the updated SkXXX.h to the current directory.

Once adding the file is complete, add the file to status.json in the Completed section. You may add it to the InProgress section during development, or leave status.json unchanged.

If the new file has been added to status.json, you can run any of the above commands with -a docs/status.json in place of -b docs or -i includes.

Bugs

Bookmaker bugs are tracked here .