| commit | e2ef92519a56b250c06f56b74ccad9dd50e861c5 | [log] [tgz] |
|---|---|---|
| author | Michael Jumper <mjumper@apache.org> | Tue Nov 19 16:06:46 2024 -0800 |
| committer | Michael Jumper <mjumper@apache.org> | Tue Nov 19 16:06:46 2024 -0800 |
| tree | c5691090df5890042c7dd3148433aefe337036c2 | |
| parent | aaf8feadae1e78514ad39d2abeb52f2d78b9b0f3 [diff] | |
| parent | e3a93ef0f96ffe445408ad3ac87e7a798ea2cf54 [diff] |
Merge changes from patch branch back to main.
This README is intended to document the build process of the Apache Guacamole manual for technical users who wish to contribute or who simply wish to build the manual themselves.
The latest version of the manual is provided on the Guacamole web site, and snapshot copies of each release are included in the release archives.
The guacamole-manual package is the base documentation for the entire Guacamole stack. It is largely written in the “MyST” flavor of Markdown, with portions of the documentation written in reStructuredText where necessary (the Guacamole protocol reference).
MyST was chosen as the primary format because:
reStructuredText is occasionally necessary because:
The build process involves running the Guacamole manual source through the tooling provided by the Sphinx project, in particular “sphinx-build”.
Building the Guacamole manual from source requires:
The required Python packages can be installed using the “pip” package manager:
$ pip install sphinx sphinx-rtd-theme sphinx-inline-tabs myst-parser
On some systems, the Python 3 version of “pip” may instead be named “pip3”, to maintain compatability with users and scripts that expect Python 2:
$ pip3 install sphinx sphinx-rtd-theme sphinx-inline-tabs myst-parser
If all build requirements have beein installed, the manual can be build by simply running “make”:
$ make
The manual will then be built using Sphinx. Once complete, the entire HTML version of the manual will be available within the build/html/ directory in the root directory of the source tree.
The guacamole-manual package includes a Dockerfile that can be used to build an Apache httpd Docker image that contains the Guacamole user manual.
By building and running the resulting container, a developer can work on the user manual without the need to install Sphinx on their workstation. The resulting container can also be used to serve the manual to Guacamole users on a network.
Docker CE version 1.6 or later is required to build the image.
Build the Guacamole manual container image by running the following command in the directory that contains this Dockerfile:
$ docker image build -t guacamole/manual .
Run the resulting container using the following command:
$ docker container run -p 8080:80 guacamole/manual
You'll see some startup messages from Apache httpd on your terminal when you start up the container. Once the container is running you can then view the HTML version of the manual by accessing http://localhost:8080 using your web browser.
If another process on the host is already using port 8080, you will need to change the corresponding argument in the command used to start the container.
As a developer working on the documentation, it will be necessary to stop the container and run the build again each time you wish to see changes you've made to the documentation source.
Please report any bugs encountered by opening a new issue in the JIRA system hosted at: