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