Workflow improvements to component docs
* Add links back to the index page when viewing an example
* On a component's example page, each individual example is in a details tag, so you don't see all the iframes when you load the page. You can click the arrow to expand an individual example.
Note: should land after https://crrev.com/c/2617796 lands else it'll cause some conflicts.
Change-Id: Icd4e3e8b1e836fede9ba00cedb12794691a94138
Reviewed-on: https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/2617797
Commit-Queue: Jack Franklin <jacktfranklin@chromium.org>
Reviewed-by: Tim van der Lippe <tvanderlippe@chromium.org>
diff --git a/scripts/component_server/README.md b/scripts/component_server/README.md
index 8d60b5d..0a312fc 100644
--- a/scripts/component_server/README.md
+++ b/scripts/component_server/README.md
@@ -7,22 +7,32 @@
To add an example for your component:
1. Create `front_end/component_docs/DIR` where `DIR` is the name of your component.
-2. Within the new `DIR`, add HTML files. Each one of these is a standalone example. You should name the HTML file based on what it's documenting, e.g. `basic.html` or `data-missing.html`. This file should import your component and render it with the data you need.
+2. Within the new `DIR`, add HTML and TypeScript files. Each one of these is a standalone example. You should name the HTML file based on what it's documenting, e.g. `basic.html` or `data-missing.html`, and add a TypeScript file with the same name. The TypeScript file should contain all the code to import and run your component, and within the HTML file you can place any HTML or CSS you need (inline style tags are fine for examples) to render the component in the right context.
3. Create a `BUILD.gn` in your new `DIR`. This should contain the following code:
```
import("../../../scripts/build/ninja/copy.gni")
+import("../../../third_party/typescript/typescript.gni")
+
+ts_library("ts") {
+ sources = [
+ "basic.ts"
+ ]
+
+ deps = [
+ # As an example: anything your TS code imports needs to be listed here as a dep.
+ "../../ui/components:bundle",
+ ]
+}
copy_to_gen("elements_breadcrumbs") {
sources = [
- "example1.html",
+ "basic.html",
# list all other examples here
]
deps = [
- # Any dependencies your examples rely on.
- # For example, if they depend on code in the elements module:
- "../../elements"
+ ":ts"
]
}
```
diff --git a/scripts/component_server/server.js b/scripts/component_server/server.js
index 78e56d8..b9aefaf 100644
--- a/scripts/component_server/server.js
+++ b/scripts/component_server/server.js
@@ -49,7 +49,7 @@
});
function createComponentIndexFile(componentPath, componentExamples) {
- const componentName = componentPath.replace('/front_end/component_docs/', '').replace(/_/g, ' ');
+ const componentName = componentPath.replace('/front_end/component_docs/', '').replace(/_/g, ' ').replace('/', '');
// clang-format off
return `<!DOCTYPE html>
<html>
@@ -64,17 +64,40 @@
padding: 5px;
margin: 10px;
}
- iframe { display: block; width: 100%; }
+
+ a:link,
+ a:visited {
+ color: blue;
+ text-decoration: underline;
+ }
+
+ a:hover {
+ text-decoration: none;
+ }
+ .example summary {
+ font-size: 20px;
+ }
+
+ .back-link {
+ padding-left: 5px;
+ font-size: 16px;
+ font-style: italic;
+ }
+
+ iframe { display: block; width: 100%; height: 400px; }
</style>
</head>
<body>
- <h1>${componentName}</h1>
+ <h1>
+ ${componentName}
+ <a class="back-link" href="/">Back to index</a>
+ </h1>
${componentExamples.map(example => {
const fullPath = path.join(componentPath, example);
- return `<div class="example">
- <h3><a href="${fullPath}">${example}</a></h3>
+ return `<details class="example">
+ <summary><a href="${fullPath}">${example.replace('.html', '').replace(/-|_/g, ' ')}</a></summary>
<iframe src="${fullPath}"></iframe>
- </div>`;
+ </details>`;
}).join('\n')}
</body>
</html>`;