From 605b6916cf153ea41106e3a09ef4b33fd42abc4f Mon Sep 17 00:00:00 2001 From: "Stephen A. Wilson" Date: Thu, 13 Jun 2024 10:58:22 -0400 Subject: [PATCH] Allow for searching TechDocs by Title Signed-off-by: Stephen A. Wilson --- .changeset/fuzzy-socks-do.md | 6 + app-config.yaml | 3 + .../catalog-info.yaml | 12 ++ .../docs/code/code-sample.md | 31 +++++ .../docs/extensions.md | 112 ++++++++++++++++++ .../docs/images/backstage-logo-cncf.svg | 1 + .../docs/index.md | 55 +++++++++ .../docs/sub-page.md | 12 ++ .../mkdocs.yml | 12 ++ .../src/home/components/Tables/DocsTable.tsx | 1 + .../src/home/components/Tables/columns.tsx | 34 +++++- 11 files changed, 274 insertions(+), 5 deletions(-) create mode 100644 .changeset/fuzzy-socks-do.md create mode 100644 plugins/techdocs-backend/examples/documented-component-with-title/catalog-info.yaml create mode 100644 plugins/techdocs-backend/examples/documented-component-with-title/docs/code/code-sample.md create mode 100644 plugins/techdocs-backend/examples/documented-component-with-title/docs/extensions.md create mode 100644 plugins/techdocs-backend/examples/documented-component-with-title/docs/images/backstage-logo-cncf.svg create mode 100644 plugins/techdocs-backend/examples/documented-component-with-title/docs/index.md create mode 100644 plugins/techdocs-backend/examples/documented-component-with-title/docs/sub-page.md create mode 100644 plugins/techdocs-backend/examples/documented-component-with-title/mkdocs.yml diff --git a/.changeset/fuzzy-socks-do.md b/.changeset/fuzzy-socks-do.md new file mode 100644 index 0000000000..02d2e4dca9 --- /dev/null +++ b/.changeset/fuzzy-socks-do.md @@ -0,0 +1,6 @@ +--- +'@backstage/plugin-techdocs-backend': patch +'@backstage/plugin-techdocs': patch +--- + +Allow for searching TechDocs by entity title diff --git a/app-config.yaml b/app-config.yaml index cb70170541..69145cd896 100644 --- a/app-config.yaml +++ b/app-config.yaml @@ -297,6 +297,9 @@ catalog: # Example component for TechDocs - type: file target: ../../plugins/techdocs-backend/examples/documented-component/catalog-info.yaml + # Example component for TechDocs with a title + - type: file + target: ../../plugins/techdocs-backend/examples/documented-component-with-title/catalog-info.yaml # Example component for ADRs - type: file target: ../../plugins/adr/examples/component/catalog-info.yaml diff --git a/plugins/techdocs-backend/examples/documented-component-with-title/catalog-info.yaml b/plugins/techdocs-backend/examples/documented-component-with-title/catalog-info.yaml new file mode 100644 index 0000000000..1a1d65ba39 --- /dev/null +++ b/plugins/techdocs-backend/examples/documented-component-with-title/catalog-info.yaml @@ -0,0 +1,12 @@ +apiVersion: backstage.io/v1alpha1 +kind: Component +metadata: + name: documented-with-title + title: Fizzbuzz Docs + description: A TechDocs with a title different than it's name + annotations: + backstage.io/techdocs-ref: dir:. +spec: + type: service + lifecycle: experimental + owner: user:guest diff --git a/plugins/techdocs-backend/examples/documented-component-with-title/docs/code/code-sample.md b/plugins/techdocs-backend/examples/documented-component-with-title/docs/code/code-sample.md new file mode 100644 index 0000000000..f41ab1d506 --- /dev/null +++ b/plugins/techdocs-backend/examples/documented-component-with-title/docs/code/code-sample.md @@ -0,0 +1,31 @@ +# Sample Code + +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. + +```typescript +const serviceEntityPage = ( + + + + + + + + + + + + +); +``` + +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-with-title/docs/extensions.md b/plugins/techdocs-backend/examples/documented-component-with-title/docs/extensions.md new file mode 100644 index 0000000000..eb9abca74a --- /dev/null +++ b/plugins/techdocs-backend/examples/documented-component-with-title/docs/extensions.md @@ -0,0 +1,112 @@ +# 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 +``` + +## Pymdownx Extensions + +Pymdownx (Python Markdown 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: + +### Attributes + +[A Download Link](./images/backstage-logo-cncf.svg){: download } + +![A Scaled Image](./images/backstage-logo-cncf.svg){: style="width: 100px" } + +### MDX truly sane lists + +- `attributes` + +- `customer` + - `first_name` + - `test` + - `family_name` + - `email` +- `person` + - `first_name` + - `family_name` + - `birth_date` +- `subscription_id` + +- `request` diff --git a/plugins/techdocs-backend/examples/documented-component-with-title/docs/images/backstage-logo-cncf.svg b/plugins/techdocs-backend/examples/documented-component-with-title/docs/images/backstage-logo-cncf.svg new file mode 100644 index 0000000000..b5ff591d1b --- /dev/null +++ b/plugins/techdocs-backend/examples/documented-component-with-title/docs/images/backstage-logo-cncf.svg @@ -0,0 +1 @@ +05 Logo_Black \ No newline at end of file diff --git a/plugins/techdocs-backend/examples/documented-component-with-title/docs/index.md b/plugins/techdocs-backend/examples/documented-component-with-title/docs/index.md new file mode 100644 index 0000000000..6295a69406 --- /dev/null +++ b/plugins/techdocs-backend/examples/documented-component-with-title/docs/index.md @@ -0,0 +1,55 @@ +# 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. + +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 + +Headings: + +# h1 + +## h2 + +### h3 + +#### h4 + +##### h5 + +###### h6 + +Here is a bulleted list: + +- Item one +- Item two +- 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, +[read up on the TechDocs Overview](https://backstage.io/docs/features/techdocs/). + +## Image Example + +This documentation is powered by Backstage's TechDocs feature: + +![Backstage Logo](images/backstage-logo-cncf.svg) + +## Table Example + +While this documentation isn't comprehensive, in the future it should cover the following +topics outlined in this example table: + +| Topic | Description | +| ------- | ------------------------------------------------------------ | +| 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. | diff --git a/plugins/techdocs-backend/examples/documented-component-with-title/docs/sub-page.md b/plugins/techdocs-backend/examples/documented-component-with-title/docs/sub-page.md new file mode 100644 index 0000000000..987f5e8a95 --- /dev/null +++ b/plugins/techdocs-backend/examples/documented-component-with-title/docs/sub-page.md @@ -0,0 +1,12 @@ +# Another page in our documentation + +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. + +## MkDocs + +Visit https://www.mkdocs.org for more information about the MkDocs tool. diff --git a/plugins/techdocs-backend/examples/documented-component-with-title/mkdocs.yml b/plugins/techdocs-backend/examples/documented-component-with-title/mkdocs.yml new file mode 100644 index 0000000000..1a159a4d12 --- /dev/null +++ b/plugins/techdocs-backend/examples/documented-component-with-title/mkdocs.yml @@ -0,0 +1,12 @@ +site_name: 'Example Documentation' +repo_url: https://github.com/backstage/backstage +edit_uri: edit/master/plugins/techdocs-backend/examples/documented-component/docs + +nav: + - Home: index.md + - Subpage: sub-page.md + - 'Code Sample': code/code-sample.md + - Extensions: extensions.md + +plugins: + - techdocs-core diff --git a/plugins/techdocs/src/home/components/Tables/DocsTable.tsx b/plugins/techdocs/src/home/components/Tables/DocsTable.tsx index c0b39878cd..59abd9b278 100644 --- a/plugins/techdocs/src/home/components/Tables/DocsTable.tsx +++ b/plugins/techdocs/src/home/components/Tables/DocsTable.tsx @@ -85,6 +85,7 @@ export const DocsTable = (props: DocsTableProps) => { }); const defaultColumns: TableColumn[] = [ + columnFactories.createTitleColumn({ hidden: true }), columnFactories.createNameColumn(), columnFactories.createOwnerColumn(), columnFactories.createKindColumn(), diff --git a/plugins/techdocs/src/home/components/Tables/columns.tsx b/plugins/techdocs/src/home/components/Tables/columns.tsx index bc85bb7a63..3deb4d9b33 100644 --- a/plugins/techdocs/src/home/components/Tables/columns.tsx +++ b/plugins/techdocs/src/home/components/Tables/columns.tsx @@ -24,17 +24,20 @@ function customTitle(entity: Entity): string { return entity.metadata.title || entity.metadata.name; } +type ColumnOptions = Partial>; + /** * Not directly exported, but through DocsTable.columns and EntityListDocsTable.columns * * @public */ export const columnFactories = { - createNameColumn(): TableColumn { + createTitleColumn(overrides: ColumnOptions = {}): TableColumn { return { title: 'Document', - field: 'entity.metadata.name', + field: 'entity.metadata.title', highlight: true, + searchable: true, render: (row: DocsTableRow) => ( ), + ...overrides, }; }, - createOwnerColumn(): TableColumn { + createNameColumn(overrides: ColumnOptions = {}): TableColumn { + return { + title: 'Document', + field: 'entity.metadata.name', + highlight: true, + searchable: true, + render: (row: DocsTableRow) => ( + {customTitle(row.entity)} + } + subvalue={row.entity.metadata.description} + /> + ), + ...overrides, + }; + }, + createOwnerColumn(overrides: ColumnOptions = {}): TableColumn { return { title: 'Owner', field: 'resolved.ownedByRelationsTitle', @@ -55,18 +76,21 @@ export const columnFactories = { defaultKind="group" /> ), + ...overrides, }; }, - createKindColumn(): TableColumn { + createKindColumn(overrides: ColumnOptions = {}): TableColumn { return { title: 'Kind', field: 'entity.kind', + ...overrides, }; }, - createTypeColumn(): TableColumn { + createTypeColumn(overrides: ColumnOptions = {}): TableColumn { return { title: 'Type', field: 'entity.spec.type', + ...overrides, }; }, };