Build with Docker
Writerside maintains a Docker image that runs the documentation builder. While local builds rely on the bundled builder, with Docker, you can specify the tag of any publicly available builder version.
This can be useful if you updated to a new version of Writerside that processes some markup differently, and you are not ready to change the sources yet to make it compatible with the latest version. Then you can run builds with the previous builder version. Or you can use it to see if the new builder will work in your project before updating to the latest version of Writerside.
You can use the Docker builder to create a script for automating your documentation builds both locally and on a CI/CD pipeline. For example, our instructions for GitHub, GitLab, and TeamCity all include a build step using the Docker image.
Pull Docker builder image
The Docker image with the Writerside builder is available in Docker Hub and in the JetBrains Docker Registry.
The tag for the latest writerside-builder image is 243.22562.
Run Docker builder container
When running a container from this image, mount the project sources directory (and an optional separate output directory) into the container and specify the necessary environment variables. For example, when running from the Starter documentation project root:
Alternatively, you can use an env file to define the variables, for example:
Where builder.env is a file that sets the variables to specific values, for example:
In the previous examples, -v .:/opt/sources mounts the current directory (you should be running it from the project root) to the directory /opt/sources in the container. If you want to output the built artifacts to a different directory, add a separate mount using another -v option.
When the builder finishes, --rm removes the container. You should find the output in the output directory under the project root.
Builder options and variables
You can also run the helpbuilderinspect command directly when running the container, but then instead of environment variables, provide the necessary options to the command:
When using variables, the container runs the command in quotes taking option values from the provided variables, like this:
The following options are required:
--source-dir,-iSpecify the directory with documentation sources. When using variables, specify it via
SOURCE_DIR.--product,-pSpecify the module and instance that you want to build, separated by a slash
/. When using variables, specify it viaMODULE_INSTANCE.--output-dir,-oSpecify the output directory where the generated documentation will be stored. When using variables, specify it via
OUTPUT_DIR.
The following options are not required:
--runner,-rSpecify the environment or platform on which the builder will be executed. The supported values are case-insensitive and include:
teamcity: Produce artifacts specific for TeamCity (default value).gitlab: Produce artifacts specific for GitLab.github: Produce artifacts specific for GitHub.other: Produce generic artifacts that may require some adjustments for your environment.
When using variables, specify it via
RUNNER.-pdfSpecify the file with PDF export settings to generate a PDF. If not specified, the builder produces a regular documentation website. When using variables, specify it via
PDF.
Create builder image with the generated website
Let's say you want to create your own Docker image that builds a specific instance with a specific builder version and also starts a webserver with the produced website when you run a container from this image.
Create a Dockerfile with the following contents:
FROM jetbrains/writerside-builder:243.22562 as build ARG INSTANCE=Writerside/hi RUN mkdir /opt/sources WORKDIR /opt/sources ADD Writerside ./Writerside RUN export DISPLAY=:99 && \ Xvfb :99 & \ /opt/builder/bin/idea.sh helpbuilderinspect --source-dir /opt/sources --product $INSTANCE --runner other --output-dir /opt/wrs-output/ WORKDIR /opt/wrs-output RUN unzip -O UTF-8 webHelpHI2-all.zip -d /opt/wrs-output/unzipped-artifact FROM httpd:2.4 as http-server COPY --from=build /opt/wrs-output/unzipped-artifact/ /usr/local/apache2/htdocs/Build an image from this Dockerfile. In the directory with the Dockerfile, run the following command:
docker build -t help-website .Run a container from this image in the documentation root and publish port 80 in the container to 8080 on the host.
docker run -dit -p 8080:80 help-website
Now you can visit http://localhost:8080 to see the built help website being served by an HTTP server in the container.
If you want to use another builder version or build a different instance, change it in the Dockerfile, rebuild the image, and run the container. Remember to change the ZIP archive name as it contains the instance ID in capital letters: webHelpHI2-all.zip.