feat: add documented component to uffizzi environment

So far, none of the components at the uffizzi environment have techdocs. Hence, there are no docs available within this environment and related features are not covered. This change will add an example from techdocs-backend plugin to the deployed examples. It was possible to register this catalog file manually, however the build of the docs fail due to missing Docker. To allow the generation of docs, we use the local generator (no docker in docker) and install required dependencies. As we don't want all dependencies for all (default) extensions to be installed at this environment, the original example at techdocs-backend plugin was copied and reduced (PlantUML extension example was removed). Signed-off-by: Patrick Jungermann <Patrick.Jungermann@gmail.com>
2023-03-06 23:39:35 +01:00
parent 21403149d2
commit 05f584f84d
11 changed files with 237 additions and 7 deletions
@@ -14,6 +14,7 @@ services:
      POSTGRES_PORT: 5432
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: kiTMoTsiEuyQ43GrL4Hv
+      REF_NAME: ${GITHUB_SHA}
      NODE_ENV: production
    deploy:
      resources:
@@ -28,6 +28,7 @@ backend:
    credentials: true
  csp:
    connect-src: ["'self'", 'http:', 'https:']
+    img-src: ["'self'", 'data:', 'https://cdnjs.cloudflare.com']
    # Content-Security-Policy directives follow the Helmet format: https://helmetjs.github.io/#reference
    # Default Helmet Content-Security-Policy values can be removed by setting the key to false

@@ -41,15 +42,18 @@ auth:
 catalog:
  locations:
    - type: url
-      target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/all.yaml
+      target: https://github.com/backstage/backstage/blob/${REF_NAME}/packages/catalog-model/examples/all.yaml

    - type: url
-      target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/acme-corp.yaml
+      target: https://github.com/backstage/backstage/blob/${REF_NAME}/plugins/techdocs-backend/examples/documented-component-uffizzi/catalog-info.yaml
+
+    - type: url
+      target: https://github.com/backstage/backstage/blob/${REF_NAME}/packages/catalog-model/examples/acme-corp.yaml
      rules:
        - allow: [User, Group]

    - type: url
-      target: https://github.com/backstage/backstage/blob/master/plugins/scaffolder-backend/sample-templates/all-templates.yaml
+      target: https://github.com/backstage/backstage/blob/${REF_NAME}/plugins/scaffolder-backend/sample-templates/all-templates.yaml
      rules:
        - allow: [Template]

@@ -124,7 +128,7 @@ proxy:
 techdocs:
  builder: 'local' # Alternatives - 'external'
  generator:
-    runIn: 'docker'
+    runIn: 'local'
    # dockerImage: my-org/techdocs # use a custom docker image
    # pullImage: true # or false to disable automatic pulling of image (e.g. if custom docker login is required)
  publisher:
@@ -81,7 +81,7 @@ jobs:
          BACKSTAGE_IMAGE=$(echo ${{ needs.build-backstage.outputs.tags }})
          export BACKSTAGE_IMAGE
          # Render simple template from environment variables.
-          envsubst '$BACKSTAGE_IMAGE' < .github/uffizzi/docker-compose.uffizzi.yml > docker-compose.rendered.yml
+          envsubst '$BACKSTAGE_IMAGE $GITHUB_SHA' < .github/uffizzi/docker-compose.uffizzi.yml > docker-compose.rendered.yml
          cat docker-compose.rendered.yml
      - name: Upload Rendered Compose File as Artifact
        uses: actions/upload-artifact@v3
@@ -13,11 +13,14 @@ FROM node:16-bullseye-slim

 # Install sqlite3 dependencies. You can skip this if you don't use sqlite3 in the image,
 # in which case you should also move better-sqlite3 to "devDependencies" in package.json.
+# Additionally, we install dependencies for `techdocs.generator.runIn: local`.
+# https://backstage.io/docs/features/techdocs/getting-started#disabling-docker-in-docker-situation-optional
 RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
    --mount=type=cache,target=/var/lib/apt,sharing=locked \
    apt-get update && \
-    apt-get install -y --no-install-recommends libsqlite3-dev python3 build-essential && \
-    yarn config set python /usr/bin/python3
+    apt-get install -y --no-install-recommends libsqlite3-dev python3 python3-pip build-essential && \
+    yarn config set python /usr/bin/python3 && \
+    pip3 install mkdocs-techdocs-core==1.1.7

 # From here on we use the least-privileged `node` user to run the backend.
 WORKDIR /app
@@ -0,0 +1,12 @@
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: documented-component-uffizzi
+  title: Documented Component (Uffizzi)
+  description: A Service with TechDocs documentation. Excl. PlantUML extension.
+  annotations:
+    backstage.io/techdocs-ref: dir:.
+spec:
+  type: service
+  lifecycle: experimental
+  owner: user:guest
@@ -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 = (
+  <EntityLayout>
+    <EntityLayout.Route path="/" title="Overview">
+      <Grid container spacing={3} alignItems="stretch">
+        <Grid item md={6}>
+          <EntityAboutCard variant="gridItem" />
+        </Grid>
+      </Grid>
+    </EntityLayout.Route>
+    <EntityLayout.Route path="/docs" title="Docs">
+      <EntityTechdocsContent />
+    </EntityLayout.Route>
+  </EntityLayout>
+);
+```
+
+Here is an example of Python code:
+
+```python
+def getUsersInGroup(targetGroup, secure=False):
+
+    if __debug__:
+        print('targetGroup=[' + targetGroup + ']')
+```
@@ -0,0 +1,99 @@
+# 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:
+
+<!-- prettier-ignore -->
+!!! warn
+    Defining admonitions can be addicting.
+
+<!-- prettier-ignore -->
+!!! note
+    You can learn a lot about TechDocs by just visiting the Backstage web site at
+    https://backstage.io/docs.
+
+<!-- prettier-ignore -->
+!!! info
+    TechDocs is the core feature that supports documentation as code in Backstage.
+
+<!-- prettier-ignore -->
+!!! tip
+    Don't forget to spell check your documentation.
+
+## Pymdownx Extensions
+
+Pymdownx (Python Markdown extensions) are a variety of smaller additions.
+
+### Details
+
+<!-- prettier-ignore -->
+??? note "What is the answer to life, the universe, and everything? (click me for the answer)"
+    The answer is 42.
+
+<!-- prettier-ignore -->
+??? note "What is 4 plus 4?"
+    The answer is 8.
+
+<!-- prettier-ignore -->
+???+ 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`
@@ -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. |
@@ -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.
@@ -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