Actions

Developer Area/Mahara manual setup

From Mahara Wiki

< Developer Area
Revision as of 21:32, 17 April 2022 by Anitsirk (talk | contribs) (→‎Include in build process)

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:

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 an example. Any reference to it would need to be replaced with the version that you are creating the manual branch for.

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 on 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

Catalyst only

  1. Build the new version and publish it to GitLab.
    1. Follow the instructions under 'Update the manual-build submodule'.
    2. Create a new schedule in the CI/CD process.
    3. Description: Version (Daily)
    4. Variables: “MAHARA_VERSION” and enter the version number in the field to the right. Just the version number, e.g. '21.10' and not '21.10_STABLE'.
    5. Interval patterns: Select 'Every day' first and then switch to 'Custom' and change the cron time. Note: Do not schedule all builds at the same time but spread things out a bit.
  2. Run the build manually. Note: To see which version of the manual was run, go to Pipelines -> Click the Status icon and then on the next screen click the 'Passed' icon and see the console output.
  3. Clear the Cloudflare cache.
  4. Once ready to have the manual publicly linked: Add the new release to conf-common.py for 'mahara_releases' and 'all_mahara_releases'. Remove the version that is fallen / has fallen out of support from 'mahara_releases'.
  5. Re-assess the auto build frequency of older releases and change them as necessary.
  6. When the new version of Mahara has been released, go to manual-build/source/index.html and change the version number on line 22, i.e. window.location = "https://manual.mahara.org/" + lang + "/21.10/";

Update the manual-build submodule:

  1. Locally, check out the 'manual-builder' repository (Catalyst access only).
  2. Update the submodule with the latest changes made to the 'manual-build' repository: git submodule update --init --remote manual-build
  3. Commit the changes: git commit manual-build

Setting up the translation export branch for Launchpad

This is done by Catalyst

This part is the tricky bit as Launchpad uses bzr for version control. There is a good tutorial on how to work with bzr that can help anyone get started.

The following steps are a bit incomplete, but will hopefully fleshed out in the future.

1. Assumption: Folder code/manual-export/manual-export exists.

2. Create the new folder "21.10_STABLE-export".

3. Generate the potfiles in your manual folder. 

 cd code/manual
 manual-build/build-manual.sh generatepot

4. Go back to the export folder. If the potfiles generation doesn't produce folders in which the potfiles are listed (sometimes it does, sometimes it doesn't), create a folder for each potfile. The folder name needs to match the potfile name (minus the extension). The folders will be empty and don't have the actual potfiles in them. Your folder 21.10_STABLE-export should contain the sub folder "potfiles" and in there a folder for each potfile that has the name of the potfile, but the potfile is not in it.

5. Create the bzr files 

 cd manual-export
 bzr init manual-export/21.10_STABLE-export/

6. Enter your potfiles export folder and commit the folders. 

 cd manual-export/21.10_STABLE-export/
 bzr add potfiles/
 bzr commit
 write commit message

7. Push your newly created branch to Launchpad 

 bzr push lp:~mahara-lang/mahara-manual/21.10_STABLE-export

8. Go to Launchpad and set up the export branch for your translation: https://translations.launchpad.net/mahara-manual/21.10/+translations-settings 

 Under "Exporting translations to branch" click the "Edit" button. Then type into the field / search for the branch:
 ~mahara-lang/mahara-manual/21.10_STABLE-export
 confirm the branch

9. Upload the potfiles into the import branch. Make sure that you set the path to "potfiles/[name of the potfile folder]/[potfile]

Retrieved from ‘https://wiki.mahara.org/index.php?title=Developer_Area/Mahara_manual_setup&oldid=12928’