Website contributing guide

The website is written in markdown format, created through sphinx. These markdown files can be edited/created/deleted to update/create/remove pages.

In order to contribute to the website, a series of steps should be followed:

  1. Download the code from the website repository
  2. Create a new branch based off the Dev branch.
  3. Make the desired changes to the markdown files located within the source directory.
  4. Preview your changes through:
    • your IDE of choice (look it up for your ide. Visual Studio Code Example)
    • building the website through sphinx and then viewing the html
    • any other markdown viewing program
  5. Upload your changes to a separate branch
  6. Create a pull request to the Dev branch
  7. (Optional) Create a pull request from the Dev branch into the Main branch whenever you are ready for the website to be updated

Adding images to your page

Every image that is contained within the website should be stored within the _static folder located within source. In order to then use that image you must reference it’s location within the markdown page.

As an example:

<div align="center">
	<img align="center" src="../_static/img/Iilluminator.jpg" width="500">
</div>

Which results in a centered image, of width 500 like so:

Building and previewing the website through sphinx

Building and previewing the website before it is uploaded on github is highly recommended. In order to create this preview a series of steps must be followed. Example over command line interface:

  1. Ensure you are in the correct directory with your terminal (your directory should see README.md and source)
  2. Prepare your environment:
    1. python3 -m venv .venv
    2. Activate your work environment:
      • MacOS & Linux: source .venv/bin/activate
      • Windows: .venv\Scripts\activate
    3. pip install -r source/requirements.txt
    4. pip install illuminator --no-deps
  3. Make your changes (if you added a new page make sure to add it to index.rst so its visible in the side-bar)
  4. Build using sphinx:
    • sphinx-build source docs (NOTE: the name docs can be changed if you wish)
    • sphinx-build source docs --fail-on-warning (optional flag, sometimes it works sometimes it does not. The warnings do not break the website build)
  5. Open any html document located within your new folder using your web browser to preview your website
  6. [Important] After you are done and want to push your changes to github you must ensure that you either delete the folder which was created when building this website, or add it to .gitignore if you plan on reusing it (see .gitignore file for examples)