Writerside Help

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.21565.

docker pull jetbrains/writerside-builder:243.21565
docker pull registry.jetbrains.team/p/writerside/builder/writerside-builder:243.21565

    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:

    docker run --rm -v .:/opt/sources \ -e SOURCE_DIR=/opt/sources \ -e MODULE_INSTANCE=Writerside/hi \ -e OUTPUT_DIR=/opt/sources/output \ -e RUNNER=other \ -e PDF=PDF.xml \ jetbrains/writerside-builder:243.21565

    Alternatively, you can use an env file to define the variables, for example:

    docker run --rm -v .:/opt/sources --env-file=builder.env \ jetbrains/writerside-builder:243.21565

    Where builder.env is a file that sets the variables to specific values, for example:

    SOURCE_DIR=/opt/sources MODULE_INSTANCE=Writerside/hi OUTPUT_DIR=/opt/sources/output RUNNER=other PDF=PDF.xml

    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:

      docker run --rm -v .:/opt/sources \ jetbrains/writerside-builder:243.21565 \ /bin/bash -c " export DISPLAY=:99 && Xvfb :99 & /opt/builder/bin/idea.sh helpbuilderinspect \ --source-dir /opt/sources \ --product Writerside/hi \ --output-dir /opt/sources/output \ --runner other \ -pdf PDF.xml \ "

      When using variables, the container runs the command in quotes taking option values from the provided variables, like this:

      export DISPLAY=:99 && Xvfb :99 & /opt/builder/bin/idea.sh helpbuilderinspect \ --source-dir %SOURCE_DIR% \ --product %MODULE_INSTANCE% \ --output-dir %OUTPUT_DIR% \ --runner %RUNNER% \ -pdf %PDF%

      The following options are required:

      --source-dir, -i

      Specify the directory with documentation sources. When using variables, specify it via SOURCE_DIR.

      --product, -p

      Specify the module and instance that you want to build, separated by a slash /. When using variables, specify it via MODULE_INSTANCE.

      --output-dir, -o

      Specify 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, -r

      Specify 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.

      -pdf

      Specify 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.

      1. Create a Dockerfile with the following contents:

        FROM jetbrains/writerside-builder:243.21565 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/
      2. Build an image from this Dockerfile. In the directory with the Dockerfile, run the following command:

        docker build -t help-website .
      3. 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.

      Last modified: 11 November 2024