diff options
author | James Mills <1290234+prologic@users.noreply.github.com> | 2020-01-16 02:59:53 +0200 |
---|---|---|
committer | GitHub <noreply@github.com> | 2020-01-16 02:59:53 +0200 |
commit | d6c35a1a43ae04dfd0817512b5aacad3287bb8d1 (patch) | |
tree | 2921038f59960ab731b5f678bb2c645a61415df7 | |
parent | 38c80abea604d3b52edb1f60e1324a9908eca83d (diff) |
Adds a Dockerfile.docs for more easily and reproducibly building/rebuilding docs (#7688)
* Added a Dockerfile.docs for more easily and reproducibly building/rebuilding docs.
* Update the docs for contributing / rebuilding the docs locally
* Add SRE Team as code owners of all Dockerfile(s)
-rw-r--r-- | .github/CODEOWNERS | 2 | ||||
-rw-r--r-- | Dockerfile.docs | 26 | ||||
-rw-r--r-- | docs/contributing/contributing-documentation.md | 17 |
3 files changed, 42 insertions, 3 deletions
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 39024e79ab..913382d593 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -39,6 +39,7 @@ web/gui/ @jacekkolasa @cosmix # Ownership by filetype (overwrites ownership by directory) *.md @cosmix @joelhans *.am @cosmix @Ferroin @knatsakis @ncmans @prologic +Dockerfile.* @Ferroin @knatsakis @ncmans @prologic @cosmix # Ownership of specific files .gitignore @cosmix @Ferroin @knatsakis @ncmans @prologic @@ -49,6 +50,7 @@ web/gui/ @jacekkolasa @cosmix .csslintrc @cosmix @Ferroin @knatsakis @ncmans @prologic .codeclimate.yml @cosmix @Ferroin @knatsakis @ncmans @prologic .codacy.yml @cosmix @Ferroin @knatsakis @ncmans @prologic +Dockerfile @Ferroin @knatsakis @ncmans @prologic @cosmix netdata.spec.in @cosmix @Ferroin @knatsakis @ncmans @prologic netdata-installer.sh @cosmix @Ferroin @knatsakis @ncmans @prologic netlify.toml @cosmix diff --git a/Dockerfile.docs b/Dockerfile.docs new file mode 100644 index 0000000000..c77dbe707e --- /dev/null +++ b/Dockerfile.docs @@ -0,0 +1,26 @@ +ARG PYVER=3.8 + +FROM python:${PYVER}-alpine + +WORKDIR /netdata + +# These scripts use Bash(ism) so install Bash +# TODO: Maybe rewrite the link checker in something more sane +RUN apk add --no-cache -U bash + +# The scripts also clone the netdata/netdata repo using git +# TODO: Maybe also optionally support bind-mounted sources +RUN apk add --no-cache -U git + +# The scripts also use GNU find options +RUN apk add --no-cache -U findutils + +# Copy and Install build dependencies first to cache them so we don't have to +# do this every single time we want to rebuild the docs. The cache is busted +# when/if the SHA of the requirements.txt is changed. +COPY docs/generator /netdata/docs/generator +RUN pip install -r /netdata/docs/generator/requirements.txt + +COPY . . + +CMD ["/netdata/docs/generator/buildhtml.sh"] diff --git a/docs/contributing/contributing-documentation.md b/docs/contributing/contributing-documentation.md index c32e1a09c2..9d4b5acf36 100644 --- a/docs/contributing/contributing-documentation.md +++ b/docs/contributing/contributing-documentation.md @@ -131,10 +131,21 @@ reason. Building the documentation periodically gives you a glimpse into the final product, and is generally required if you're making changes to the table of contents. -!!! attention "" We have only tested the build process on Linux. Initial tests on OS X have been unsuccessful. Windows - is fully untested at this point, but we would love to know if it works there as well! +We have a [netdata/docs Docker Image](https://hub.docker.com/r/netdata/os-test) available on the Docker Hub +that greatly simplifies building the documentation on any [Docker](https://www.docker.com) supported platform. -To build the documentation, you need `python`/`pip`, `mkdocs`, and `mkdocs-material` installed on your machine. +To build the docs using this image via Docker simply run the following commands in your shell: + +```bash +cd /path/to/netdata +docker run -i -t -v $PWD:/netdata netdata/docs +``` + +---- + +if you are using a GNU/Linux based system for developing / contribiting to our documentation, you may build the +docs with the provided Shell scripts in `./docs/generator/buildhtml.sh`. This requires GNU Bash and findutils +as well as Python/pip and some Python packages `mkdocs` and `mkdocs-material` installed in your environment. Follow the [Python installation instructions](https://www.python.org/downloads/) for your machine. |