TechDocs: Remove techdocs-container package from mono-repo (#3230)
* Move techdocs-container package to backstage/techdocs-container * Clean up codeowners * Remove unnecessary GitHub CI workflow * Modify path in docs for techdocs-container * Fix techdocs-cli URL * Remove techdocs packages from docs/support/packages
This commit is contained in:
Himanshu Mishra
@@ -11,6 +11,5 @@
|
||||
/plugins/techdocs @backstage/techdocs-core
|
||||
/plugins/techdocs-backend @backstage/techdocs-core
|
||||
/packages/techdocs-cli @backstage/techdocs-core
|
||||
/packages/techdocs-container @backstage/techdocs-core
|
||||
/.github/workflows/techdocs.yml @backstage/techdocs-core
|
||||
/.changeset/cost-insights-* @backstage/silver-lining
|
||||
|
||||
@@ -1,33 +0,0 @@
|
||||
name: TechDocs
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
paths:
|
||||
- '.github/workflows/techdocs.yml'
|
||||
- 'packages/techdocs-container/**'
|
||||
- 'packages/techdocs-cli/**'
|
||||
- 'plugins/techdocs/**'
|
||||
- 'plugins/techdocs-backend/**'
|
||||
|
||||
jobs:
|
||||
build:
|
||||
runs-on: ${{ matrix.os }}
|
||||
|
||||
strategy:
|
||||
matrix:
|
||||
os: [ubuntu-latest]
|
||||
python-version: [3.7]
|
||||
|
||||
env:
|
||||
TECHDOCS_CORE_PATH: ./packages/techdocs-container/techdocs-core
|
||||
|
||||
name: Python ${{ matrix.node-version }} on ${{ matrix.os }}
|
||||
steps:
|
||||
- uses: actions/checkout@v2
|
||||
|
||||
# Build Docker Image
|
||||
- name: Build Docker image
|
||||
uses: docker/build-push-action@v1.1.0
|
||||
with:
|
||||
path: packages/techdocs-container
|
||||
push: false
|
||||
@@ -17,9 +17,8 @@ This page answers frequently asked questions about [TechDocs](README.md).
|
||||
|
||||
TechDocs is using [MkDocs](https://www.mkdocs.org/) to build project
|
||||
documentation under the hood. Documentation built with the
|
||||
[techdocs-container](https://github.com/backstage/backstage/blob/master/packages/techdocs-container/README.md)
|
||||
is using the MkDocs
|
||||
[Material Theme](https://github.com/squidfunk/mkdocs-material).
|
||||
[techdocs-container](https://github.com/backstage/techdocs-container) is using
|
||||
the MkDocs [Material Theme](https://github.com/squidfunk/mkdocs-material).
|
||||
|
||||
#### What is the mkdocs-techdocs-core plugin?
|
||||
|
||||
|
||||
@@ -109,8 +109,8 @@ migrate Spotify's existing TechDocs features to open source.
|
||||
| ------------------------------------------- | -------------------------------------------------------- |
|
||||
| Frontend | [`@backstage/plugin-techdocs`][techdocs/frontend] |
|
||||
| Backend | [`@backstage/plugin-techdocs-backend`][techdocs/backend] |
|
||||
| Docker Container (for generating doc sites) | [`packages/techdocs-container`][techdocs/container] |
|
||||
| CLI (for local development) | [`packages/techdocs-cli`][techdocs/cli] |
|
||||
| Docker Container (for generating doc sites) | [`techdocs-container`][techdocs/container] |
|
||||
| CLI (for local development) | [`@techdocs/cli`][techdocs/cli] |
|
||||
|
||||
[getting started]: getting-started.md
|
||||
[concepts]: concepts.md
|
||||
@@ -120,7 +120,5 @@ migrate Spotify's existing TechDocs features to open source.
|
||||
https://github.com/backstage/backstage/blob/master/plugins/techdocs
|
||||
[techdocs/backend]:
|
||||
https://github.com/backstage/backstage/blob/master/plugins/techdocs-backend
|
||||
[techdocs/container]:
|
||||
https://github.com/backstage/backstage/blob/master/packages/techdocs-container
|
||||
[techdocs/cli]:
|
||||
https://github.com/backstage/backstage/blob/master/packages/techdocs-cli
|
||||
[techdocs/container]: https://github.com/backstage/techdocs-container
|
||||
[techdocs/cli]: https://github.com/backstage/techdocs-cli
|
||||
|
||||
@@ -23,7 +23,7 @@ The TechDocs container is a Docker container available at
|
||||
pages, including stylesheets and scripts from Python flavored Markdown, through
|
||||
MkDocs.
|
||||
|
||||
[TechDocs Container](https://github.com/backstage/backstage/blob/master/packages/techdocs-container/README.md)
|
||||
[TechDocs Container](https://github.com/backstage/techdocs-container)
|
||||
|
||||
### TechDocs publisher
|
||||
|
||||
|
||||
@@ -168,12 +168,6 @@ are separated out into their own folder, see further down.
|
||||
package. The Backstage Storybook is found
|
||||
[here](https://backstage.io/storybook)
|
||||
|
||||
- [`techdocs-cli/`](https://github.com/backstage/backstage/tree/master/packages/techdocs-cli) -
|
||||
Used for verifying TechDocs locally.
|
||||
|
||||
- [`techdocs-container/`](https://github.com/backstage/backstage/tree/master/packages/techdocs-container) -
|
||||
Used by the `techdocs-cli`
|
||||
|
||||
- [`test-utils-core/`](https://github.com/backstage/backstage/tree/master/packages/test-utils-core)
|
||||
|
||||
- [`test-utils/`](https://github.com/backstage/backstage/tree/master/packages/test-utils)
|
||||
|
||||
@@ -23,7 +23,7 @@ But this is just one way to do it. Today we’re most excited for what the open
|
||||
|
||||
If you go to [GitHub](https://github.com/backstage/backstage/tree/master/plugins) now, you’ll find everything you need to start collaborating with us to build out the docs-like-code Backstage plugin — we’ll call it TechDocs in the open as well.
|
||||
|
||||
You’ll find the code in [techdocs](https://github.com/backstage/backstage/tree/master/plugins/techdocs) (frontend) and [techdocs-backend](https://github.com/backstage/backstage/tree/master/plugins/techdocs-backend). (There are also two separate packages [techdocs-cli](https://github.com/backstage/backstage/tree/master/packages/techdocs-cli) and [techdocs-container](https://github.com/backstage/backstage/tree/master/packages/techdocs-container).)
|
||||
You’ll find the code in [techdocs](https://github.com/backstage/backstage/tree/master/plugins/techdocs) (frontend) and [techdocs-backend](https://github.com/backstage/backstage/tree/master/plugins/techdocs-backend). (There are also two separate packages [techdocs-cli](https://github.com/backstage/techdocs-cli) and [techdocs-container](https://github.com/backstage/techdocs-container).)
|
||||
|
||||
You’ll find issues to work on in the [issues queue](https://github.com/backstage/backstage/issues?q=is%3Aissue+is%3Aopen+label%3A%22docs-like-code%22+label%3A%22help+wanted%22), typically starting with TechDocs: and labeled with docs-like-code, some labeled good first issue. Feel free to add your own issues, of course.
|
||||
|
||||
|
||||
@@ -1,28 +0,0 @@
|
||||
# Copyright 2020 Spotify AB
|
||||
#
|
||||
# Licensed under the Apache License, Version 2.0 (the "License");
|
||||
# you may not use this file except in compliance with the License.
|
||||
# You may obtain a copy of the License at
|
||||
#
|
||||
# http://www.apache.org/licenses/LICENSE-2.0
|
||||
#
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS,
|
||||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
|
||||
FROM python:3.8-alpine
|
||||
|
||||
|
||||
RUN apk update && apk --no-cache add gcc musl-dev openjdk11-jdk curl graphviz ttf-dejavu fontconfig
|
||||
|
||||
RUN curl -o plantuml.jar -L http://sourceforge.net/projects/plantuml/files/plantuml.1.2020.16.jar/download && echo "c789ace48347c43073232b1458badc5810c01fe8 plantuml.jar" | sha1sum -c - && mv plantuml.jar /opt/plantuml.jar
|
||||
RUN pip install --upgrade pip && pip install mkdocs-techdocs-core==0.0.11
|
||||
|
||||
# Create script to call plantuml.jar from a location in path
|
||||
|
||||
RUN echo $'#!/bin/sh\n\njava -jar '/opt/plantuml.jar' ${@}' >> /usr/local/bin/plantuml
|
||||
RUN chmod 755 /usr/local/bin/plantuml
|
||||
|
||||
ENTRYPOINT [ "mkdocs" ]
|
||||
@@ -1,31 +0,0 @@
|
||||
# techdocs-container
|
||||
|
||||
This is the Docker container that powers the creation of static documentation sites that are supported by [TechDocs](https://github.com/backstage/backstage/blob/master/plugins/techdocs).
|
||||
|
||||
## Getting Started
|
||||
|
||||
Using the TechDocs CLI, we can invoke the latest version of `techdocs-container` via Docker Hub:
|
||||
|
||||
```bash
|
||||
npx techdocs-cli serve
|
||||
```
|
||||
|
||||
## Local Development
|
||||
|
||||
```bash
|
||||
docker build . -t mkdocs:local-dev
|
||||
|
||||
docker run -w /content -v $(pwd)/mock-docs:/content -p 8000:8000 -it mkdocs:local-dev serve -a 0.0.0.0:8000
|
||||
```
|
||||
|
||||
Then open up `http://localhost:8000` on your local machine.
|
||||
|
||||
## Publishing
|
||||
|
||||
This container is published on DockerHub - https://hub.docker.com/r/spotify/techdocs
|
||||
|
||||
The publishing is configured by [Automated Builds](https://hub.docker.com/repository/docker/spotify/techdocs/builds/edit) feature on Docker Hub which is triggered from GitHub (on new commits and releases). @backstage/techdocs-core team has access to the settings.
|
||||
|
||||
The `latest` tag on Docker Hub points to the recent commits in the `master` branch. The [version tags](https://hub.docker.com/r/spotify/techdocs/tags) (e.g. v0.1.1-alpha.24) point to the GitHub tags created from [releases](https://github.com/backstage/backstage/releases) of this GitHub repository.
|
||||
|
||||
Note: We recommend using a specific version of the container instead of `latest` release for stability and avoiding unexpected changes.
|
||||
@@ -1 +0,0 @@
|
||||
site/
|
||||
@@ -1,99 +0,0 @@
|
||||
## hello mock docs
|
||||
|
||||
!!! test
|
||||
Testing something
|
||||
|
||||
Abbreviations:
|
||||
Some text about MOCDOC
|
||||
|
||||
This is a paragraph.
|
||||
{: #test_id .test_class }
|
||||
|
||||
Apple
|
||||
: Pomaceous fruit of plants of the genus Malus in
|
||||
the family Rosaceae.
|
||||
|
||||
```javascript
|
||||
import { test } from 'something';
|
||||
|
||||
const addThingToThing = (a, b) a + b;
|
||||
```
|
||||
|
||||
- [abc](#abc)
|
||||
- [xyz](#xyz)
|
||||
|
||||
## abc
|
||||
|
||||
This is a b c.
|
||||
|
||||
## xyz
|
||||
|
||||
This is x y z.
|
||||
|
||||
# The attack plan
|
||||
|
||||
{% dot attack_plan.svg
|
||||
digraph G {
|
||||
rankdir=LR
|
||||
Earth [peripheries=2]
|
||||
Mars
|
||||
Earth -> Mars
|
||||
}
|
||||
%}
|
||||
|
||||
```graphviz dot attack_plan.svg
|
||||
digraph G {
|
||||
rankdir=LR
|
||||
Earth [peripheries=2]
|
||||
Mars
|
||||
Earth -> Mars
|
||||
}
|
||||
```
|
||||
|
||||
# PlantUML Samples
|
||||
|
||||
```plantuml classes="uml myDiagram" alt="Diagram placeholder" title="My diagram"
|
||||
@startuml
|
||||
Goofy -> MickeyMouse: calls
|
||||
Goofy <-- MickeyMouse: responds
|
||||
@enduml
|
||||
```
|
||||
|
||||
:bulb:
|
||||
|
||||
=== "JavaScript"
|
||||
|
||||
```javascript
|
||||
import { test } from 'something';
|
||||
|
||||
const addThingToThing = (a, b) a + b;
|
||||
```
|
||||
|
||||
=== "Java"
|
||||
|
||||
```java
|
||||
public void function() {
|
||||
test();
|
||||
}
|
||||
```
|
||||
|
||||
```java tab="java"
|
||||
public void function() {
|
||||
test();
|
||||
}
|
||||
```
|
||||
|
||||
```java tab="java 2"
|
||||
public void function() {
|
||||
test();
|
||||
}
|
||||
```
|
||||
|
||||
```javascript
|
||||
import { test } from 'something';
|
||||
|
||||
const addThingToThing = (a, b) a + b;
|
||||
```
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
*[MOCDOC]: Mock Documentation
|
||||
@@ -1,9 +0,0 @@
|
||||
site_name: 'mock-docs'
|
||||
site_description: 'mock-docs site description'
|
||||
|
||||
nav:
|
||||
- Home: index.md
|
||||
- SubDocs: '!include ./sub-docs/mkdocs.yml'
|
||||
|
||||
plugins:
|
||||
- techdocs-core
|
||||
@@ -1 +0,0 @@
|
||||
### This is an md file in another docs folder using the [MkDocs Monorepo Plugin](https://github.com/spotify/mkdocs-monorepo-plugin)
|
||||
@@ -1,4 +0,0 @@
|
||||
site_name: subdocs
|
||||
|
||||
nav:
|
||||
- Home 2: 'index.md'
|
||||
Reference in New Issue
Block a user