Skip to content

How To

RoboWiki is based on files written in markdown (which can be edited with a text editor), and mkdocs.

Installation

Mkdocs requires 'a recent version of Python'. These steps were performed using Python 3.11.

pip3 install mkdocs

Then install the material theme:

pip3 install mkdocs-material

Development

The source files for RoboWiki are written in a specific flavour of Markdown (Python Markdown).

Metadata and Authorship

Each page source should have a yaml metadata header containing information as detailed in the sample below. If you contribute to a page, make sure to add your name in the yaml header in the author list at the top of the file.

---
title: Home
authors:
    - William E. Robinson
date-created: 01-02-2024
last-updated: 03-02-2024
---

Project layout

The directory structure should be self-explanatory. If images are to be used, for organisation's sake, please add any image files required for a file within an images directory within the same directory. If you move a file, please make every effort to update all of the links to it in the documentation (hint: you can use command line tools such as grep or ripgrep to help you find which links must be changed).

Editing and Creating Files

  • Files are named with dashed instead of spaces (correct: this-is-a-file.md, incorrect: this is a file.md).
  • Try to keep pages small-ish. If a page becomes large, consider breaking it down into sub-pages.
  • Use naming conventions for files (e.g. using-numpy.md, using-sklearn.md) to make it easier to create links between files.
  • If you create a new page, try to place at least one link to it in another page.
  • keep linking related information!

Building/ Viewing the Site

To view the site using a development server: run mkdocs serve, then go to http://127.0.0.1:8000/.

To build the site for release: run mkdocs build. The built side will be deposited in the site directory. If you have Make installed, you can just run that and it will execute the build process.

Links to files can be made as if navigating a directory structure. Always use a / in path names and not \! For example, if two files are in the same directory (e.g. data/data), then a link can be made to one like so:

[Text for the link](file_2.md)

If the file to be linked to is in a sub-directory:

[Text for the link](sub_directory/file_2.md)

If the file to be linked to is in the directory above:

[Text for the link](../file_2.md)

And so on.

Useful Commands

  • mkdocs serve - Start the live-reloading docs server.
  • mkdocs build - Build the documentation site.
  • mkdocs -h - Print help message and exit.