Developer Area/Mahara manual setup

Introduction

The Mahara manual uses Sphinx and a custom theme. It is hosted by Catalyst. It is an open source project though and can be contributed to. The code is accessible. At the moment, you can't register on that Git repository. If you'd like to contribute, you can:

• Send a change request via our tracker
• Send a mail with your change or ask to have access to the repository

The Mahara manual can be cloned, and you can make changes yourself. If you host it on your own, you can change the URL in your Mahara instance in 'Administration menu → Configure site → Menus'. Keep the overall structure of the manual pages though so that links within Mahara can refer to the correct section in the manual.

The steps outlined below are typically done by Catalyst to set up a new version of the overall manual and set up the translation branches.

The example below uses Mahara version 21.10 as reference. Any reference to it would need to be replaced with the version that you are creating the manual branch for.

Translating the Mahara manual

If you want to translate the Mahara manual, you can do so directly via Launchpad and do not need to install anything on your computer.

You would only need to set up the manual on your computer if you wanted to make changes to it or create your own version of it.

Setup

1. Clone the repository to your computer

 cd ~
 mkdir code
 cd code
 git clone https://git.mahara.org/user-manual/manual.git

2. Follow the instructions to get the install running. Docker is required.

That Readme file outlines how to preview the manual locally, pull in the translations, and get the output, which you could then push to a server and publish your own manual.

Create a new branch (Catalyst)

1. Create a new local branch for the new version of the manual

 git branch
 git checkout -b 21.10_STABLE

2. Replace the information in .git/config with the following.

 [core]
    repositoryformatversion = 0
    filemode = true
    bare = false
    logallrefupdates = true
  [remote "origin"]
    fetch = +refs/heads/*:refs/remotes/origin/*
    url = [email protected]:user-manual/manual.git
  [branch "21.10_STABLE"]
    remote = origin
    merge = refs/heads/21.10_STABLE

3. Publish the new branch to git.mahara.org

 git push origin 21.10_STABLE:refs/heads/21.10_STABLE 

4. Make initial changes to index.php, manual-build/conf-common.py.

Include in build process and set up translation branches in Launchpad

The manual is built automatically for the versions defined and translations are updated automatically as well when new text has appeared.

Typically, the most recent version is updated weekly and older versions may be updated monthly if there are changes. If a translator did a big push to update the translation, the versions in question can be updated manually via the pipelines rather than running a scheduled task.

Catalyst only: Follow the Readme file on the Catalyst internal GitLab instance for the 'manual-builder' project.