build: add Dockerfile for local build environment

[skytomo221]

Added Docker Support for Building the Reference Manual

This pull request introduces the following changes:

• Added a Dockerfile: Simplifies the setup process for building the reference manual locally.
• Updated the README: Includes instructions for building and running the manual using Docker.

Motivation

These changes aim to make it easier for contributors and users to build the reference manual without needing to install dependencies manually. Docker provides a consistent and isolated environment for building the project.

Changes

1. Dockerfile:
   • Configured to build the reference manual in a containerized environment.
   • Ensures all necessary dependencies are installed.
2. README Updates:
   • Added a section explaining how to use Docker to build and run the manual.

Related Issue

This pull request is not associated with any existing issue.

[david-christiansen]

I'm a bit nervous about adding a new build method that's not part of CI and that I myself don't regularly use. Users may come to depend on it, which is not great if it bit-rots.

What's the main benefit of Docker here? If it's just making the TeX parts easier, then I plan to just check in the figures along with their source. Does this make it easier to build it and check the examples on Windows?

[david-christiansen]

(and sorry for the slow response, this PR arrived just as I left on summer vacation)

[skytomo221]

Thanks a lot for the feedback!

I understand your concern about adding a build method that is not part of CI. My intention here was not to propose a second “official” way of building the manual, but rather to provide an optional convenience for contributors — especially on Windows, where setting up LaTeX and other dependencies can be tricky. With Docker, everything works out of the box, so new contributors can build and check examples without spending time on environment setup.

In fact, the initial motivation for creating this Dockerfile was to make it easier to work on translations (e.g. Japanese), where being able to quickly build and check the rendered manual is essential. On Windows in particular, this greatly lowers the barrier to entry.

I fully agree that we don’t want something to bit-rot. One way to handle this could be to mark the Docker instructions as an “optional/unsupported” method, so users don’t expect it to be maintained as tightly as the primary build.