Generate the ManiaScript references
It's possible to generate a simple documentation (functions and variables listing) for the ManiaScript API using a command of ManiaPlanet.exe.
- Locate the folder containing ManiaPlanet.exe.
- Create a new file in this folder and name it "GenerateDoc.bat".
- Edit the file and paste this line inside:
C:\Path\To\Folder\doc.h by the path to the folder where you want the documentation file to be created.
- Save the file and execute it by double clicking on it.
- A command prompt window will be displayed and ManiaPlanet will start.
- You can close ManiaPlanet right after that.
- Check the folder you specified in the command line, you should see a doc.h file inside it. If you open it you will see a listing of all the functions and variables accessible in ManiaScript.
If you take a look at the file generated by ManiaPlanet you will see that it's not really user friendly and not always comfortable to use. Some tools allow you to generate a nicer documentation in a lot of different formats. Here I'll only talk about Doxygen, but there is a lot of other tools available.
You can see how it looks here:
- Download Doxygen on the official website: www.doxygen.org (doxygen-1.8.4-setup.exe at the time of writing)
- Install Doxygen, it should be pretty straightforward. Just be sure to select the Doxywizard GUI component during the process.
- We will try to keep a clean working environment. Create a folder and name it "ManiaScriptDocumentation".
- In this folder create 3 sub-folders:
- Edit the GenerateDoc.bat file that you created earlier in the ManiaPlanet folder to make it generate the documentation in our new Sources folder:
- Run GenerateDoc.bat and check that there is now a doc.h file inside the Sources folder.
- Run Doxywizard (StartMenu > doxygen > Doxywizard).
- In the top field (step 1), select the Working directory you created earlier.
- In the Wizard tab we will configure how the documentation will be generated.
- Project Name: give a name to the documentation.
- Project synopsis: a brief description about the documentation.
- Project version or id: a version number.
- Project logo: a logo to display on the documentation.
- Source code directory: here select the Sources directory we created before.
- Scan recursively: you can leave it unchecked.
- Destination directory: this time select the Documentation directory.
- Leave the default settings.
- Check HTML and select "with navigation panel". You can also change the color of the documentation here.
- Uncheck the other formats (LaTeX, Man pages, RTF, XML).
- Select "Use built-in class diagram generator".
- We won't do anything in the Expert tab, so you can click directly on the Run tab.
- Click on "Run doxygen". Doxygen will now generate the documentation. Once it's done, just click on the "Show HTML output" button to see your brand new documentation in HTML format.
- IMPORTANT: before closing Doxywizard, remember to save your settings. To do that click on File > Save As at the top of the window and save the configuration file into the Working directory.
- You can also click on Settings > Use current settings at startup to load your configuration automatically each time you launch Doxywizard.
You can find a fully working documentation batch generator here (.zip) or here (GitHub).
Follow the ReadMe.txt instruction to get it working.
- Open the Working directory
- Edit the GenerateDoc.bat file
- Change the first three lines
- ManiaPlanetDrive: set the drive letter of the hard disk containing ManiaPlanet
- ManiaPlanetDir: set the directory where the ManiaPlanet.exe is
- DoxygenDir: set the directory where the doxygen.exe is
- Save the file and quit
- Double click on GenerateDoc.bat
- Close the ManiaPlanet window
- Press enter to close the Windows command prompt
- Open the index.html file with your Internet browser to read the documentation