This is the repository of the "Modding Handbook - rF2" source.
The documentation is written in reStructuredText (RST) and generated using Spinx. To work on the source and compile the documentation on your own, you would need at least the following:
- To write documentation or edit RST files, you can use any text editor of your choice. Suggested are Notepad++ https://notepad-plus-plus.org/ and Atom https://atom.io/
- To compile the documentation from source, you need sphinx-doc https://www.sphinx-doc.org
There are a couple of packaging scripts provided. These are very simple bash scripts, intended to work on a Ubuntu Linux OS. Maybe batch scripts for Windows will be added later.
The requirements above mention you need sphinx-doc to "compile" the documentation from source on your machine. To use it, you need to install Python on your computer.
For Windows the installation for that is described in the Getting started using Python on Windows for beginners guide, where you should follow the steps to install Python, optionally Visual Studio Code, and probably Git (if you have not done so already to clone this repository). This version of Python comes with "pip", a package manager for Python which makes the installation of sphinx-doc easy.
You need to install the following packages:
pip install sphinx
pip install sphinx-rtd-theme
pip install sphinxprettysearchresults
pip install readthedocs-sphinx-search
If that worked without generating any error messages, you can go to the folder where you've cloned the git repository and then type:
make html
This will build the whole documentation into a subfolder called build\html so to read that type:
start build\html\index.html
That should open the documentation in your default browser. You can run the make command again after every update you do to the documentation.
To avoid conflicts with existing Python packages, it's recommended to use a virtual environment.
Install packages python3 and python3-env from your package manager in case they're not already installed.
Go to the folder where you've cloned the git repository and create the virtual enviroment with the following command:
python3 -m venv python-env
Activate the virtual environment with command:
source python-env/bin/activate
Notice the command prompt changes when the virtual environment is active to remind you Python commands are using this environment.
You need to install the following packages:
pip install sphinx
pip install sphinx-rtd-theme
pip install sphinxprettysearchresults
pip install readthedocs-sphinx-search
If that worked without generating any error messages then type:
make html
This will build the whole documentation into a subfolder called build\html so to read that type:
xdg-open build/html/index.html
Deactivate the virtual environment by closing the terminal or typing the command:
deactivate
TODO