Documentation of OpenTrafficCam

This repository provides the full documentation for OpenTrafficCam.

It is generated by MkDocs using the awesome material theme.

The documentation is fully written in Markdown.

Contribute

You can update or correct the content of this documentation by editing existing or creating new Markdown files in /docs (e.g. directly on GitHub or using an IDE like VS Code). A new page needs to be added to the navigation structure in mkdocs.yml. It includes also all settings for the theme.

If you are using VS Code you should consider using the extension markdownlint to write proper Markdown code. The [YAML] extension is useful to lint and autoformat the mkdocs.yml . Markdown All in One could be helpful to write Markdown.

You can commit any changes in any branch except master and gh-pages. To add your changes, create a new branch and open a pull request to master. gh-pages branch contains the generated HTML files for the site and should never be touched.

A ton of additional Markdown features are documented in the material theme reference.

Deployment

MkDocs converts all Markdown files using the settings and navigation defined in mkdocs.yml into a static HTML site. The documentation is hosted on GitHub Pages and will be deployed automatically. After creating, reviewing and merging a pull request to the master branch, a GitHub action will deploy the changes.

Local Development Server

If you want to preview your changes before creating a pull request, here is what you have to do.

Installation

Clone the repository (if not done already). Create a virtual environment and install dependencies. We provide an install script. Open a terminal and start the install script.

sh ./install_dev.sh

The script deletes previous installs, so you can use it to update your local environment.

Run

You can run a local server with autoload. You should always upgrade your venv.

sh ./start_local_server.sh

MkDocs builds the site and starts a local webserver which monitors for changes.

Open http://127.0.0.1:8000 in your browser to access this site. If you change any file inside /docs MkDocs regenerates that site and instantly reloads your browser. This even works great if you change a branch while running mkdocs serve .

To stop the web server, press "Ctrl + C" or by closing the terminal.