Merge branch 'master' of github.com:backstage/backstage into adamdmharvey/fix-docs

Signed-off-by: Adam Harvey <adaharve@cisco.com>

docs/features/software-catalog/references.md

@@ -23,8 +23,7 @@ compound reference structure.
 
 ## String References
 
-This is the most common alternative, that should be used in almost all
-circumstances.
+This is the most common alternative, that is used in almost all circumstances.
 
 The string is on the form `[<kind>:][<namespace>/]<name>`, that is, it is
 composed of between one and three parts in this specific order, without any
@@ -75,30 +74,16 @@ essentially expand to `api:external-systems/petstore`,
 `api:internal/streetlights`, and `api:external-systems/hello-world`. We expect
 there to exist three API kind entities in the catalog matching those references.
 
+Note that the remarks above in regards to shortening (leaving out kind and/or
+namespace) _only_ apply for the entity input YAML data. In protocols, storage
+systems, or when referring to entities externally, the entity ref always
+consists of all three parts.
+
 ## Compound References
 
 This is a more verbose version of a reference, where each part of the
-kind-namespace-name triplet is expressed as a field in a structure. This format
-can be used where necessary, such as if either of the three elements contains
-colons or forward slashes. Avoid using it where possible, since it is harder to
-read and write for humans.
-
-```yaml
-# Example:
-apiVersion: backstage.io/v1alpha1
-kind: Component
-metadata:
-  name: petstore
-  description: Petstore
-spec:
-  type: service
-  lifecycle: experimental
-  owner:
-    kind: Group
-    name: aegis-imports/pet-managers
-```
-
-In this example, the `spec.owner` has been broken apart since the name was
-complex. The kind happened to be written with an uppercase letter G, which also
-works. The namespace was left out just like in the string version above, which
-is handled identically.
+kind-namespace-name triplet is expressed as a field in an object. You may see
+this structure used in Backstage code, but it should normally not be used in any
+form of protocol or between plugins and/or external systems. For those cases,
+instead prefer to use the string form which has clearer semantics and can be
+transported more easily since it's just a string.

docs/features/techdocs/how-to-guides.md

@@ -491,7 +491,7 @@ plugins:
 
 The `docs/index.md` can for example have the following content:
 
-```
+```markdown
 # ${{ values.component_id }}
 
 ${{ values.description }}
@@ -509,8 +509,8 @@ Done! You now have support for TechDocs in your own software template!
 
 ## How to enable iframes in TechDocs
 
-TechDocs uses the [DOMPurify](https://github.com/cure53/DOMPurify) library to sanitize
-HTML and prevent XSS attacks.
+TechDocs uses the [DOMPurify](https://github.com/cure53/DOMPurify) library to
+sanitize HTML and prevent XSS attacks.
 
 It's possible to allow some iframes based on a list of allowed hosts. To do
 this, add the allowed hosts in the `techdocs.sanitizer.allowedIframeHosts`
@@ -530,20 +530,20 @@ This way, all iframes where the host in the src attribute is in the
 
 ## How to add Mermaid support in TechDocs
 
-To add `Mermaid` support in Techdocs, you can use [`kroki`](https://kroki.io)
+To add `Mermaid` support in TechDocs, you can use [`kroki`](https://kroki.io)
 that creates diagrams from Textual descriptions. It is a single rendering
 gateway for all popular diagrams-as-a-code tools. It supports an enormous number
 of diagram types.
 
-1. **Create and Publish docker image:** Create the docker image from the
-   following Dockerfile and publish it to DockerHub.
+1. **Create and Publish Docker image:** Create the Docker image from the
+   following `Dockerfile` and publish it to DockerHub.
 
 ```docker
-FROM python:3.8-alpine
+FROM python:3.10-alpine
 
 RUN apk update && apk --no-cache add gcc musl-dev openjdk11-jdk curl graphviz ttf-dejavu fontconfig
 
-RUN pip install --upgrade pip && pip install mkdocs-techdocs-core==1.1.7
+RUN pip install --upgrade pip && pip install mkdocs-techdocs-core==1.2.0
 
 RUN pip install mkdocs-kroki-plugin
 
@@ -551,7 +551,7 @@ ENTRYPOINT [ "mkdocs" ]
 ```
 
 Create a repository in your DockerHub and run the below command in the same
-folder where your Dockerfile is present:
+folder where your `Dockerfile` is present:
 
 ```shell
 docker build . -t dockerHub_Username/repositoryName:tagName
@@ -559,7 +559,7 @@ docker build . -t dockerHub_Username/repositoryName:tagName
 
 Once the docker image is ready, push it to DockerHub.
 
-2. **Update app-config.yaml:** So that when your app generates techdocs, it will
+2. **Update app-config.yaml:** So that when your app generates TechDocs, it will
    pull your docker image from DockerHub.
 
 ```python
@@ -573,7 +573,7 @@ techdocs:
     type: 'local' # Alternatives - 'googleGcs' or 'awsS3'. Read documentation for using alternatives.
 ```
 
-3. **Add the `kroki` plugin in mkdocs.yml:**
+3. **Add the `kroki` plugin in `mkdocs.yml`:**
 
 ```yml
 plugins:
@@ -588,7 +588,7 @@ plugins:
 > instead. Check out [mkdocs-kroki-plugin config](https://github.com/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin#config)
 > for more plugin configuration details.
 
-4. **Add mermaid code into techdocs:**
+4. **Add mermaid code into TechDocs:**
 
 ````md
 ```kroki-mermaid

docs/features/techdocs/troubleshooting.md

@@ -5,11 +5,24 @@ sidebar_label: Troubleshooting
 description: Troubleshooting for TechDocs
 ---
 
-## Failure to clone
+## Documentation not found when generating
 
-TechDocs will fail to clone your docs if you have a git config which overrides
-the `https` protocol with `ssh` or something else. Make sure to remove your git
-config locally when you try TechDocs.
+This may happen if you have TechDocs set up using the "out-of-the-box"
+configuration, wherein documentation is built dynamically by the TechDocs
+backend, and your TechDocs files are being pulled from a git-based source
+control management system (e.g. GitHub, BitBucket, etc).
+
+If you experience this, check that TechDocs-related files (e.g. markdown,
+assets, or the `mkdocs.yml` file) are not matched by an `export-ignore`
+attribute in a `.gitattributes` file in the relevant repository.
+
+TechDocs' backend is not able to see such files, and therefore may generate
+partial (or no) TechDocs as a result.
+
+You'll need to reconsider how you distribute tar archives based on your source
+code (and how you prevent internal documentation from being included in those
+archives). Alternatively, you could consider switching to the "recommended"
+TechDocs architecture (documentation generated and published in CI/CD).
 
 ## MkDocs Build Errors