Skip to content

Commit 356cb7b

Browse files
edwingamboaedwingamboa
committed
#4 Add site explaining how to add docs
1 parent 1626da9 commit 356cb7b

File tree

3 files changed

+95
-73
lines changed

3 files changed

+95
-73
lines changed

‎docs_dev/.vuepress/config.js

+1
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,7 @@ module.exports = {
5555
]
5656
},
5757
'/developer-guide/vanilla-boilerplate/developing-compounds',
58+
'/developer-guide/vanilla-boilerplate/adding-docs',
5859
'/developer-guide/vanilla-boilerplate/available-scripts',
5960
]
6061
},

‎docs_dev/developer-guide/vanilla-boilerplate/adding-docs.md

+94
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
# Adding documentation to Cubbles components
2+
3+
To show an example of how the webpack configuration can be modified according to your needs. We will add a documentation page to the elementary using a component called `cubx-webpackage-viewer`. To aim that, we just need to provide the following input slots:
4+
5+
* **manifestUrl**: the path of the manifest containing the definition of the component. This path should be according to the final folder structure of the _dist_ folder. In our case, it would be `../manifest.webpackage`
6+
* **componentArtifactId**: artifactId of the elementary. Remember that it is composed by the "name" defined in the _package.json_ file and the name folder containing the elementary. In our case, it would be `my-currency-converter`
7+
8+
We will add a _DOCS.html_ file to the root folder of the elementary. This file will contain the following code:
9+
10+
```html
11+
<!--
12+
This is the generated documentation for your artifact
13+
-->
14+
15+
<!DOCTYPE html>
16+
<html>
17+
<head>
18+
<meta charset="UTF-8">
19+
<title>&lt;<%= elementName %>&gt; generated documentation</title>
20+
<script src="../../[email protected]/webcomponents/custom-elements-es5-adapter.js"></script>
21+
<script src="../../[email protected]/webcomponents/webcomponents-lite.js"></script>
22+
<script src="../../[email protected]/crc-loader/js/main.js" data-crcinit-loadcif="true"></script>
23+
24+
</head>
25+
26+
<body>
27+
<div class="container">
28+
<div class="row">
29+
<h1>&lt;<%= elementName %>&gt; generated documentation</h1>
30+
</div>
31+
<div cubx-core-crc class="row">
32+
<cubx-component-docs-viewer cubx-webpackage-id="[email protected]">
33+
<cubx-core-init style="display:none">
34+
<cubx-core-slot-init slot="manifestUrl">"../manifest.webpackage"</cubx-core-slot-init>
35+
<cubx-core-slot-init slot="componentArtifactId">"<%= elementName %>"</cubx-core-slot-init>
36+
</cubx-core-init>
37+
</cubx-component-docs-viewer>
38+
</div>
39+
</div>
40+
</body>
41+
42+
</html>
43+
```
44+
45+
Note that we are using a template parameter called `<%= elementName %>`. This would allow us to always have the correct artifactId (e.g. if we change the name of the package or o the containing folder). For this to work correctly, we should indicate webpack to process this file. To aim that, you should a new entry to the `plugins` property in the `config` object in the _webpack.subconfig.js_ file. You should indicate webpack to process the _DOCS.html_ file using the [HtmlWebpackPlugin](https://webpack.js.org/plugins/html-webpack-plugin/) with a templateParameter called `elementName` as follows:
46+
47+
```javascript
48+
//...
49+
const config = {
50+
//...
51+
module: {
52+
//...
53+
plugins: [
54+
//..
55+
new HtmlWebpackPlugin({
56+
template: 'DOCS.html',
57+
filename: 'DOCS.html',
58+
// manage placeholders
59+
templateParameters: {
60+
elementName: `${elementName}`
61+
}
62+
}),
63+
]
64+
};
65+
module.exports = config;
66+
```
67+
68+
> Note that you should be familiar with [webpack](https://webpack.js.org/) to be able to modify this kind of configuration
69+
70+
Now, if you run your project (i.e. running the `npm run start` command) and navigate to the DOCS.html file, you should see something similar to:
71+
72+
![currency-converter generated docs](../../assets/images/docs_elementary_bp.png)
73+
74+
Finally, we should add an entry to the runnables array of the artifact manifest file (i.e., Manifest.elementary.js for elementaries and MANIFEST.compound.js for compounds). That will allow us to have a DOCS page available in the [base](../../user-guide/terms-and-concepts/base) where the artifact is hosted.
75+
76+
```javascript
77+
const assert = require("assert");
78+
79+
module.exports = webpackageName => {
80+
assert.ok(webpackageName, 'Expected "webpackageName" to be defined.');
81+
return {
82+
//...
83+
runnables: [
84+
//...
85+
{
86+
name: "DOCS",
87+
path: "/DOCS.html"
88+
}
89+
],
90+
//...
91+
};
92+
};
93+
94+
```

‎docs_dev/developer-guide/vanilla-boilerplate/developing-elementaries/elementary-sample.md

-73
Original file line numberDiff line numberDiff line change
@@ -307,79 +307,6 @@ The `element.js` file handles the behavior of the component when a slot value is
307307

308308
> For this tutorial we won't modify the style of our component. However, you can add style definitions in the file element.sss. Using [sugarss](https://github.com/postcss/sugarss). It could also be a CSS style sheet. Then, you can import the style in the _elementary.js_ file.
309309
310-
## Adding documentation
311-
312-
To show an example of how the webpack configuration can be modified according to your needs. We will add a documentation page to the elementary using a component called `cubx-webpackage-viewer`. To aim that, we just need to provide the following input slots:
313-
314-
* **manifestUrl**: the path of the manifest containing the definition of the component. This path should be according to the final folder structure of the _dist_ folder. In our case, it would be `../manifest.webpackage`
315-
* **componentArtifactId**: artifactId of the elementary. Remember that it is composed by the "name" defined in the _package.json_ file and the name folder containing the elementary. In our case, it would be `my-currency-converter`
316-
317-
We will add a _DOCS.html_ file to the root folder of the elementary. This file will contain the following code:
318-
319-
```html
320-
<!--
321-
This is the generated documentation for your artifact
322-
-->
323-
324-
<!DOCTYPE html>
325-
<html>
326-
<head>
327-
<meta charset="UTF-8">
328-
<title>&lt;<%= elementName %>&gt; generated documentation</title>
329-
<script src="../../[email protected]/webcomponents/custom-elements-es5-adapter.js"></script>
330-
<script src="../../[email protected]/webcomponents/webcomponents-lite.js"></script>
331-
<script src="../../[email protected]/crc-loader/js/main.js" data-crcinit-loadcif="true"></script>
332-
333-
</head>
334-
335-
<body>
336-
<div class="container">
337-
<div class="row">
338-
<h1>&lt;<%= elementName %>&gt; generated documentation</h1>
339-
</div>
340-
<div cubx-core-crc class="row">
341-
<cubx-component-docs-viewer cubx-webpackage-id="[email protected]">
342-
<cubx-core-init style="display:none">
343-
<cubx-core-slot-init slot="manifestUrl">"../manifest.webpackage"</cubx-core-slot-init>
344-
<cubx-core-slot-init slot="componentArtifactId">"<%= elementName %>"</cubx-core-slot-init>
345-
</cubx-core-init>
346-
</cubx-component-docs-viewer>
347-
</div>
348-
</div>
349-
</body>
350-
351-
</html>
352-
```
353-
354-
Note that we are using a template parameter called `<%= elementName %>`. This would allow us to always have the correct artifactId (e.g. if we change the name of the package or o the containing folder). For this to work correctly, we should indicate webpack to process this file. To aim that, you should a new entry to the `plugins` property in the `config` object in the _webpack.subconfig.js_ file. You should indicate webpack to process the _DOCS.html_ file using the [HtmlWebpackPlugin](https://webpack.js.org/plugins/html-webpack-plugin/) with a templateParameter called `elementName` as follows:
355-
356-
```javascript
357-
//...
358-
const config = {
359-
//...
360-
module: {
361-
//...
362-
plugins: [
363-
//..
364-
new HtmlWebpackPlugin({
365-
template: 'DOCS.html',
366-
filename: 'DOCS.html',
367-
// manage placeholders
368-
templateParameters: {
369-
elementName: `${elementName}`
370-
}
371-
}),
372-
]
373-
};
374-
module.exports = config;
375-
```
376-
377-
> Note that you should be familiar with [webpack](https://webpack.js.org/) to be able to modify this kind of configuration
378-
379-
Now, if you run your project (i.e. running the `npm run start` command) and navigate to [http://localhost:4000/my-currency/my-currency-converter/DOCS.html](http://localhost:4000/my-currency/my-currency-converter/DOCS.html), you should see something similar to:
380-
381-
![currency-converter generated docs](../../../assets/images/docs_elementary_bp.png)
382-
383310
## The final result
384311

385312
If you run the project and navigate to the _SHOWROOM.html_ file, you will see something similar to:

0 commit comments

Comments
 (0)