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