From 70d96002ac8e2c60b3345afd4e399135ad5b6a05 Mon Sep 17 00:00:00 2001 From: Adam Harvey Date: Tue, 16 Mar 2021 22:38:33 -0400 Subject: [PATCH 1/6] Update example documentation Signed-off-by: Adam Harvey --- .../docs/code/code-sample.md | 11 ++- .../documented-component/docs/extensions.md | 77 +++++++++++++++++++ .../documented-component/docs/index.md | 18 +++-- .../examples/documented-component/mkdocs.yml | 1 + 4 files changed, 101 insertions(+), 6 deletions(-) create mode 100644 plugins/techdocs-backend/examples/documented-component/docs/extensions.md diff --git a/plugins/techdocs-backend/examples/documented-component/docs/code/code-sample.md b/plugins/techdocs-backend/examples/documented-component/docs/code/code-sample.md index ed430edb15..c40474cf48 100644 --- a/plugins/techdocs-backend/examples/documented-component/docs/code/code-sample.md +++ b/plugins/techdocs-backend/examples/documented-component/docs/code/code-sample.md @@ -4,7 +4,7 @@ This page provides some sample code which may be used in your example component. This code uses TypeScript, and the Markdown code fence to wrap the code. -```tsx +```typescript const DefaultEntityPage = ({ entity }: { entity: Entity }) => ( ( ); ``` + +Here is an example of Python code: + +```python +def getUsersInGroup( targetGroup, secure = False ): + + if __debug__: + print ('targetGroup=[' + targetGroup + ']') +``` diff --git a/plugins/techdocs-backend/examples/documented-component/docs/extensions.md b/plugins/techdocs-backend/examples/documented-component/docs/extensions.md new file mode 100644 index 0000000000..cbc7e42f19 --- /dev/null +++ b/plugins/techdocs-backend/examples/documented-component/docs/extensions.md @@ -0,0 +1,77 @@ +# Plugins & Extensions + +Just by including the TechDocs Core Plugin to your MkDocs site included with Backstage, you gain the immediate use of a variety of popular plugins and extensions to MkDocs. + +For more information and full details of the available features, see the [`mkdocs-techdocs-core` repository](https://github.com/backstage/mkdocs-techdocs-core#mkdocs-plugins-and-extensions). + +This page provides a demonstration of some of the available features. + +## Admonitions + +Admonitions are call outs that help catch a users attention. + +To define an admonition simply put the following Markdown into your content: + +``` +!!! warn + Defining admonitions can be addicting. +``` + +And they end up looking like this: + +!!! warn +Defining admonitions can be addicting. + +!!! note +You can learn a lot about TechDocs by just visiting the Backstage web site at https://backstage.io/docs. + +!!! info +TechDocs is the core feature that supports documentation as code in Backstage. + +!!! tip +Don't forget to spell check your documentation. + +## PlantUML + +You can create dynamic UML diagrams on the fly by just specifying flow via text, using [PlantUML](https://pypi.org/project/plantuml-markdown/). + +```plantuml format="svg" classes="uml myDiagram" alt="Backstage sample PlantUML" title="Backstage sample PlantUML" width="500px" height="250px" +User -> SCMProvider: stores +TechDocs -> SCMProvider: prepares +TechDocs -> TechDocs: generates +TechDocs -> CloudStorage: publishes +CloudStorage -> Backstage: displays +``` + +## Pymdown Extensions + +Pymdown extensions are a variety of smaller additions. + +### Details + +??? note "What is the answer to life, the universe, and everything? (click me for the answer)" +The answer is 42. + +??? note "What is 4 plus 4?" +The answer is 8. + +???+ note "How do I get support?" +You can get support by opening an issue in this repository. This detail is open by default so it's more easily visible without requiring the user to click to open it. + +### Task Lists + +Automatic rendering of Markdown task lists. + +- [x] Phase 1 +- [x] Phase 2 +- [ ] Phase 3 + +### Emojis + +Very nice job on documentation! :thumbsup: + +I've read a lot of documentation, but I love :heart: this document. + +Weather: :sunny: :umbrella: :cloud: :snowflake: + +Animals: :tiger: :horse: :turtle: :wolf: :frog: diff --git a/plugins/techdocs-backend/examples/documented-component/docs/index.md b/plugins/techdocs-backend/examples/documented-component/docs/index.md index 5a9c23d9f6..44a11abe4d 100644 --- a/plugins/techdocs-backend/examples/documented-component/docs/index.md +++ b/plugins/techdocs-backend/examples/documented-component/docs/index.md @@ -1,17 +1,25 @@ # Welcome! -This is a basic example of documentation. +This is a basic example of documentation. It is intended as a showcase of some of the features that TechDocs provides out of the box. + +You can see also: + +- [A sub page](sub-page.md) +- [Inline code examples](code/code-sample.md) +- [Plugin & Extension examples](extensions.md) - Diagrams, emojis, visual formatting. + +## Basic Markdown Here is a bulleted list: - Item one - Item two -- Item three +- Item Three Check out the [Markdown Guide](https://www.markdownguide.org/) to learn more about how to simply create documentation. -You can also learn more about how to configure and setup this documentation in Backstage by -[reading up on the TechDocs Overview](https://backstage.io/docs/features/techdocs/techdocs-overview). +You can also learn more about how to configure and setup this documentation in Backstage, +[read up on the TechDocs Overview](https://backstage.io/docs/features/techdocs/techdocs-overview). ## Image Example @@ -25,6 +33,6 @@ While this documentation isn't comprehensive, in the future it should cover the | Topic | Description | | ------- | ------------------------------------------------------------ | -| Topic 1 | An introductory topic to help you learn about the component. | +| Topic 1 | An introductory topic to help you learn about the topic. | | Topic 2 | A more detailed topic that explains more information. | | Topic 3 | A final topic that provides conclusions and lessons learned. | diff --git a/plugins/techdocs-backend/examples/documented-component/mkdocs.yml b/plugins/techdocs-backend/examples/documented-component/mkdocs.yml index 4c7d018690..2087979d22 100644 --- a/plugins/techdocs-backend/examples/documented-component/mkdocs.yml +++ b/plugins/techdocs-backend/examples/documented-component/mkdocs.yml @@ -4,6 +4,7 @@ nav: - Home: index.md - Subpage: sub-page.md - 'Code Sample': code/code-sample.md + - Extensions: extensions.md plugins: - techdocs-core From 74e0e12e41ed6bc055975aad25c46abb0c699017 Mon Sep 17 00:00:00 2001 From: Adam Harvey Date: Tue, 16 Mar 2021 22:48:59 -0400 Subject: [PATCH 2/6] Update text Signed-off-by: Adam Harvey --- .../examples/documented-component/docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/techdocs-backend/examples/documented-component/docs/index.md b/plugins/techdocs-backend/examples/documented-component/docs/index.md index 44a11abe4d..dd3d3da6fa 100644 --- a/plugins/techdocs-backend/examples/documented-component/docs/index.md +++ b/plugins/techdocs-backend/examples/documented-component/docs/index.md @@ -33,6 +33,6 @@ While this documentation isn't comprehensive, in the future it should cover the | Topic | Description | | ------- | ------------------------------------------------------------ | -| Topic 1 | An introductory topic to help you learn about the topic. | +| Topic 1 | An introductory topic to help you learn about the component. | | Topic 2 | A more detailed topic that explains more information. | | Topic 3 | A final topic that provides conclusions and lessons learned. | From 8efa047a6bd056005f5a745e7a9a0f270dc5da1f Mon Sep 17 00:00:00 2001 From: Adam Harvey Date: Tue, 16 Mar 2021 22:50:12 -0400 Subject: [PATCH 3/6] Wrap lines Signed-off-by: Adam Harvey --- .../documented-component/docs/extensions.md | 15 ++++++++++----- .../examples/documented-component/docs/index.md | 9 ++++++--- .../documented-component/docs/sub-page.md | 3 ++- 3 files changed, 18 insertions(+), 9 deletions(-) diff --git a/plugins/techdocs-backend/examples/documented-component/docs/extensions.md b/plugins/techdocs-backend/examples/documented-component/docs/extensions.md index cbc7e42f19..5447d14d51 100644 --- a/plugins/techdocs-backend/examples/documented-component/docs/extensions.md +++ b/plugins/techdocs-backend/examples/documented-component/docs/extensions.md @@ -1,8 +1,10 @@ # Plugins & Extensions -Just by including the TechDocs Core Plugin to your MkDocs site included with Backstage, you gain the immediate use of a variety of popular plugins and extensions to MkDocs. +Just by including the TechDocs Core Plugin to your MkDocs site included with Backstage, +you gain the immediate use of a variety of popular plugins and extensions to MkDocs. -For more information and full details of the available features, see the [`mkdocs-techdocs-core` repository](https://github.com/backstage/mkdocs-techdocs-core#mkdocs-plugins-and-extensions). +For more information and full details of the available features, see the +[`mkdocs-techdocs-core` repository](https://github.com/backstage/mkdocs-techdocs-core#mkdocs-plugins-and-extensions). This page provides a demonstration of some of the available features. @@ -23,7 +25,8 @@ And they end up looking like this: Defining admonitions can be addicting. !!! note -You can learn a lot about TechDocs by just visiting the Backstage web site at https://backstage.io/docs. +You can learn a lot about TechDocs by just visiting the Backstage web site at +https://backstage.io/docs. !!! info TechDocs is the core feature that supports documentation as code in Backstage. @@ -33,7 +36,8 @@ Don't forget to spell check your documentation. ## PlantUML -You can create dynamic UML diagrams on the fly by just specifying flow via text, using [PlantUML](https://pypi.org/project/plantuml-markdown/). +You can create dynamic UML diagrams on the fly by just specifying flow via text, +using [PlantUML](https://pypi.org/project/plantuml-markdown/). ```plantuml format="svg" classes="uml myDiagram" alt="Backstage sample PlantUML" title="Backstage sample PlantUML" width="500px" height="250px" User -> SCMProvider: stores @@ -56,7 +60,8 @@ The answer is 42. The answer is 8. ???+ note "How do I get support?" -You can get support by opening an issue in this repository. This detail is open by default so it's more easily visible without requiring the user to click to open it. +You can get support by opening an issue in this repository. This detail is open by default +so it's more easily visible without requiring the user to click to open it. ### Task Lists diff --git a/plugins/techdocs-backend/examples/documented-component/docs/index.md b/plugins/techdocs-backend/examples/documented-component/docs/index.md index dd3d3da6fa..48a903445a 100644 --- a/plugins/techdocs-backend/examples/documented-component/docs/index.md +++ b/plugins/techdocs-backend/examples/documented-component/docs/index.md @@ -1,6 +1,7 @@ # Welcome! -This is a basic example of documentation. It is intended as a showcase of some of the features that TechDocs provides out of the box. +This is a basic example of documentation. It is intended as a showcase of some of the +features that TechDocs provides out of the box. You can see also: @@ -16,7 +17,8 @@ Here is a bulleted list: - Item two - Item Three -Check out the [Markdown Guide](https://www.markdownguide.org/) to learn more about how to simply create documentation. +Check out the [Markdown Guide](https://www.markdownguide.org/) to learn more about how to +simply create documentation. You can also learn more about how to configure and setup this documentation in Backstage, [read up on the TechDocs Overview](https://backstage.io/docs/features/techdocs/techdocs-overview). @@ -29,7 +31,8 @@ This documentation is powered by Backstage's TechDocs feature: ## Table Example -While this documentation isn't comprehensive, in the future it should cover the following topics outlined in this example table: +While this documentation isn't comprehensive, in the future it should cover the following +topics outlined in this example table: | Topic | Description | | ------- | ------------------------------------------------------------ | diff --git a/plugins/techdocs-backend/examples/documented-component/docs/sub-page.md b/plugins/techdocs-backend/examples/documented-component/docs/sub-page.md index 8e1870c7b4..987f5e8a95 100644 --- a/plugins/techdocs-backend/examples/documented-component/docs/sub-page.md +++ b/plugins/techdocs-backend/examples/documented-component/docs/sub-page.md @@ -4,7 +4,8 @@ This sub-page can be used to elaborate on a specific part of the component. ## Details -It is linked off the main page, and due to its inclusion in the `mkdocs.yml` file, becomes part of the auto-generated site navigation. +It is linked off the main page, and due to its inclusion in the `mkdocs.yml` file, +becomes part of the auto-generated site navigation. ## MkDocs From 22e97483c4678c067407307380eeaf2e9c8f8332 Mon Sep 17 00:00:00 2001 From: Adam Harvey Date: Tue, 16 Mar 2021 22:58:20 -0400 Subject: [PATCH 4/6] Add emoji Signed-off-by: Adam Harvey --- .github/styles/vocab.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/styles/vocab.txt b/.github/styles/vocab.txt index 8a3ebd180f..994fc9335b 100644 --- a/.github/styles/vocab.txt +++ b/.github/styles/vocab.txt @@ -266,6 +266,7 @@ templated templater templaters theia +thumbsup toc tolerations toolchain From 2ef9ac9d83bbfd107755b20ea9c84a0d97c84927 Mon Sep 17 00:00:00 2001 From: Adam Harvey Date: Tue, 16 Mar 2021 22:58:47 -0400 Subject: [PATCH 5/6] Change wording for spelling alignment Signed-off-by: Adam Harvey --- .../examples/documented-component/docs/extensions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/techdocs-backend/examples/documented-component/docs/extensions.md b/plugins/techdocs-backend/examples/documented-component/docs/extensions.md index 5447d14d51..a2b02ec866 100644 --- a/plugins/techdocs-backend/examples/documented-component/docs/extensions.md +++ b/plugins/techdocs-backend/examples/documented-component/docs/extensions.md @@ -47,9 +47,9 @@ TechDocs -> CloudStorage: publishes CloudStorage -> Backstage: displays ``` -## Pymdown Extensions +## Pymdownx Extensions -Pymdown extensions are a variety of smaller additions. +Pymdownx (Python Markdown extensions) are a variety of smaller additions. ### Details From 9b3a205303bc3b11aafbdc702b59e22648a4eeda Mon Sep 17 00:00:00 2001 From: Adam Harvey Date: Wed, 17 Mar 2021 11:23:08 -0400 Subject: [PATCH 6/6] PIP8 alignment Signed-off-by: Adam Harvey --- .../examples/documented-component/docs/code/code-sample.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/techdocs-backend/examples/documented-component/docs/code/code-sample.md b/plugins/techdocs-backend/examples/documented-component/docs/code/code-sample.md index c40474cf48..9f8e1bd739 100644 --- a/plugins/techdocs-backend/examples/documented-component/docs/code/code-sample.md +++ b/plugins/techdocs-backend/examples/documented-component/docs/code/code-sample.md @@ -24,8 +24,8 @@ const DefaultEntityPage = ({ entity }: { entity: Entity }) => ( Here is an example of Python code: ```python -def getUsersInGroup( targetGroup, secure = False ): +def getUsersInGroup(targetGroup, secure=False): if __debug__: - print ('targetGroup=[' + targetGroup + ']') + print('targetGroup=[' + targetGroup + ']') ```