Quick Start

Reading

Just point your browser at http://documentation

If you have contributed changes (see below), they may take a few minutes to appear.

Contributing

The general workflow for contributing documentation changes is:

  1. Update your local documentation folder
  2. Make changes using any text editor you want
  3. Preview the changes to verify they’re correct (it’s recommended to use our Visual Code preview system; more instructions below)
  4. Upload the changes

These steps are detailed below:

Download and set up the required software

You only need to do this once:
  1. Make sure you have downloaded or have access to the docs. If you can locate the docs folder inside your game folder, then use that directly. If you don’t know what all of that’s about, then [TODO: explain non-BeamNG workers how to use git or whatever method is used in the future]
  2. Uninstall all versions of Visual Studio Code
  3. Uninstall all versions of Python
  4. Run the documentation all-in-one installer: DocTools.exe
  5. Open Visual Studio Code, go to menu File > Open Folder > navigate to the documentation folder > Select Folder

Update the documentation folder

Always update before you start editing files, as working on outdated files will require extra effort to submit:

  1. If you can locate the docs folder inside your game folder, then you should know how to update that folder. If you don’t know what all of that’s about, then [TODO: explain non-BeamNG workers how to use git or whatever method is used in the future]

Edit existing files

Open the .rst file you want with the editor of your choice, modify it and save the file.

For more information on adding links, images, formatting, etc. you can check:

Note

If you edit files using Visual Studio Code, and notice huge slowdowns while typing text, then:

  1. Go to File > Preferences > Settings > User Settings
  2. Add the following json entry: "restructuredtext.updateOnTextChanged": "false",
  3. Save and restart Visual Studio Code

Preview your changes

You must always preview your changes before uploading them. Use Visual Studio Code to preview changes (you may also use it as your text editor):

  1. Open Visual Studio code
  2. Open the .rst file you want to preview or edit
  3. Use:
  • Ctrl + Shift + R to open a preview tab
  • Ctrl + K,R to open a preview tab on the right side

Each time the file is saved, the preview tab will update a few seconds later

Create new files

Every file represents a documentation page. Each topic should have a separate page.

Most text should go in public/ and then a folder of the corresponding category.

The Internal folder is only there for stuff end-users should not be able to access or understand.

  1. Add a new file, e.g. myfile.rst
  2. Add a section to it:
Sample Section Title
==========================
  1. Reference the file in the parent’s toc:
.. toctree::
  myfile.rst

Upload your changes

  1. If you can locate the docs folder inside your game folder, then you should know how to upload your changed files. If you don’t know what all of that’s about, then [TODO: explain non-BeamNG workers how to use git or whatever method is used in the future]

Auto Building locally

There is a small script you can use to automatically build changes on saving a file and automatically reflect them in your local browser.

Setup

All commands are command line or terminal commands.

  1. If you haven’t already, install node.
  2. If you haven’t already, install gulp by running npm install gulp-cli -g in your terminal
  3. Navigate to the docs folder
  4. Run npm i to install all dependencies

Use

  1. Navigate to docs folder
  2. Run gulp

Alternatively use VS Codes nativ task execution. Press ctrl + p and then type task default. Hit enter.