Use requirements.txt for docs dependencies

docs/README.md

@@ -1,29 +1,94 @@
-## Generating the Documentation
+# Generating the Tiled Documentation
+
+This guide covers how to generate the Tiled documentation on various platforms using a virtual environment. You'll need Python 3 installed.
+
+## Prerequisites
+
+- Python 3
+- pip (Python package installer)
+
+## Setting Up a Virtual Environment
+
+It's recommended to use a virtual environment to isolate the project dependencies. Here's how to set it up:
+
+### Windows
+
+1. Open Command Prompt and navigate to the project directory.
+2. Create a virtual environment named ".venv":
+   ```cmd
+   python -m venv .venv
+   ```
+3. Activate the virtual environment:
+   ```cmd
+   .venv\Scripts\activate
+   ```
+
+### Linux (Ubuntu, Fedora, RHEL, CentOS) and macOS
+
+1. Open a terminal and navigate to the project directory.
+2. Create a virtual environment named ".venv":
+   ```bash
+   python3 -m venv .venv
+   ```
+3. Activate the virtual environment:
+   ```bash
+   source .venv/bin/activate
+   ```
 
-To generate the Tiled documentation, you need to install Python 3, Sphinx and
-the ReadTheDocs theme.
+## Installing Dependencies
 
-On Ubuntu the following commands could be used:
+After activating the virtual environment, install the required packages using the `requirements.txt` file:
 
-    sudo apt install python3-pip
-    pip3 install sphinx sphinx_rtd_theme myst_parser sphinx_design sphinx_reredirects
+```bash
+pip install -r requirements.txt
+```
 
-Or, alternatively:
+## Generating the Documentation
+
+With the virtual environment activated and dependencies installed, you can generate the documentation by running:
 
-    sudo apt install python3-sphinx-rtd-theme
+```bash
+make html
+```
 
-Then, the documentation can be generated by running:
+On Windows, use:
 
-    make html
+```cmd
+make.bat html
+```
 
 ## Updating Translation Files
 
-The documentation can be translated as well. To update the translation files
-before tagging a new release, the following commands can be used:
+To update the translation files before tagging a new release:
+
+1. Ensure your virtual environment is activated.
+2. Generate the .pot files:
+   ```bash
+   make gettext
+   ```
+3. Update the .po files for German and French:
+   ```bash
+   sphinx-intl update -p _build/gettext -l de -l fr
+   ```
+
+Note: Currently, only German and French translations are hosted. Additional languages can be added if there's sufficient interest in maintaining those translations.
+
+## Deactivating the Virtual Environment
+
+When you're done working on the documentation, you can deactivate the virtual environment:
+
+```bash
+deactivate
+```
+
+## Requirements
+
+The `requirements.txt` file in the documentation directory specifies the required packages and their versions. If you need to view or update these requirements, you can find them in this file.
+
+Remember to activate the virtual environment each time you work on the documentation, and to update your virtual environment if `requirements.txt` changes:
 
-    make gettext
-    sphinx-intl update -p _build/gettext -l de -l fr
+```bash
+pip install -r requirements.txt
+```
 
-Above only German and French are included because they are hosted, but other
-languages could be added in the future if there's enough interest in keeping
-those translations up to date.
+This ensures you're always using the correct versions of the dependencies for building the documentation.