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)
James Mills committed
Jan 16, 2020 at 02:59 UTC
d6c35a1a43ae04dfd0817512b5aacad3287bb8d1
3 files changed
+42
-3
.github/CODEOWNERS
+2
@@ -39,6 +39,7 @@ web/gui/ @jacekkolasa @cosmix
39
# Ownership by filetype (overwrites ownership by directory)
40
*.md @cosmix @joelhans
41
*.am @cosmix @Ferroin @knatsakis @ncmans @prologic
42
+Dockerfile.* @Ferroin @knatsakis @ncmans @prologic @cosmix
43
44
# Ownership of specific files
45
.gitignore @cosmix @Ferroin @knatsakis @ncmans @prologic
@@ -49,6 +50,7 @@ web/gui/ @jacekkolasa @cosmix
50
.csslintrc @cosmix @Ferroin @knatsakis @ncmans @prologic
51
.codeclimate.yml @cosmix @Ferroin @knatsakis @ncmans @prologic
52
.codacy.yml @cosmix @Ferroin @knatsakis @ncmans @prologic
53
+Dockerfile @Ferroin @knatsakis @ncmans @prologic @cosmix
54
netdata.spec.in @cosmix @Ferroin @knatsakis @ncmans @prologic
55
netdata-installer.sh @cosmix @Ferroin @knatsakis @ncmans @prologic
56
netlify.toml @cosmix
Dockerfile.docs
new
+26
@@ -0,0 +1,26 @@
1
+ARG PYVER=3.8
2
+
3
+FROM python:${PYVER}-alpine
4
+
5
+WORKDIR /netdata
6
+
7
+# These scripts use Bash(ism) so install Bash
8
+# TODO: Maybe rewrite the link checker in something more sane
9
+RUN apk add --no-cache -U bash
10
+
11
+# The scripts also clone the netdata/netdata repo using git
12
+# TODO: Maybe also optionally support bind-mounted sources
13
+RUN apk add --no-cache -U git
14
+
15
+# The scripts also use GNU find options
16
+RUN apk add --no-cache -U findutils
17
+
18
+# Copy and Install build dependencies first to cache them so we don't have to
19
+# do this every single time we want to rebuild the docs. The cache is busted
20
+# when/if the SHA of the requirements.txt is changed.
21
+COPY docs/generator /netdata/docs/generator
22
+RUN pip install -r /netdata/docs/generator/requirements.txt
23
+
24
+COPY . .
25
+
26
+CMD ["/netdata/docs/generator/buildhtml.sh"]
docs/contributing/contributing-documentation.md
+14
-3
@@ -131,10 +131,21 @@ reason.
131
Building the documentation periodically gives you a glimpse into the final product, and is generally required if you're
132
making changes to the table of contents.
133
134
-!!! attention "" We have only tested the build process on Linux. Initial tests on OS X have been unsuccessful. Windows
135
- is fully untested at this point, but we would love to know if it works there as well!
134
+We have a [netdata/docs Docker Image](https://hub.docker.com/r/netdata/os-test) available on the Docker Hub
135
+that greatly simplifies building the documentation on any [Docker](https://www.docker.com) supported platform.
136
137
-To build the documentation, you need `python`/`pip`, `mkdocs`, and `mkdocs-material` installed on your machine.
137
+To build the docs using this image via Docker simply run the following commands in your shell:
138
+
139
+```bash
140
+cd /path/to/netdata
141
+docker run -i -t -v $PWD:/netdata netdata/docs
142
+```
143
+
144
+----
145
+
146
+if you are using a GNU/Linux based system for developing / contribiting to our documentation, you may build the
147
+docs with the provided Shell scripts in `./docs/generator/buildhtml.sh`. This requires GNU Bash and findutils
148
+as well as Python/pip and some Python packages `mkdocs` and `mkdocs-material` installed in your environment.
149
150
Follow the [Python installation instructions](https://www.python.org/downloads/) for your machine.
151