

IDeA Labs Wiki

This portion of the lab website is meant to serve as a knowledge base and documentation for various projects and things around the lab. There apparently was some sort of traditional wiki in the past, but it has been lost to the digital abyss by all accounts. This page contains instructions on how the wiki is deployed to the website, how to edit it yourself, and how to submit your changes.

The URL for the wiki is https://wiki.idealabs.byu.edu

Overview

The wiki is hosted on the lab web server, which uses Caddy as the webserver. Following the instructions on the web server page to access the server, the wiki materials can be found at /var/www/wiki. The source code for the wiki is hosted in the GitLab repository at https://gitlab.com/idealabs/wiki, and the web server is configured to automatically pull any changes from the master branch, build the website, and then immediately begin serving the updated wiki. It should be fairly quick to reflect any changes made, and though the initial configuration is a bit complicated, it allows all of this material to be stored in plaintext by a version control platform and be presented in a easy to use, searchable website.

The wiki itself uses Mkdocs to take the static markdown files and generated the website files that is then served by Caddy. Mkdocs is a Python program tha simply converts the files.

Warning

This project and the wiki are publically accessible on the website and at GitLab.com. Do not publish sensitive information here.

Editing and writing in the wiki

Anyone who is part of the IDeA Labs GitLab group should be able to modify the wiki. There are two ways to do so, described in following sections:

1. Editing in your browser via Gitlab.com
2. Running and editing the wiki locally on your computer

The wiki is written using plaintext Markdown files, with a number of extensions provided by the framework Mkdocs and the Material theme for Mkdocs. The following links are the documentation on what you can add and write (things like nifty looking warning cards, etc.), and you can also look at the pages already in this project for examples.

• Mkdocs
  • Getting started
  • Writing your docs
• Mkdocs-Material theme
  • Getting started
  • Extensions
  • More extension options

Editing files in a web browser

There are two ways to begin editing files on Gitlab.com:

1. Click on the pencil icon found on the top right of every page, which will take you to the file to edit, then click on the Edit button described in the following instructions.
2. Go to the project repo at https://gitlab.com/idealabs/wiki, login, navigate to the files you'd like to edit, and follow the instructions below.

Gitlab Web Editor

Local Installation

The second method is to clone the repo, and then edit the files locally as you would any project managed with Git:

1. Install Mkdocs and dependencies
2. Clone the GitLab repository
3. Run the web server
4. Modify the files
5. Use Git to push the changes accordingly

Steps 1-2 only need to be done once, while the rest need to be done everytime you want to edit and run the wiki docs.

Install Mkdocs and dependencies

Tip: First, optionally install Virtualenvwrapper

This isolates Python modules from separate projects and is an excellent practice as you develop in Python. More info can be found here: https://virtualenvwrapper.readthedocs.io/en/latest/install.html

To install and create a virtual enviroment, run the following commands:

$ pip install virtualenvwrapper
$ mkvirtualenv lab-wiki

Then anytime you want to work in this Python environment, you run

$ workon lab-wiki

The wiki has been developed using Python 3, but it should work for Python 2 as well. Install everything using pip with the following command:

$ pip install -r requirements.txt

This installs all of the packages indicated in the requirements.txt file in the wiki repo.

Clone the GitLab repository

$ cd /path/to/where/code/should/reside
$ git clone git@gitlab.com:idealabs/wiki.git

Tip: Checkout a new branch for large modifications

If you have a large change you want to make and track over time without pushing to the live production site, you can create a new branch. Once you're satisfied with the changes, you can then merge that branch with the master branch.

Assuming your current working directory is the wiki folder that you just clone, we can create a new branch:

$ git checkout -b name-of-my-branch

Further information can be found at the following links:

• Feature branch workflow
• What a branch is in Git

Run the webserver

Next, run the wiki server locally and see changes as you make them:

$ mkdocs serve

This opens a webserver (at http://127.0.0.1:8000 by default but it'll tell you otherwise) and watches the source files. If you make any changes, you can visit the wiki at that address in a web browser and see them as they change. After doing the steps above once, you only need to do this step and the following ones to edit the wiki in the future.

Modify the files

Open up your favorite text editor and modify the necessary files.

Use Git to push the changes accordingly

$ git add .                      # Add all files that you'd like to stage for your commit, change as needed
$ git commit -m "Changes dones"  # Commit the files staged by the previous step
$ git push origin master         # Do this the first time pushing
$ git push                       # Do this afterwards, to save on typing effort

Then go to the Merge Requests page, request a new merge with your changes, and review everything.

Note

You can cancel or modify a merge request if you realize you need to make more changes.