Actions

Difference between revisions of "Developer Area/Mahara manual setup"

From Mahara Wiki

< Developer Area
(Update instructions to remove old info that has been superceded by our automatic process)
 
(9 intermediate revisions by the same user not shown)
Line 1: Line 1:
=Introduction=
+
===Introduction===
  
The [http://manual.mahara.org Mahara user manual] uses a number of tools to generate the end product. The [http://www.slideshare.net/4nitsirk/catalyst-pizza-thursdaytalkmaharamanual20120607 presentation by Kristina Hoeppner] illustrates the process and tools used briefly.
+
The [https://manual.mahara.org Mahara manual] uses [https://www.sphinx-doc.org/ Sphinx] and a custom theme. It is hosted by Catalyst. It is an open source project though and can be contributed to. The [https://git.mahara.org/user-manual/manual code] is accessible. At the moment, you can't register on that Git repository. If you'd like to contribute, you can:
  
The following are notes for setting up a new branch for the user manual which is generally done by Catalyst. It requires that Sphinx is already installed. The example below uses Mahara version 15.10 as an example. Any reference to it would need to be replaced with the version that you are creating the manual branch for.
+
*[https://bugs.launchpad.net/mahara-manual/+filebug Send a change request via our tracker]
 +
*Send [mailto:info@mahara.org a mail] with your change or ask to have access to the repository
  
=Set up Python locally=
+
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.
  
A Python developer recommended to set up a virtual environment instead of installing Sphinx directly as root.
+
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.
  
Set up the folder for the user manual.
+
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.
  
  cd code
+
=== Translating the Mahara manual ===
  mkdir manual1510
+
If you want to translate the Mahara manual, you can do so directly via [https://translations.launchpad.net/mahara-manual Launchpad] and do not need to install anything on your computer.
  
Please follow the [http://docs.python-guide.org/en/latest/dev/virtualenvs/ instructions] for setting up, activating and deactivating a virtual environment. It should be installed in this folder under the default "venv" folder (will be created as part of the setup). That folder is then part of gitignore and will not be committed back to the project. If you call your folder differently, you need to update .gitignore.
+
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.
  
=Setting up a new local and remote branch=
+
===Setup===
  
1. Do a checkout of the code in the new folder for the manual:
+
1. Clone the repository to your computer
  
via SSH:
+
  cd ~
 +
  mkdir code
 
   cd code
 
   cd code
   git clone git@git.mahara.org:user-manual/manual.git manual1510
+
   git clone https://git.mahara.org/user-manual/manual.git
 +
 
 +
2. [https://git.mahara.org/user-manual/manual-build 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.
  
via HTTPS:
+
===Create a new branch (Catalyst)===
  cd code
 
  git clone https://git.mahara.org/user-manual/manual.git manual1510
 
  
2. Create a new local branch for the new version of the manual
+
1. Create a new local branch for the new version of the manual
  
 
   git branch
 
   git branch
   git checkout -b 15.10_STABLE
+
   git checkout -b 21.10_STABLE
  
3. Replace the information in .git/config with the following.
+
2. Replace the information in .git/config with the following.
  
 
   [core]
 
   [core]
Line 43: Line 47:
 
     fetch = +refs/heads/*:refs/remotes/origin/*
 
     fetch = +refs/heads/*:refs/remotes/origin/*
 
     url = [email protected]:user-manual/manual.git
 
     url = [email protected]:user-manual/manual.git
   [branch "15.10_STABLE"]
+
   [branch "21.10_STABLE"]
 
     remote = origin
 
     remote = origin
     merge = refs/heads/15.10_STABLE
+
     merge = refs/heads/21.10_STABLE
 
 
 
 
4. Publish the new branch on git.mahara.org
 
 
 
  git push origin 15.10_STABLE:refs/heads/15.10_STABLE
 
 
 
5. Make initial changes to index.php, config.py, mahara/links.html to reflect that you are now dealing with a new version of the manual. Commit the changes and push them to git.mahara.org.
 
 
 
=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 [http://doc.bazaar.canonical.com/latest/en/mini-tutorial/ 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 "15.10_STABLE-export".
 
 
 
3. Generate the potfiles in your manual folder.
 
 
 
  cd code/manual1510
 
  sphinx-build -b gettext source potfiles
 
 
 
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 15.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/15.10_STABLE-export/
 
 
 
6. Enter your potfiles export folder and commit the folders.
 
 
 
  cd manual-export/15.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/15.10_STABLE-export
 
  
8. Go to Launchpad and set up the export branch for your translation: https://translations.launchpad.net/mahara-manual/15.10/+translations-settings
 
  
  Under "Exporting translations to branch" click the "Edit" button. Then type into the field / search for the branch:
+
3. Publish the new branch to git.mahara.org
  ~mahara-lang/mahara-manual/15.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]
+
  git push origin 21.10_STABLE:refs/heads/21.10_STABLE
  
=Add new manual to the package for generating it on the server=
+
4. Make initial changes to index.php, manual-build/conf-common.py.
  
Once the new user manual has been set up and pushed to git.mahara.org, the server also needs to know that this version of the manual needs to be generated. The correct repository for that is [https://git.mahara.org/user-manual/manual-packaging https://git.mahara.org/user-manual/manual-packaging]. There, the file '''maharadocs.cron.daily''' needs to be updated to include the following line.
+
===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.
  
  make -C $INSTALLDIR update html epub latexpdf MAHARA=15.10  >> $LOGFILE 2>&1
+
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.
  
This change then needs to be applied to the server itself. The server is managed by [http://catalyst.net.nz Catalyst IT].
+
'''Catalyst only:''' Follow the Readme file on the Catalyst internal GitLab instance for the 'manual-builder' project.

Latest revision as of 22:29, 12 April 2023

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