Skip to content

Guide Toolchain Setup

Description

The Guide website is built with following technologies:

  • Markdown: Widely used, simple description language. All site contents are in this format.
  • MkDocs: Site generator for Markdown format, creates a website from Markdown sources.
  • Python: Programming language used by MkDocs.
  • Git: Version control system for source code. Guide sources are stored in a git repository on GitHub for easy collaboration.

Guide repository is configured to automatically update the website when new changes to the sources are merged.

Prerequisites

If you don't yet have one, create yourself a GitHub account and fork1 the Guide repository: https://github.com/itsnicksia/wizardry-daphne-guide

Installation

Git

Note

The official distribution of git is purely a command-line interface. It is recommended to start with it, but if you find it unpleasant to use, there are many GUI clients available. GitHub also has their own desktop client.

Download and run git installer: https://git-scm.com/downloads/win

The default options are mostly fine, but do read the descriptions before proceeding. Git comes with its own bundled Bash shell, but in this guide we use Windows native PowerShell.

Python

Download and run Python installer: https://www.python.org/downloads/

During install, enable option Add Python [ver] to PATH to use Python from PowerShell.

MkDocs

Start up PowerShell and clone your forked Guide git repository:

PS C:\Users\anon> git clone https://github.com/anon/wizardry-daphne-guide
PS C:\Users\anon> cd wizardry-daphne-guide

Create a Python virtual environment, where MkDocs and all dependencies are installed. This isolates the installation from the system-wide Python files and is highly recommended (but not mandatory).

PS C:\Users\anon\wizardry-daphne-guide> python -m venv .venv

Activate virtual environment:

PS C:\Users\anon\wizardry-daphne-guide> .\.venv\Scripts\Activate.ps1

What to do if activation fails

In case Windows policy has disabled script execution, use this commands to enable it: 

PS C:\> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Finally, install MkDocs and dependencies using pip (Package Installer for Python). List of packages to install comes from requirements.txt, hosted in the git repository:

(.venv) PS C:\Users\anon\wizardry-daphne-guide> pip install -r requirements.txt

Start up your local site:

(.venv) PS C:\Users\anon\wizardry-daphne-guide> mkdocs serve

You can now browse the site at http://127.0.0.1:8000.

Usage

Always re-activate Python virtual environment before starting the site.

PS C:\Users\anon> cd wizardry-daphne-guide
PS C:\Users\anon\wizardry-daphne-guide> .\.venv\Scripts\Activate.ps1
(.venv) PS C:\Users\anon\wizardry-daphne-guide> mkdocs serve

Changes to the site sources are automatically detected and deployed, so you can leave it running for as long as you need it.

  1. Create a clone of the repository. ↩

Comments