Windows Quick and Dirty

Godot Looking API documentation for Windows - the fast way

This is a step by step way of getting the API up and running on windows with minimal explanation of the steps. I am assuming that programmers on windows will not be as familiar with python as their Linux counterparts because Python does not come already installed.

1. Install python

   Goto Python.org and download latest version for windows. run the downloaded file and tick Add Python 3.9 to PATH

   If you want you can dissable path limit at the end of the setup (I think this is advisable as the path limit is an anacronism now)

All of the following is done in a cmd window or (my personal preference) from a cmd terminal in VSCode.

Ensure that Godot is on the sytem path by typing the name of the godot program on the cmd line.

If Godot starts then all is fine. If not then entering system environment in the windows search bar should bring up the link to the system properties dialog where the environment variables can be updated. You can add the path to Godot either in the user or system PATH settings.

2. Create your project directory for the documentation - I suggest keeping it separate from your Game directory.

3. cd into your doc project directory.

   I tend to create a virtual python environment in the document directory as this keeps things tidy.

   If you want to do this then entering

   python -m venv $env
   

   where $env is the name of the virtual environment will create the virtual environment (I tend to use .env so it is hidden, but the name is a free choice for you).

   If you create a virtual environment then activate it with

   $env\Scripts\activate
   

   where $env is again the name you gave to your virtual environment.

   You can deactive the enviroment with deactivate

   Note: The python environemt is purely a local child directory named with your choice of $env. It must be activated from its parent directory for each new cmd window where you want to work with it.

4. Download the modules you will need for the reStructuredText creation with

   pip install godot-api-refs gdscript2rest Pygments Sphinx sphinx-notfound-page sphinx-rtd-theme sphinx-tabs
   

5. Download the zip file of the gdscript-to-restructured repository - make sure you pick the main branch as this has the release version.

6. Open the zip file and extract all the contents to your document project directory - we will delete the bits we don't want next.

7. Delete the folders gdscript-rest-maker and Screenshots and the files .gitignore LICENSE and README.md

8. Test by typing

   generate_reference.bat
   

   which should now bring up the help listing for generate_reference

9. Create the godot help link file godot_api_calls with

   python -m godot_api_refs
   

   this will give the links to the stable branch.

10. Create the reStructuredText documents with

    generate_reference.bat $Path -p docs\source\api -i --doc-version 0.1.0 -v
    

    $Path being the location of your game project directory - this can be either a direct or indirect path.

    Your Godot project should start up, run for a while then shut down. Then, after the rest of the script has run the directory docs\source\api should be populated with the reStructuredText files.

11. Create the website for the documentation by

    cd docs
    

    then

    make html
    

    this should tell you that the HTML pages are in build\html.

12. View the documentation by opening index.html in the build\html directory with your favourite browser (chrome and edge use ctr+o).

    You should be able to navigate through the docs using the tree on the left and the links in the document should all be working.

13. Configure the documentation to suit your project.

    • The docs_logo.png file in the source directory is the graphic that is shown at the top of the navigation sidebar. This can be any graphic that you want and is referenced in the conf.py file.

    • Set up conf.py to suit your project.

      This is a complex file that is set up to generate the Godot look and feel but all that is of real interest are the lines

      project = 'some text" - change this to the name of your project

      copyright = ' copyright' - change this to your copyright notice

      author = 'some name' - change to the authors name

      version = '0.1.0' - change to the current version number

      and further down, in the Options for HTML output, change

      html_logo = "docs_logo.png" to point to the logo file you wish to use.

    • Change index.rst in the source directory (not the API directory) to suit your needs. Refer to the Sphinx documentation on how to do this.

      The file copied over has defaults for Introduction, Standards and API but as created will only show the API on the webpage as the other sections are currently empty.

14. If you change any of the settings in conf.py then the system needs to rebuild the documentation from scratch. In the docs directory type the following commands

    make clean
    

    this removes all the old settings. Then rebuild the documentation again with

    make html