From 52cfb298e3383c37e6cdc7287a1a430c3817654a Mon Sep 17 00:00:00 2001 From: Ryan Waskiewicz Date: Fri, 30 Sep 2022 10:44:24 -0400 Subject: [PATCH] normalize json, readme --- .../documentation-generation/docs-json.md | 43 ++++--------------- .../documentation-generation/docs-readme.md | 28 ++++++++---- 2 files changed, 28 insertions(+), 43 deletions(-) diff --git a/src/docs/documentation-generation/docs-json.md b/src/docs/documentation-generation/docs-json.md index 343c20a52..3aca70304 100644 --- a/src/docs/documentation-generation/docs-json.md +++ b/src/docs/documentation-generation/docs-json.md @@ -14,15 +14,11 @@ contributors: # JSON Docs Generation -While auto-generated readme files formatted with markdown is convenient, there may be scenarios where it'd be better to get all of the docs in the form of json data. To build the docs as json, use the `--docs-json` flag, followed by a path on where to write the json file. +There may be scenarios where it'd be better to get all the docs in the form of JSON. -```tsx - scripts: { - "docs.data": "stencil build --docs-json path/to/docs.json" - } -``` +## Enabling -Another option would be to add the `docs-json` output target to the `stencil.config.ts` in order to auto-generate this file with every build: +To generate JSON documentation, add the `docs-json` output target to the `stencil.config.ts` in order to auto-generate this file with every build: ```tsx import { Config } from '@stencil/core'; @@ -36,35 +32,14 @@ export const config: Config = { ] }; ``` +where `file` is the name & location of the file to be generated. -Check out the typescript declarations for the JSON output: https://github.com/ionic-team/stencil/blob/main/src/declarations/stencil-public-docs.ts +To generate the JSON file, have Stencil build your project. -## Custom JSDocs Tags +Another option would be use the `--docs-json` flag, followed by a path on where to write the json file: -In addition to reading the predefined JSDoc tags, users can provide their own custom tags which also get included in the JSON data. This makes it easier for teams to provide their own documentation and conventions to get built within the JSON data. For example, if we added a comment into our source code like this: - -```tsx -/** - * @myDocTag someName - some value - * @myOtherDocTag someOtherName - some other name - */ - -@Component({ - tag: '...' -}) ... +```bash +stencil build --docs-json path/to/docs.json ``` -It would end up in the JSON data like this: - -```tsx -"docsTags": [ - { - "text": "someName - some value", - "name": "myDocTag" - }, - { - "text": "someOtherName - some other name", - "name": "myOtherDocTag" - } -], -``` +Check out the typescript declarations for the JSON output: https://github.com/ionic-team/stencil/blob/main/src/declarations/stencil-public-docs.ts diff --git a/src/docs/documentation-generation/docs-readme.md b/src/docs/documentation-generation/docs-readme.md index 8fce3f1c8..dc4615c15 100644 --- a/src/docs/documentation-generation/docs-readme.md +++ b/src/docs/documentation-generation/docs-readme.md @@ -11,11 +11,16 @@ contributors: - marcjulian --- -# README.md Docs Generation +# Markdown Docs Generation -Stencil is able to auto-generate `readme.md` files in markdown. This is an opt-in feature and will save the readme files as a sibling to the component within the same directory. When this feature is used it can be useful for others to easily find and read formatted docs about one component. In particular, when a `readme.md` file is placed within a directory on Github, it will default the readme markdown file as the primary content of the page. +Stencil is able to auto-generate `readme.md` files in markdown. +This is an opt-in feature and will save the readme files as a sibling to the component within the same directory. +When this feature is used it can be useful for others to easily find and read formatted docs about one component. +In particular, when a `readme.md` file is placed within a directory on GitHub, it will default the readme markdown file as the primary content of the page. -To auto-generate readme files, add the `docs-readme` output target to your `stencil.config.ts`: +## Enabling + +To generate readme files, add the `docs-readme` output target to your `stencil.config.ts`: ```tsx import { Config } from '@stencil/core'; @@ -33,13 +38,18 @@ Another option would be to use the `--docs` CLI flag, like so: stencil build --docs ``` -This will cause the Stencil compiler to perform a one-time generation of README -files using the [`docs-readme`](https://stenciljs.com/docs/docs-readme) output target. -## Adding Custom Markdown to Auto-Generated Files +This will cause the Stencil compiler to perform a one-time generation of README files. + + +## Customization + +### Adding Custom Markdown to Auto-Generated Files Once you've generated a `readme.md` file you can customize it with your own markdown content. Simply add your own markdown above the comment that reads: ``. -## Custom Footer +## Configuration + +### Custom Footer Removing or customizing the footer can be done by adding a `footer` property to the output target. Markdown can be used to enhance the footer if needed. @@ -56,7 +66,7 @@ export const config: Config = { }; ``` -## Generating to a Directory +### Generating to a Directory By default, a readme file will be generated in its corresponding component directory. This behavior can be changed through the `dir` property of the output target configuration. Specifying a directory will create the structure `{dir}/{component}/readme.md`. @@ -73,7 +83,7 @@ export const config: Config = { }; ``` -## Strict Mode +### Strict Mode Adding `strict: true` to the output target configuration will cause Stencil to output a warning whenever the project is built with missing documentation.