mirror of https://github.com/knative/docs.git
Docker instructions (#4733)
* Add docker instructions to preview website locally Signed-off-by: Carlos Santana <csantana23@gmail.com> * minor updates Signed-off-by: Carlos Santana <csantana23@gmail.com>
This commit is contained in:
Carlos Santana
GitHub
parent
993f02bcf6
commit
a3e16fd7c6
|
|
@ -2,9 +2,38 @@
|
|||
|
||||
The Knative website uses [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)
|
||||
to render documentation.
|
||||
You can choose to install MkDocs locally or use a Docker image.
|
||||
|
||||
## Install Material for MkDocs locally
|
||||
If you don't want to use any tool locally, you can use [GitPod](https://gitpod.io/#https://github.com/knative/docs)
|
||||
this will allow you to edit the files on a Web IDE and live preview.
|
||||
|
||||
If you choose to run the site locally, we strongly recommend using a container.
|
||||
|
||||
Regardless of the method used, when you submit a PR, a live preview link will be available in a comment on the PR.
|
||||
|
||||
## Use the Docker container
|
||||
|
||||
To start the live preview, run the following script.
|
||||
```
|
||||
./hack/docker/run.sh
|
||||
```
|
||||
Then open a web browser on http://localhost:8000
|
||||
|
||||
You can edit any file under `./docs` and the live preview autoreloads.
|
||||
|
||||
When you're done with your changes, you can stop the container in another terminal.
|
||||
```
|
||||
./hack/docker/stop.sh
|
||||
```
|
||||
You can run a complete build of the website with all versions using.
|
||||
```
|
||||
./hack/docker/test.sh
|
||||
```
|
||||
The build output is the entire static site located in `./site`.
|
||||
|
||||
You can preview the website locally by running a webserver using this directory like `npx http-server site -p 8000` if you have Node.js or `python3 -m http.server 8000` if you have Python 3
|
||||
|
||||
|
||||
### Install Material for MkDocs locally
|
||||
|
||||
Material for MkDocs is Python based and uses pip to install most of its required
|
||||
packages, as well as the optional add-ons we use.
|
||||
|
|
@ -14,7 +43,7 @@ from the [Python website](https://www.python.org).
|
|||
|
||||
For some (e.g. folks using RHEL), you might have to use pip3.
|
||||
|
||||
### Install using pip
|
||||
#### Install using pip
|
||||
|
||||
1. Install Material for MkDocs by running:
|
||||
|
||||
|
|
@ -30,26 +59,9 @@ For some (e.g. folks using RHEL), you might have to use pip3.
|
|||
pip install mkdocs-material-extensions mkdocs-macros-plugin mkdocs-exclude mkdocs-awesome-pages-plugin mkdocs-redirects
|
||||
```
|
||||
|
||||
### Install using pip3
|
||||
If you have `pip3` you can use the above commands and replace `pip` with `pip3`
|
||||
|
||||
1. Install Material for MkDocs by running:
|
||||
|
||||
```
|
||||
pip3 install mkdocs-material
|
||||
```
|
||||
|
||||
For more detailed instructions, see the [Material for MkDocs documentation](https://squidfunk.github.io/mkdocs-material/getting-started/#installation)
|
||||
|
||||
1. Install the extensions to MkDocs needed for Knative by running:
|
||||
|
||||
```
|
||||
pip3 install mkdocs-material-extensions mkdocs-macros-plugin mkdocs-exclude mkdocs-awesome-pages-plugin mkdocs-redirects
|
||||
```
|
||||
|
||||
## Use the Docker container
|
||||
//TODO DOCKER CONTAINER EXTENSIONS
|
||||
|
||||
## Setting up local preview
|
||||
### Setting up local preview
|
||||
|
||||
When using the local preview, anytime you change any file in your local copy of
|
||||
the `/docs` directory and hit save, the site automatically rebuilds to reflect your changes!
|
||||
|
|
@ -70,7 +82,7 @@ and clone the repo.
|
|||
```
|
||||
|
||||
- **Local Preview with Dirty Reload**
|
||||
If you’re only changing a single page in the `/docs/` folder that is not the homepage or `nav.yml`, adding the flag `--dirtyreload` makes the site rebuild super crazy insta-fast.
|
||||
If you’re only changing a single page in the `/docs/` folder that is not the homepage or `nav.yml`, adding the flag `--dirtyreload` makes the site rebuild faster.
|
||||
|
||||
```
|
||||
mkdocs serve --dirtyreload
|
||||
|
|
|
|||
|
|
@ -8,5 +8,3 @@ COPY ./requirements.txt /site/
|
|||
|
||||
# Python Dependencies
|
||||
RUN pip --no-cache-dir install -r requirements.txt
|
||||
# NodeJS Dependencies
|
||||
RUN npm ci
|
||||
|
|
|
|||
|
|
@ -1,10 +0,0 @@
|
|||
#!/usr/bin/env sh
|
||||
|
||||
set -x
|
||||
|
||||
IMAGE=${1:-knative-docs-dev}
|
||||
|
||||
SCRIPT_DIR=$(cd $(dirname $0); pwd -P)
|
||||
ROOT_DIR=$(cd "${SCRIPT_DIR}/../.."; pwd -P)
|
||||
|
||||
docker build -t ${IMAGE} -f ${SCRIPT_DIR}/Dockerfile ${ROOT_DIR}
|
||||
|
|
@ -1,6 +0,0 @@
|
|||
#!/usr/bin/env sh
|
||||
|
||||
set -x
|
||||
|
||||
NAME=${1:-knative-docs-dev}
|
||||
docker logs -f ${NAME}
|
||||
|
|
@ -4,9 +4,10 @@ set -x
|
|||
|
||||
NAME=${1:-knative-docs-dev}
|
||||
PORT=${2:-8000}
|
||||
IMAGE=${3:-knative-docs-dev}
|
||||
IMAGE=${3:-ghcr.io/knative/knative-docs:latest}
|
||||
|
||||
docker rm "${NAME}" --force 1> /dev/null 2> /dev/null
|
||||
|
||||
docker run --name "${NAME}" -d -p "${PORT}:8000" -v "${PWD}:/site" ${IMAGE} serve --dirtyreload --dev-addr=0.0.0.0:8000
|
||||
echo "Dev environment running with live reloading enabled. Open http://localhost:${PORT} to see the site"
|
||||
echo "For live logs run:"
|
||||
echo "docker logs -f ${NAME}"
|
||||
docker logs -f ${NAME}
|
||||
|
|
|
|||
|
|
@ -4,6 +4,6 @@ set -x
|
|||
|
||||
NAME=${1:-knative-docs-dev}
|
||||
PORT=${2:-8000}
|
||||
IMAGE=${3:-knative-docs-dev}
|
||||
IMAGE=${3:-ghcr.io/knative/knative-docs:latest}
|
||||
|
||||
docker run --rm -v "${PWD}:/site" -it --entrypoint "" ${IMAGE} hack/build.sh
|
||||
|
|
|
|||
File diff suppressed because it is too large
Load Diff
36
package.json
36
package.json
|
|
@ -1,36 +0,0 @@
|
|||
{
|
||||
"name": "knative",
|
||||
"version": "0.1.0",
|
||||
"description": "Knative docs",
|
||||
"main": "index.js",
|
||||
"devDependencies": {
|
||||
"autoprefixer": "^10.2.6",
|
||||
"http-server": "^0.12.3",
|
||||
"postcss-cli": "^8.3.1"
|
||||
},
|
||||
"scripts": {
|
||||
"predev": "./hack/docker/clean.sh knative-docs-dev",
|
||||
"dev": "./hack/docker/run.sh knative-docs-dev 8000",
|
||||
"postdev": "./hack/docker/logs.sh knative-docs-dev",
|
||||
"dev:stop": "./hack/docker/clean.sh knative-docs-dev",
|
||||
"dev:build": "./hack/docker/build.sh knative-docs-dev",
|
||||
"serve": "./hack/mkdocs.sh",
|
||||
"test": "./hack/docker/test.sh && exit 1"
|
||||
},
|
||||
"repository": {
|
||||
"type": "git",
|
||||
"url": "git+https://github.com/knative/docs.git"
|
||||
},
|
||||
"author": "",
|
||||
"license": "ISC",
|
||||
"bugs": {
|
||||
"url": "https://github.com/knative/docs/issues"
|
||||
},
|
||||
"homepage": "https://knative.dev",
|
||||
"engines": {
|
||||
"node": ">12.0"
|
||||
},
|
||||
"dependencies": {
|
||||
"postcss": "^8.3.0"
|
||||
}
|
||||
}
|
||||
Loading…
Reference in New Issue