[docs] Port markdown to Docsy
This CL lands copies all the documentation in /site into /site2
but also adds frontmatter to each page.
Additionally it adds a Hugo `config.toml` file.
Once the new documentation server is live the original /site
directory will be removed and /site2 will be renamed /site.
Bugs: skia:11799
Change-Id: Ic300cf5c2a2a8fa2f9acc3455251bf818cb96a52
Docs-Preview: https://skia.org/?cl=386116
Reviewed-on: https://skia-review.googlesource.com/c/skia/+/386116
Reviewed-by: Joe Gregorio <jcgregorio@google.com>
diff --git a/site2/docs/dev/tools/_index.md b/site2/docs/dev/tools/_index.md
new file mode 100644
index 0000000..180cef6
--- /dev/null
+++ b/site2/docs/dev/tools/_index.md
@@ -0,0 +1,12 @@
+
+---
+title: "Tools"
+linkTitle: "Tools"
+
+weight: 2
+
+---
+
+
+Developer tools for working in Skia.
+
diff --git a/site2/docs/dev/tools/codesearch.md b/site2/docs/dev/tools/codesearch.md
new file mode 100644
index 0000000..925a90f
--- /dev/null
+++ b/site2/docs/dev/tools/codesearch.md
@@ -0,0 +1,56 @@
+
+---
+title: "Code Search"
+linkTitle: "Code Search"
+
+---
+
+
+There are a number of ways to search the Skia codebase, each with advantages and
+disadvantages.
+
+[cs.skia.org](http://cs.skia.org) redirects to
+[Chromium code search](https://code.google.com/p/chromium/codesearch) restricted
+to the Skia portion of the Chromium tree. You can add a query after the slash;
+e.g. [cs.skia.org/foo](http://cs.skia.org/foo) will search for "foo" within the
+Skia tree. Chromium code search provides cross-references.
+
+For Googlers, there is also the option of [the skia depot](http://cs/#skia/) in
+internal Code Search. In addition to the
+main [skia](http://cs/#skia/skia/) repo, internal Code Search indexes the
+[buildbot](http://cs/#skia/buildbot/), [common](http://cs/#skia/common/),
+and [skia_internal](https://cs/#skia/skia_internal/) repos. However,
+cross-references and code analysis are not available.
+
+The GitHub mirrors of the [skia](https://github.com/google/skia) and
+[skia-buildbot](https://github.com/google/skia-buildbot) repos are useful for
+investigating history and blame, or for exploring release branches or other
+branches. However, the search functionality is fairly limited, cross-references
+are not available, and in history the original committer's username is replaced
+with that person's GitHub username.
+
+You can also navigate through the
+[Skia repos on googlesource.com](https://skia.googlesource.com/). All commits
+appear here first.
+
+ Code search option |Search |XRef |History |Repos |Branches |Freshness
+ --------------------|-------|-----|--------|------------------------------|---------|---------------
+ [cs.skia.org][1] |regexp | yes |yes |skia [buildbot][5] |master |last DEPS roll
+ [Internal][2] |regexp | no |yes |skia buildbot common internal |master |hours
+ [GitHub][3] |basic | no |yes |skia buildbot |all |hour
+ [googlesource][4] |none | no |yes |all |all |N/A
+
+[1]: http://cs.skia.org/ "Chromium code search"
+[2]: http://cs/#skia/ "Internal Code Search"
+[3]: https://github.com/google/skia "GitHub mirror of skia"
+[4]: https://skia.googlesource.com/ "Primary Skia repos on googlesource.com"
+[5]: https://cs.chromium.org/chromium/skia/buildbot/
+
+Client code search
+------------------
+
+There is an [internal tool for
+Googlers](https://goto.google.com/skia-client-search) to make it easier to
+search the repos of Skia clients, e.g. Chromium, Android, and Mozilla. If you
+use it and have suggestions, please let brianosman know.
+
diff --git a/site2/docs/dev/tools/debugger.md b/site2/docs/dev/tools/debugger.md
new file mode 100644
index 0000000..3e21e55
--- /dev/null
+++ b/site2/docs/dev/tools/debugger.md
@@ -0,0 +1,192 @@
+---
+title: 'Skia Debugger'
+linkTitle: 'Skia Debugger'
+---
+
+## Introduction
+
+The Skia Debugger is a graphical tool used to step through and analyze the
+contents of the Skia picture format. The tool is available online at
+[https://debugger.skia.org](https://debugger.skia.org/) or can be run locally.
+
+Features:
+
+- Draw command and multiple frame playback
+- Shows the current clip and matrix at any step
+- Zoomed viewer with crosshair for selecting pixels.
+- Breakpoints that stop playback when a pixel's color changes.
+- GPU or CPU backed execution.
+- GPU op bounds visualization
+- Android offscreen layer visualization
+- Shared resource viewer
+
+<img src="/dev/tools/onlinedebugger.png" style="display: inline-block;" />
+
+## User Guide
+
+SKP files can contain a single frame or multiple frames. Single frame files have
+the .skp extension and Multi-frame files have the .mskp extension. In the online
+debugger linked above, Open a [sample mskp file](/dev/tools/calendar.mskp) or
+capture one from an android device using the
+[instructions here](https://sites.google.com/a/google.com/skia/android/skp-from-framework).
+
+### Command Playback and Filters
+
+Try playing back the commands within the current frame using the lower play
+button <img src="/dev/tools/playcommands.png" style="display: inline-block;" />,
+(the one not in a circle) You should see the image built up one draw at a time.
+
+Many commands manipulate the matrix or clip but don't make any visible change
+when run. Try filtering these out by pasting
+`!drawannotation save restore concat setmatrix cliprect` in to the filter
+textbox just below the command playback controls. Press enter to apply the
+filter, and resume playback if it was paused. This will have the effect of
+making the playback appear to be much faster as there are only 29 commands in
+the first frame of the sample file that pass this filter.
+
+Try pausing command playback and stepping forward and back through the commands
+using `,` (comma) and `.` (period).
+
+> Filters are case insensitive, and the only supported logical operator is !
+> (not) which applies to the entire filter and is only recognised when it occurs
+> at the beginning.
+
+Any command can be expanded using the
+<img src="/dev/tools/expand.png" style="display: inline-block;" /> icon to see
+all of the parameters that were recorded with that command.
+
+Commands can be disabled or enabled with the checkbox that becomes available
+after expanding the command's detail view.
+
+Jog the command playhead to the end of the list with the
+<img src="/dev/tools/end.png" style="display: inline-block;" /> button.
+
+### Frame playback
+
+<img src="/dev/tools/frameplayback.png" style="display: inline-block;" />
+
+The sample file contains multiple frames. Use the encircled play button to play
+back the frames. The current frame is indictated by the slider position, and the
+slider can be set manually. Frames can be stepped through with `w` (back) and
+`s` forward. `p` pauses or unpauses the frame playback.
+
+Not all frames in a file will have the same number of commands. When the command
+playhead is left at the end of the list the debugger will play every frame to
+the end of its list. If the command playhead is somewhere in the middle, say
+155, the debugger will try to play every frame to its 155th command.
+
+### Resources Tab
+
+<img src="/dev/tools/resources.png" style="display: inline-block;" />
+
+Any resources that were referenced by commands in the file appear here. As of
+Dec 2019, this only shows images.
+
+Any resource can be selected and viewed. You may find it helpful to toggle the
+Light/Dark setting if you cannot see an image.
+
+Images' names are formatted as `7 @24205864 (99, 99)` where `7` is the index of
+the image as it was saved in the file, `@24205864` is it's address in wasm
+memory, for cross referencing with DrawImage\* commands in the command list
+which also show this address, and `(99, 99)` is the size of the image.
+
+The resource viewer allows a user to determine if an image was not effectively
+shared between frames or draw commands. If it occurs more than once in the
+resource tab, then there were multiple copies of it with different generation
+ids in the process that recorded the SKP.
+
+### Android Layers
+
+<img src="/dev/tools/layers.png" style="display: inline-block;" />
+
+When MSKPs are recorded in Android, Extra information about offscreen hardware
+layers is recorded. The sample google calendar mskp linked above contains this
+information. You will find two layers on frame 3.
+
+There are two kinds of events relevant to recorded android layer use.
+
+1. Draw Events - points when an offscreen surface was drawn to. They may be
+ complete, meaning the clip equalled the surface's size, or partial, meaning
+ the clip was smaller.
+2. Use events - points when the offscreen surface was used as an SkImage in the
+ main surface.
+
+Layers are shown as boxes in the bottom right of the interface when viewing a
+frame where a layer draw event occurred. Each Layer box has two buttons:
+`Show Use` will cycle through use events for that layer in the current frame if
+there are any, and `Inspector` will open the draw event as if it were a single
+frame SKP. you can play back it's commands, enable or disabled them, inspect GPU
+op bounds or anything else you could do with an ordinary SKP. Exit the inspector
+by clicking the `Exit` button on the layer box.
+
+### Crosshair and Breakpoints
+
+<img src="/dev/tools/crosshair.png" style="display: inline-block;" />
+
+Clicking any point in the main view will toggle a red crosshair for selecting
+pixels. the selected pixel's color is shown in several formats on the right
+pane. A zoomed view centered on the selected pixel is shown below it. The
+position can be moved precicely by either clicking neighboring pixels in the
+zoom view, or using `H` (left) `L` (right) `J` (down) `K` (up).
+
+When "Break on change" is selected, command playback will pause on any command
+which changes the color of the selected pixel. this can be used to find the
+command that draws something you see in the viewer.
+
+### GPU Op Bounds and Other settings
+
+<img src="/dev/tools/settings.png" style="display: inline-block;" />
+
+Each of the filtered commands from above has a colored number to its right
+<img src="/dev/tools/gpuop.png" style="display: inline-block;" />. This is the
+GPU operation id. When multiple commands share a GPU op id, this indicates that
+they were batched together when sent to the GPU. In the WASM debugger, this goes
+though WebGL.
+
+There is a "Display GPU Op Bounds" toggle in the upper right of the interface.
+Turning this on will show a colored rectangle to represent the bounds of the GPU
+op of the currently selected command.
+
+GPU - Controls which backend Skia uses to draw to the screen. GPU in the online
+wasm debugger means WebGL. CPU means skia draws into a surface in memory which
+is copied into an HTML canvas without using the GPU.
+
+Light/Dark - this toggle changes the appearance of the checkerboard behind the
+main view and zoom views to assist in viewing content with transparency.
+
+Display Overdraw Viz - This vizualization shows a red overlay that is darker in
+propertion to how much overdraw has occurred on a pixel. Overdraw meaning that
+the pixel was drawn to more than once.
+
+- As of Dec 2019, this feature may not be working correctly.
+
+### Image fit and download buttons.
+
+<img src="/dev/tools/settings.png" style="display: inline-block;" />
+
+These buttons resize the main view. they are, from left to right:
+
+Original size - the natural size of the canvas, when it was recorded. Fit to
+page - shrink enough that the whole canvas fits in the center pane. Fit to page
+width - make the canvas fit horizontally but allow scrolling vertically Fit to
+page height - make the canvas fit vertically but allow scrolling horizontally.
+
+next to these is a 5th, unrelated download button which saves the current canvas
+as a PNG file.
+
+## Building and running locally
+
+Begin by following the instructions to
+[download and build Skia](../../user/quick), then simply build and run the
+`skiaserve` tool:
+
+<!--?prettify lang=sh?-->
+
+ # Build.
+ ninja -C out/Release skiaserve
+
+ # Run the debugger locally
+ out/Release/skiaserve
+
+After running `skiaserve`, follow the instructions to open the debugger in your
+local browser. By default the address will be `http://127.0.0.1:8888`.
diff --git a/site2/docs/dev/tools/debugvis.md b/site2/docs/dev/tools/debugvis.md
new file mode 100644
index 0000000..09ee7dd
--- /dev/null
+++ b/site2/docs/dev/tools/debugvis.md
@@ -0,0 +1,18 @@
+
+---
+title: "Debug Visualization"
+linkTitle: "Debug Visualization"
+
+---
+
+
+Skia uses custom container types, such as `SkString` and `SkTArray<>`, which can
+be inconvenient to view in a debugger.
+
+If you frequently debug code that uses Skia types, consider installing a debug
+visualizer. Skia offers debugger visualization support for the following
+platforms:
+
+- [Visual Studio and VS Code](https://skia.googlesource.com/skia/+/refs/heads/master/platform_tools/debugging/vs/Skia.natvis)
+- [LLDB and Xcode](https://skia.googlesource.com/skia/+/refs/heads/master/platform_tools/debugging/lldb/skia.py)
+
diff --git a/site2/docs/dev/tools/markdown.md b/site2/docs/dev/tools/markdown.md
new file mode 100644
index 0000000..732da88
--- /dev/null
+++ b/site2/docs/dev/tools/markdown.md
@@ -0,0 +1,52 @@
+---
+title: 'Markdown'
+linkTitle: 'Markdown'
+---
+
+This site is build with [Hugo](https://gohugo.io/) and
+[Docsy](https://www.docsy.dev/).
+
+Any file you put under `/site/` that has the extension `.md` will be processed
+as Markdown. All other files will be served directly. For example, images can be
+added and they will be served correctly and referenced from within Markdown
+files.
+
+When preparing for a code review of site docs you can get a preview of how the
+page will render by visiting the skia.org site and add a query parameter `cl`
+with the value of the Reitveld issue id:
+
+ https://skia.org/path/to/markdown-file?cl=REITVELD_ISSUE_NUMBER
+
+See the [Docsy documentation](https://www.docsy.dev/docs/) for more details on
+how to configure and use docsy. For example the
+[Navigation](https://www.docsy.dev/docs/adding-content/navigation/) section
+explains what frontmatter needs to be added to a page to get it to appear in the
+top navigation bar.
+
+## Frontmatter
+
+Each page needs a frontmatter section that provides information on that page.
+For example:
+
+```
+---
+title: 'Markdown'
+linkTitle: 'Markdown'
+---
+```
+
+This is true for both Markdown and HTML pages. See
+[the Docsy documentation on frontmatter](https://www.docsy.dev/docs/adding-content/content/#page-frontmatter)
+for more details.
+
+## Styling And Icons
+
+Docsy supports both
+[Bootstrap](https://getbootstrap.com/docs/5.0/getting-started/introduction/) and
+[Font-Awesome](https://fontawesome.com/). Check out their documentation for what
+they offer.
+
+## Configuration
+
+The Hugo configuration file is [config.toml](../../../config.toml) in the site
+directory.
diff --git a/site2/docs/dev/tools/tracing.md b/site2/docs/dev/tools/tracing.md
new file mode 100644
index 0000000..ad7057c
--- /dev/null
+++ b/site2/docs/dev/tools/tracing.md
@@ -0,0 +1,115 @@
+
+---
+title: "Tracing Skia Execution"
+linkTitle: "Tracing Skia Execution"
+
+---
+
+
+Introduction
+------------
+
+Skia is instrumented to provide execution traces in several ways. Within Chrome, Skia is traced
+with the standard [tracing interface](chrome://tracing), along with the rest of Chromium. In
+the Android framework, Skia's tracing is integrated into
+[atrace](https://source.android.com/devices/tech/debug/ftrace).
+
+For standalone builds, Skia's tools (DM, nanobench, and Viewer) are capable of tracing execution
+in three ways, controlled by the `--trace` command line argument.
+
+Standalone Tracing
+------------------
+
+Most arguments to `--trace` will be interpreted as a filename (the two exceptions are described
+below), and trace events will be written to that file in JSON format, suitable for viewing with
+[chrome://tracing](chrome://tracing).
+
+<!--?prettify lang=sh?-->
+
+ # Run DM on several GMs to get tracing data
+ out/Release/dm --config gl --match bleed --trace gl_bleed_gms.json
+
+This creates a file `gl_bleed_gms.json` in the current directory. There are limitations in Chrome's
+tracing tool that prevent loading a file larger than 256 MB. To stay under that limit (and avoid
+clutter and slowdown in the interface), it's best to run a small number of tests/benchmarks when
+tracing. Once you have generated a file in this way, go to
+[chrome://tracing](chrome://tracing), click Load:
+
+
+
+... then select the JSON file. The data will be loaded and can be navigated/inspected using the
+tracing tools. Tip: press '?' for a help screen explaining the available keyboard and mouse
+controls.
+
+
+
+Android ATrace
+--------------
+
+Running any tool with `--trace atrace` on an Android device will cause the application to forward
+tracing information to [atrace](https://source.android.com/devices/tech/debug/ftrace). On other
+platforms, this has no effect.
+
+If you run `systrace` from the host command line, you will need to supply `-a <app_name>`,
+and the `<app_name>` argument will need to exactly match the command line used on the target
+device. For example, if you use `adb shell "cd /data/local/tmp; ./nanobench --trace atrace ..."`
+you must pass `-a ./nanobench` or systrace will ignore events from the application.
+
+Console Logging
+---------------
+
+For simple situations, all tracing events can be directed to the console with `--trace debugf`:
+
+<!--?prettify lang=sh?-->
+
+ # Run DM on a single GM with SkDebugf tracing
+ out/Release/dm --config gl --match ^gamma$ --trace debugf
+
+~~~
+[ 0] <skia.gpu> GrDrawingManager::internalFlush id=1 #0 {
+[ 0] } GrDrawingManager::internalFlush
+[ 0] <skia.gpu> GrGpu::createTexture id=1 #1 {
+[ 0] } GrGpu::createTexture
+[ 0] <skia.gpu> GrRenderTargetContext::discard id=1 #2 {
+[ 0] } GrRenderTargetContext::discard
+[ 0] <skia.gpu> SkGpuDevice::clearAll id=1 #3 {
+[ 1] <skia.gpu> GrRenderTargetContext::clear id=1 #4 {
+[ 1] } GrRenderTargetContext::clear
+[ 0] } SkGpuDevice::clearAll
+[ 0] <skia> SkCanvas::drawRect() #5 {
+[ 1] <skia.gpu> SkGpuDevice::drawRect id=1 #6 {
+[ 2] <skia.gpu> GrRenderTargetContext::drawRect id=1 #7 {
+[ 3] <skia.gpu> GrRenderTargetContext::addDrawOp id=1 #8 {
+[ 3] } GrRenderTargetContext::addDrawOp
+[ 2] } GrRenderTargetContext::drawRect
+[ 1] } SkGpuDevice::drawRect
+[ 0] } SkCanvas::drawRect()
+...
+~~~
+
+Adding More Trace Events
+------------------------
+
+Adding more trace events involves using a set of `TRACE_` macros. The simplest example, to record
+the time spent in a function or other scope, is:
+
+~~~
+#include "SkTraceEvent.h"
+...
+void doSomething() {
+ // Add an event for the duration of the current function (or other scope)
+ // "skia" is a category name, for filtering events while recording
+ // TRACE_FUNC is the event name, and expands to the name of the current function
+ TRACE_EVENT0("skia", TRACE_FUNC);
+
+ if (doExtraWork) {
+ TRACE_EVENT0("skia", "ExtraWorkBeingDone");
+ ...
+ }
+}
+~~~
+
+For more examples, including other kinds of trace events and attaching parameters to events, see
+the comments in
+[SkTraceEventCommon.h](https://cs.chromium.org/chromium/src/third_party/skia/src/core/SkTraceEventCommon.h).
+