Skip to content

4. Github Wiki

Jump to bottom
Marijana Petojevic edited this page Sep 18, 2023 · 1 revision

The idea of the GitHub Wiki is to equip our developers and contributors with relevant information about main workflows and ensure a basic understanding of our packages exists. Every repository on GitHub.com comes equipped with a section for hosting documentation, called a Wiki. You can use your repository's Wiki to share long-form content about your project, such as how to use it, how you designed it, or its core principles. While a README file quickly tells what your project can do, a wiki can be used to provide additional documentation.

Contributing to Grader Service Github Wiki

There are two possible ways of contributing to the GitHub Wiki:

  1. Adding or Editing Pages directly in your browser (changes will be applied immediately after saving).
  2. Cloning the Wiki locally and then committing changes.

Cloning Github Wiki

GitHub Wiki creates its own 'standalone' repository, which can be cloned as follows:

git clone https://github.com/TU-Wien-dataLAB/Grader-Service.wiki.git

Once you cloned Wiki Repository locally, you can create your own branches to work on. For example:

git checkout -b wiki/new-wiki-documentation

In our GitHub Wiki Repository, the files we are working with are in reStructuredText (.rst) format, the same as in the Sphinx Documentation.

A downside of GitHub Wikis is that there is no interface that allows you to see all of the Wiki remote branches directly on GitHub. To apply and make your changes visible in the GitHub wiki, your branch must be merged into the origin/main branch.

Github Wiki details

Home page

The Home page is an essential part of GitHub Wiki, and its name shouldn't be changed! If you change the name of the Home page, when first loading GitHub Wiki, no Home page will be loaded. Instead, you'll see a list of available pages, which means you won't be able to see a Wiki-like structured page.

Cross referencing

Referencing here won't function the same way as in Sphinx Documentation. For example, in Sphinx, you could have a file named Installation.rst and want to reference its part about requirements in another file named Grader-Labextension.rst the usual way:

# Installation.rst
.. _installation-requirements:

Requirements
------------
# Grader-Labextension.rst
You can check all the needed requirements in :ref:`here <installation-requirements>`.

In GitHub Wikis, every title and subtitle is provided with an online link, which you can reference. So, if you want to reference the requirements from Installation.rst in another file, you just need to provide a link to it:

# Grader-Labextension.rst
You can check all the needed requirements `here <https://github.com/TU-Wien-dataLAB/Grader-Service/wiki/Installation#installation-requirements>`_.

Toctree

The directory tree on the right-hand side of the GitHub Wiki is generated automatically based on your file names in alphabetical order. If you want to have the files listed in a specific order, make sure to add enumeration in front of the file names.

You can also create a custom "sidebar", which is a Markdown file. It won't be generated automatically, so if you want to reference any specific parts of your documentation, you must provide a link to it.

Static files

Static files such as pictures are located in the static/ directory. You can add them to your documents in the usual way:

.. image:: ./static/my_static_file.png
    :alt: this is a picture
Clone this wiki locally