Documentation

Want to help make the VPE Documentation better? Great! We’d love any help, whether it’s as small as correcting a typo, adding to a section that isn’t clear, adding your own tutorial, or whatever else you want to change.

How VPE's documentation is built

VPE's documentation site is automatically generated and deployed every time we merge something to our master branch, i.e. when new code was reviewed and approved. It doesn't have to be actual source code, it can also just be documentation, or an updated or changed asset.

You can find the source of the documentation here. We use DocFX, a static site generator that produces documentation from source code, but also from Markdown files. If you're not familiar with Markdown, have a quick look at this site.

Quick changes to an existing page

Updating an existing page is really easy. When you're browsing the doc, there is a Improve this Doc button on every page that leads you to the source at GitHub. There you can edit the page right away and propose a change. The whole flow works as follows:

1. Click on Improve this Doc
2. If you're logged on GitHub, click the pencil icon on the upper-right corner of the page content (otherwise you'll have to login first).
3. Make your change and click on Propose file change. This will create a pull request.
4. Type a short description of what you've changed, and click Create pull request

When we've reviewed and merged your change, it will be online instantly! Details with screenshots of the process can be found here.

Bigger changes or new content

If you want to write a tutorial or document an undocumented feature, it's best to work locally first, build the documentation yourself to test, and then submit the pull request. Given you have an account at GitHub, you'll need to:

1. Fork and clone this repository.
2. Install DocFX. Put it into your PATH environment variable
3. In your locally cloned working directory, navigate to VisualPinball.Unity/Documentation~.
4. Generate the documentation and spawn a local server by typing docfx build --serve

Note

The current docfx version we're using is 2.77.0. You probably want to use the same version, since the our template is dependent on a specific version.

You can then browse the locally generated documentation at http://localhost:8080.

The documentation is currently limited to the Creator's Guide, so navigate to the creators-guide folder and create a new file in whatever sub folder you'd like to complement. Name the file with the .md extension, for "Markdown".

Write your new content. You can put images into the same folder. If you're not sure how to achieve a particular layout, have a look at other pages or the DocFX documentation.

In order to make your new page appear in the sidebar, you'll need to add it to toc.yml. When done, stop the server with CTRL+C and relaunch it (docfx --serve).

Once you're happy with your new content, commit and push your changes, and create a pull request for us to review:

1. Stage your changes. In the Documentation~ folder, type git add *
2. Commit your changes: git commit -m "Some description of what you've done"
3. Push your changes: git push

Go to github.com and create a pull request. Once reviewed and merged, your new content will be published.