Add support for the building the manual with a Visual Studio Code development container

[YoRyan]

Visual Studio Code's development containers feature allows us to construct a reproducible, well-defined Linux toolstack to work with our code on our Windows machines. It's the perfect technology to apply to our manual; rather than installing and maintaining the full Python/Sphinx/LaTeX stack, you can let VS Code and Docker do all the work for you!

To use the feature:

1. Install the Dev Containers extension for VS Code and Docker Desktop for Windows 10/11. Start Docker Desktop.
2. In VS Code, press F1 and search for the "Open Folder in Container" command. Browse to the Source\Documentation\Manual folder. After opening the workspace, VS Code will pull the Docker image straight from Sphinx and spin it up.
3. Press Ctrl+Shift+B to build the HTML version of the manual. And that's it! The files will output to the _build directory, just as if you'd used Sphinx for Windows. (Under Terminal > Run Task, I've also included commands to build the PDF manual and to clean the output directory.)

This will hopefully make it much easier for other developers and interested power users to contribute to our manual.

Caveat: You're normally able to use VS Code's Git integration in a development container, but it doesn't work for our use case. That's because the manual is located in a subdirectory, and VS Code doesn't yet detect development container workspaces within subdirectories (microsoft/vscode-remote-release#2413), so you can't open the openrails root folder and get full Git integration. One possible workaround would be to spin off the manual to separate repository, as we are doing for the website.

[cjakeman]

Hi Ryan,

It's the perfect technology to apply to our manual; rather than installing and maintaining the full Python/Sphinx/LaTeX stack, you can let VS Code and Docker do all the work for you!

This sounds so much better than what we're currently doing. Many thanks. Will try it as soon as i have a moment.

One possible workaround would be to spin off the manual to separate repository, as we are doing for the website.

Thanks for suggesting a workaround, but I would argue against something that divorced the Manual from the code. At present, changes to the Manual are the first item on my checklist when reviewing a code PR. If they're in a different repository, I expect they would often be skipped.

[cjakeman]

Hi Ryan,

All worked well for me. I've added some extra notes below for anyone else who wants to try it.

1. Install the Remote Containers extension for VS Code and Docker Desktop for Windows 10/11. Start Docker Desktop.

In my case, installing Docker Desktop also prompted for the WSL 2 Linux kernel.
Make sure Docker Desktop is running before you start Visual Studio Code.

2. In VS Code, press F1 and search for the "Open Folder in Container" command. Browse to the Source\Documentation\Manual folder. After opening the workspace, VS Code will pull the Docker image straight from Sphinx and spin it up.

It's "Remote-Containers: Open Folder in Container"
This takes some time on first use, so be patient.

3. Press Ctrl+Shift+B to build the HTML version of the manual. And that's it! The files will output to the _build directory, just as if you'd used Sphinx for Windows. (Under Terminal > Run Task, I've also included commands to build the PDF manual and to clean the output directory.)

Ctrl+Shift+B is a shortcut for running the default task in the Terminal window, in this case "make html" and you can browse the results at "Source\Documentation\Manual_build\html\index.html"

In the Terminal window, enter "make latexpdf" to build "Source\Documentation\Manual_build\latex\Manual.pdf"

[cjakeman]

Works very well. No issues.

Approved with thanks,

Chris