Setup

This is a guide on how to setup the tools & processes needed for testing out Amethyst’s docs locally.

Note

This guide is only for PC

1. Install doxygen

Go to Doxygen’s Download Page and download doxygen, then simply install doxygen and add it to your system’s path variable, if not already done automatically.

2. Install Python

Go to Python’s Download Page and install Python with pip included.

Validate if both were installed successfully with running this in your console:

python.exe

As well as:

pip.exe

If one of these couldn’t be found add the file to the system’s path variable, like mentioned before.

3. Install the Dependencies

Open the terminal and navigate to your local amethyst repository clone. Switch into the /docs directory and run:

pip.exe install -r requirements.txt

This install all the needed python dependencies.

4. Install CMake

Go to CMake’s Download Page and install it.

Validate if it was installed successfully with running this in your console:

cmake.exe

If cmake couldn’t be found add the file to the system’s path variable.

5. Build using CMake

Stay in the /docs directory in your local amethyst clone.

Run this to let doxygen do it’s magic and generate the needed data from the C++ headers:

cmake.exe doxygen

This should fill the /docs/source/doxygen folder with a lot of xml files generated by doxygen

Then run this to let breathe do it’s magic and generate rst files from the doxygen data:

cmake.exe breathe_apidoc

This should fill the /docs/source/breathe folder with a lot of rst files generated by breathe

Finally, run this to build html files from the rst files with sphinx:

cmake.exe sphinx_build

The final html files can be found in the /docs/build/html folder. Open the /docs/build/html/index.html file in your browser of choice and enjoy the amazing documentation.

Hint

To modify the docs and learn how to write good doxygen comments/sphinx docs, look at the Amethyst Sphinx docs and the Amethyst Doxygen docs respectively.

Caution

It is recommended to not add these generated files (by breathe and doxygen) to your git, they may end up in a pullrequest, this could cause a lot of problems. That’s also why they listed in the .gitignore.