1 usingBookmaker 2 === 3 <a href='usingBookmaker#Bookmaker'>Bookmaker</a> generates markdown files to view documentation on skia.org, and generates includes for use in C++. 4 <a href='usingBookmaker#Bookmaker'>Bookmaker</a> reads canonical documentation from files suffixed with bmh in the docs directory. These bmh 5 files describe how public interfaces work, and generate Skia fiddle examples to illustrate them. 6 7 The docs files must be manually edited to stay current with Skia as it evolves. 8 9 <a name='Installing'></a> 10 11 Install 12 <a href='https://golang.org/doc/install'>Go</a></a> if needed. 13 Check the version. The results should be 1.10 or greater. 14 15 <pre style="padding: 1em 1em 1em 1em;width: 62.5em; background-color: #f0f0f0"> 16 $ go version 17 </pre> 18 19 Get the fiddle command <a href='undocumented#Line'>line</a> interface tool. 20 By default this will appear in your home directory. 21 22 <pre style="padding: 1em 1em 1em 1em;width: 62.5em; background-color: #f0f0f0"> 23 $ go get go.skia.org/infra/fiddlek/go/fiddlecli 24 </pre> 25 26 Check the version. The command should work and the result should be 1.0 or greater. 27 28 <pre style="padding: 1em 1em 1em 1em;width: 62.5em; background-color: #f0f0f0"> 29 $ ~/go/bin/fiddlecli --version 30 </pre> 31 32 If fiddlecli is already installed but out of date, update with: 33 34 <pre style="padding: 1em 1em 1em 1em;width: 62.5em; background-color: #f0f0f0"> 35 $ go get -u go.skia.org/infra/fiddlek/go/fiddlecli 36 </pre> 37 38 Build <a href='usingBookmaker#Bookmaker'>Bookmaker</a>. 39 40 <pre style="padding: 1em 1em 1em 1em;width: 62.5em; background-color: #f0f0f0"> 41 $ ninja -C out/skia <a href='usingBookmaker#Bookmaker'>bookmaker </a> 42 </pre> 43 44 <a name='Running'></a> 45 46 <a href='usingBookmaker#Bookmaker'>Bookmaker</a> extracts examples, generates example hashes with fiddle, and generates web markdown 47 and c++ includes. 48 49 <pre style="padding: 1em 1em 1em 1em;width: 62.5em; background-color: #f0f0f0"> 50 $ ./out/skia/bookmaker -E && ~/go/bin/fiddlecli --quiet && ./out/skia/bookmaker 51 </pre> 52 53 A successful run generates: 54 55 <pre style="padding: 1em 1em 1em 1em;width: 62.5em; background-color: #f0f0f0"> 56 cross-check................... 57 </pre> 58 59 <a name='Broken_Build'></a> 60 61 The bots 62 <a href='https://status.skia.org/repo/skia?filter=search&search_value=Housekeeper-PerCommit-Bookmaker'>Housekeeper-PerCommit-Bookmaker</a></a> and 63 <a href='https://status.skia.org/repo/skia?filter=search&search_value=Housekeeper-Nightly-Bookmaker'>Housekeeper-Nightly-Bookmaker</a></a> verify that <a href='usingBookmaker#Bookmaker'>Bookmaker</a> <a href='undocumented#Data'>data</a> in docs builds without error and is consistent with include files it documents. 64 65 Possible failures include: 66 67 <table> <tr> 68 <td>Public interface in include directory does not match documented interface in docs directory.</td> 69 </tr> <tr> 70 <td>Example in <a href='usingBookmaker#Bookmaker'>bookmaker</a> bmh file does not compile, or does not produce expected output.</td> 71 </tr> <tr> 72 <td>Undocumented but referenced interface is missing from undocumented <a href='usingBookmaker#Bookmaker'>bookmaker</a> file in docs directory.</td> 73 </tr> 74 </table> 75 76 Editing comments in includes or editing private interfaces will not break the bots. 77 <a href='usingBookmaker#Bookmaker'>Bookmaker</a> detects that comments edited in includes do not match comments in docs; it will generate an updated include in the 78 directory where it is run. 79 80 If 81 <a href='https://status.skia.org/repo/skia?filter=search&search_value=Housekeeper-PerCommit-Bookmaker'>Housekeeper-PerCommit-Bookmaker</a></a> bot is red, the error is usually related to an edit to an include which has not been reflected in docs. 82 83 To fix this, edit the docs file corresponding to the changed include file. 84 85 For instance, if the change was made to <a href='SkIRect_Reference#SkIRect'>SkIRect</a>, edit docs/SkIRect_Reference.bmh. 86 Checking in the edited docs/SkIRect_Reference.bmh will fix the bot. 87 88 If the interface is deprecated, private, or experimental, documentation is not 89 required. Put the word "Deprecated", "Private", or "Experimental"; upper or lower 90 case, in a comment just before the symbol to be ignored. 91 92 If 93 <a href='https://status.skia.org/repo/skia?filter=search&search_value=Housekeeper-Nightly-Bookmaker'>Housekeeper-Nightly-Bookmaker</a></a> bot is red, one of several things may have gone wrong: 94 95 <table> <tr> 96 <td>A change to include broke documentation examples.</td> 97 </tr> <tr> 98 <td>Something changed the examples that output <a href='undocumented#Text'>text</a>.</td> 99 </tr> <tr> 100 <td>Some interface was added, deleted, edited.</td> 101 </tr> <tr> 102 <td>Documentation is malformed.</td> 103 </tr> 104 </table> 105 106 The bot output describes what changed, and includes the file and <a href='undocumented#Line'>line</a> 107 where the error occurred. 108 109 To regenerate the documentation, follow the Installing and Regenerate steps below. 110 111 <a name='Editing_Comments'></a> 112 113 Edit docs instead of include/core files to update comments if possible. 114 115 The <a href='usingBookmaker#Bookmaker'>Bookmaker</a> bots do not complain if the docs file does not match the 116 corresponding include comments. Running <a href='usingBookmaker#Bookmaker'>Bookmaker</a> include generation will 117 report when docs and includes comments do not match. 118 119 For instance, if include/core/SkSurface.h comments do not match 120 docs/SkSurface_Reference.bmh, running: 121 122 <pre style="padding: 1em 1em 1em 1em;width: 62.5em; background-color: #f0f0f0"> 123 $ ./out/dir/bookmaker -b docs -i include/core/SkSurface.h -p 124 </pre> 125 126 generates 127 128 <pre style="padding: 1em 1em 1em 1em;width: 62.5em; background-color: #f0f0f0"> 129 wrote updated <a href='SkSurface_Reference#SkSurface'>SkSurface</a>.h 130 </pre> 131 132 The updated <a href='SkSurface_Reference#SkSurface'>SkSurface</a>.h is written to the root to avoid subsequent runs of 133 <a href='usingBookmaker#Bookmaker'>Bookmaker</a> from recompiling. if <a href='SkSurface_Reference#SkSurface'>SkSurface</a>.h was not changed, it is not written, 134 and <a href='usingBookmaker#Bookmaker'>Bookmaker</a> will not generate any output. 135 136 <a name='Broken_Example'></a> 137 138 An example may cause <a href='usingBookmaker#Bookmaker'>Bookmaker</a> or a bot running <a href='usingBookmaker#Bookmaker'>Bookmaker</a> to fail if it fails to compile. 139 140 Fix the example by pasting it into <a href='https://fiddle.skia.org'>Skia Fiddle</a></a> and editing it until it runs successfully. 141 142 If the example cannot be fixed, it can be commented out by changing 143 144 <pre style="padding: 1em 1em 1em 1em;width: 62.5em; background-color: #f0f0f0"> 145 #Example 146 </pre> 147 148 to 149 150 <pre style="padding: 1em 1em 1em 1em;width: 62.5em; background-color: #f0f0f0"> 151 #NoExample 152 </pre> 153 154 . The disabled example can contain additional markup, which will be ignored. 155 156 <a name='Regenerate'></a> 157 158 Complete rebuilding of all <a href='usingBookmaker#Bookmaker'>bookmaker</a> output looks like: 159 160 <pre style="padding: 1em 1em 1em 1em;width: 62.5em; background-color: #f0f0f0"> 161 $ ./out/dir/bookmaker -a docs/status.json -e fiddle.json 162 $ ~/go/bin/fiddlecli --input fiddle.json --output fiddleout.json 163 $ ./out/dir/bookmaker -a docs/status.json -f fiddleout.json -r site/user/api -c 164 $ ./out/dir/bookmaker -a docs/status.json -f fiddleout.json -r site/user/api 165 $ ./out/dir/bookmaker -a docs/status.json -x 166 $ ./out/dir/bookmaker -a docs/status.json -p 167 </pre> 168 169 <a name='New_Documentation'></a> 170 171 Generate an starter <a href='usingBookmaker#Bookmaker'>Bookmaker</a> file from an existing include. 172 173 <pre style="padding: 1em 1em 1em 1em;width: 62.5em; background-color: #f0f0f0"> 174 $ ./out/dir/bookmaker -i include/core/SkXXX.h -t docs 175 </pre> 176 177 If a method or function has an unnamed parameter, <a href='usingBookmaker#Bookmaker'>bookmaker</a> generates an error: 178 179 <pre style="padding: 1em 1em 1em 1em;width: 62.5em; background-color: #f0f0f0"> 180 C:/puregit/include/core/SkPixmap.h(208): error: #Method missing param name 181 bool erase(const <a href='SkColor4f_Reference#SkColor4f'>SkColor4f</a>&, const <a href='SkIRect_Reference#SkIRect'>SkIRect</a>* subset = nullptr) const 182 ^ 183 </pre> 184 185 All parameters require names to allow markdown and doxygen documents to refer to 186 them. After naming all parameters, check in the include before continuing. 187 188 A successful run generates 189 190 <pre style="padding: 1em 1em 1em 1em;width: 62.5em; background-color: #f0f0f0"> 191 docs/SkXXX_Reference.bmh 192 </pre> 193 194 . 195 196 Next, use your favorite editor to fill out 197 198 <pre style="padding: 1em 1em 1em 1em;width: 62.5em; background-color: #f0f0f0"> 199 docs/SkXXX_Reference.bmh 200 </pre> 201 202 . 203 204 <a name='Style'></a> 205 206 Documentation consists of cross references, descriptions, and examples. 207 All structs, classes, enums, their members and methods, functions, and so on, 208 require descriptions. Most also require examples. 209 210 All methods and functions should include examples if practical. 211 It's difficult to think of a meaningful example for class destructors. 212 In cases like these, change the placeholder: 213 214 <pre style="padding: 1em 1em 1em 1em;width: 62.5em; background-color: #f0f0f0"> 215 #Example 216 </pre> 217 218 to: 219 220 <pre style="padding: 1em 1em 1em 1em;width: 62.5em; background-color: #f0f0f0"> 221 #NoExample 222 </pre> 223 224 Descriptions start with an active verb. Descriptions are complete, punctuated 225 sentences unless they describe parameters or return values. Parameters and 226 returned values are described by phrases that start lower case and do not 227 include trailing punctuation. 228 229 Descriptions are not self-referential; they do not include the thing they 230 describe. Descriptions may contain upper case or camel case references to 231 definitions but otherwise should be free of jargon. 232 233 Descriptions may contain code and formulas, each bracketed by markup. 234 235 Similar items may be grouped into topics. Topics may include subtopics. 236 237 Each <a href='undocumented#Document'>document</a> begins with one or more indices that include the contents of 238 that file. A class reference includes an index listing contained topics, 239 a separate listing for constructors, one for methods, and so on. 240 241 Class methods contain a description, any parameters, any return value, 242 an example, and any cross references. 243 244 Each method must contain either one or more examples or markup indicating 245 that there is no example. 246 247 After editing is complete, searching for "incomplete" should fail, 248 assuming "incomplete" is not the perfect word to use in a description or 249 example! 250 251 <a name='Adding_Documentation'></a> 252 253 Generate fiddle.json from all examples, including the ones you just wrote. 254 Error checking is syntatic: starting keywords are closed, keywords have the 255 correct parents. 256 If you run <a href='usingBookmaker#Bookmaker'>Bookmaker</a> inside Visual_Studio, you can click on errors and it 257 will take you to the source <a href='undocumented#Line'>line</a> in question. 258 259 <pre style="padding: 1em 1em 1em 1em;width: 62.5em; background-color: #f0f0f0"> 260 $ ./out/dir/bookmaker -e fiddle.json -b docs 261 </pre> 262 263 Once complete, run fiddlecli to generate the example hashes. 264 Errors are contained by the output but aren't reported yet. 265 266 <pre style="padding: 1em 1em 1em 1em;width: 62.5em; background-color: #f0f0f0"> 267 $ $GOPATH/bin/fiddlecli --input fiddle.json --output fiddleout.json 268 </pre> 269 270 Generate SkXXX.md from SkXXX.bmh and fiddleout.json. 271 Error checking includes: undefined references, fiddle compiler errors, 272 missing or mismatched printf output. 273 Again, you can click on any errors inside Visual_Studio. 274 275 <pre style="padding: 1em 1em 1em 1em;width: 62.5em; background-color: #f0f0f0"> 276 $ ./out/dir/bookmaker -r site/user/api -b docs -f fiddleout.json 277 </pre> 278 279 The original include may have changed since you started creating the markdown. 280 Check to see if it is up to date. 281 This reports if a method no longer exists or its parameters have changed. 282 283 <pre style="padding: 1em 1em 1em 1em;width: 62.5em; background-color: #f0f0f0"> 284 $ ./out/dir/bookmaker -x -b docs/SkXXX.bmh -i include/core/SkXXX.h 285 </pre> 286 287 Generate an updated include header. Run: 288 289 <pre style="padding: 1em 1em 1em 1em;width: 62.5em; background-color: #f0f0f0"> 290 $ ./out/dir/bookmaker -p -b docs -i include/core/SkXXX.h 291 </pre> 292 293 to write the updated SkXXX.h to the current directory. 294 295 Once adding the file is complete, add the file to status.json in the 296 Completed section. You may add it to the InProgress section during 297 development, or leave status.json unchanged. 298 299 If the new file has been added to status.json, you can run 300 any of the above commands with -a docs/status.json in place of 301 -b docs or -i includes. 302 303 <a name='Bugs'></a> 304 305 <a href='usingBookmaker#Bookmaker'>Bookmaker</a> bugs are tracked 306 <a href='https://bug.skia.org/6898'>here</a></a> . 307 308
