Create the reStructuredText documents

To create the reStructuredText documents it is sufficient to run

python3 -m gdscript2rest $ReferenceFile.json

where $ReferenceFile.json is the path to the file created in generate-reference. The program will output the files in a subdirectory called export.

If you run python3 -m gdscript2rest -h your will get:

python3 -m gdscript2rest -h
usage: gdscript2rest [-h] [-p PATH] [-i] [-v] [--dry-run] [-V] [--doc-version DOC_VERSION] files [files ...]

Converts JSON data dumped by Godot's GDScript language server to create .rst files for use with Sphinx.

positional arguments:
  files                 A list of paths to JSON files.

optional arguments:
  -h, --help            show this help message and exit
  -p PATH, --path PATH  Path to the output directory.
  -i, --make-index      If this flag is present, create and index.rst page with a table of contents.
  -v, --verbose         Set the verbosity level. For example -vv sets verbosity to level 2. Defalt: 0.
  --dry-run             Run the script at max verbosity without creating files. For debugging purposes.
  -V, --version         Print the version number and exit,
  --doc-version DOC_VERSION
                        Set the document version number if there is no version set in the JSON file. Defaults to 0.0.0

A fuller explanation of the options is:

• files :-> this is a list of files generated by generate-reference that is used as the input to the program
• -h --help :-> prints out the above usage statement and exits.
• -p PATH, --path PATH :-> outputs the reStructuredText files to PATH, this can be either an absolute or relative path
• -i :-> Creates an index file index.rst. This file is a very basic file with a single toctree entry that globs all the files in its directory
• -v, --verbose :-> Prints out information as the program progresses. Not over helpful but could aid in finding problems.
• --dry-run Run the script at max verbosity without creating files. (For debugging purposes.)
• -V, --version Print the version number and exit,
• --doc-version DOC_VERSION :-> Unless I'm missing something Godot doesn't currently have the facility to store a version number so this gives the option to set the version number manually. If not used the version number defaults to 0.0.0

Continuing on from creating a reference.json file where we had a file structure of:

sample-doc-project/
┣ baddies/
┃ ┗ reference.json
┣ docs/
┣ godot-scripts/
┃ ┣ Collector.gd
┃ ┣ README.md
┃ ┣ ReferenceCollector.gd
┃ ┗ ReferenceCollectorCLI.gd
┣ .gitignore
┣ goodies/
┃ ┗ reference.json
┣ LICENSE
┣ README.md
┗  generate_reference

After creating a source/api folder within docs then running python3 -m gdscript2rest goodies/reference.json -p docs/source/api/goodies followed by python3 -m gdscript2rest baddies/reference.json -p docs/source/api/baddies we should get

sample-doc-project/
┣ baddies/
┃ ┗ reference.json
┣ docs/
┃ ┗source/
┃   ┗ api
┃     ┣ baddies
┃     ┃  ┗ (all your baddies .rst files)
┃     ┗  goodies
┃        ┗ (all your goodies .rst files) 
┣ godot-scripts/
┃ ┣ Collector.gd
┃ ┣ README.md
┃ ┣ ReferenceCollector.gd
┃ ┗ ReferenceCollectorCLI.gd
┣ .gitignore
┣ goodies/
┃ ┗ reference.json
┣ LICENSE
┣ README.md
┗  generate_reference

If you add the -i option to the command the an index.rst file is created in the output directory. The file is very simple and consists of

YourProjectName
===============

Version: 0.1.0

Contents
--------

..  toctree::
    :maxdepth: 1
    :caption: API
    :glob:

    *

This removes the necessity of listing the individual .rst files in a toctree listing.