Merge pull request #56 from maths/main

Merge main into dev

cli/config_sample.txt

@@ -33,6 +33,7 @@ $moodleinstances = [
 ];
 
 // Array of moodleinstance nicknames and tokens.
+// Site administration/Server/Web services/Manage tokens
 $token = [
     'instance1' => '4ec...cfcd',
     'instance2' => '6ae...abcd',

doc/createrepo.md

@@ -49,6 +49,16 @@ TODO: note explaining directory structure.
 
 ### Example 3:
 
+Assume Moodle is exactly as in Example 1.
+
+You have a quiz within your course, and you have populated the _quiz_ question bank, rather than the course question bank.  You would like all questions from the quiz question bank,  and all sub-categories, to become files in a sub-directory "gitsync-loc" of your local `$rootdirectory` directory.
+
+Navigate to the view quiz, to get the id of the quiz itself from the URL, e.g. `mod/quiz/view.php?id=547`.  
+
+`php createrepo.php -l module -n=547 -d "gitsync-sub"`
+
+### Example 4:
+
 `php createrepo.php -t 4ec7cd3f62e08f595df5e9c90ea7cfcd -i edmundlocal -r "C:\question_repos" -d "source_1" -l system`
 
 You will need to specify the context of the questions you want to export from Moodle.

doc/localsetup.md

@@ -36,7 +36,7 @@ You need to download the gitsync scripts and set it up locally as described belo
   4) Restart the web server e.g. `systemctl restart apache2`.
 
 ## Setup
-- Open a terminal and clone this repository `git clone https://github.com/maths/moodle-qbank_gitsync.git gitsync`. The repository will be downloaded in a folder `gitsync` inside your current folder.
+- Open a terminal and clone this repository `git clone https://github.com/maths/moodle-qbank_gitsync.git gitsync`. The repository will be downloaded in a folder `gitsync` inside your current folder. If you have a local development environment for Moodle with the gitsync plugin installed, it is recommended to create a new copy of gitsync somewhere else to not confuse the server and the client side.
 - The repository will default to the `main` branch but you may need to switch to another branch if you're testing new features (e.g. `dev` for initial beta testing). In the gitsync directory e.g. `git checkout dev`.
 - In the `cli` folder within `gitsync`, make a copy of `config_sample.txt` and name it `config.php` within the `cli` folder.
 - Update `config.php` with the URLs and names of your Moodle instances.

doc/webservicesetup.md

@@ -22,7 +22,7 @@ This plugin requires the [import as new version](https://github.com/maths/moodle
   - Assigned the role to the user. (Site administration/User/Permissions/Assign system roles)
   - Enable the webservice (Site administration/Server/Web services/External services/qbank_gitsync/Edit) and on the same page 'Show more...' and enable file upload within the webservice.
   - Authorise the user to use the service. (Site administration/Server/Web services/External services/qbank_gitsync/Authorised users)
-- Go to Site administration/Server/Web services/Manage tokens in Moodle and create a token for the user `ws-gitsync-user`.
+- Go to Site administration/Server/Web services/Manage tokens in Moodle and create a token for the user `ws-gitsync-user`. Copy this string and store it somewhere safe as you won't be able to access it anymore once you have left the page! You will need this token later when configuring up the connection to your Moodle installation.
 ![Screenshot of token creation.](../images/Add_token.png)
 - Add roles for the user to give them access to the required courses and questions. If you would like them to have site-wide access, go to Site Administration/Users/Permissions/Assign system roles and give `ws-gitsync-user` Manager role for the webservice to have access to all questions on the site.  If you only want them to have access to particular courses, then make `ws-gitsync-user` Manager on courses individually.
 - If you have user agreements set up for your Moodle site, you will need to accept them on behalf of the Gitsync user. (Site Administration/Users/Privacy and policies/Manage policies/Agreements/Accept)
@@ -38,4 +38,4 @@ Fill in the URL and parameters above in the fields as shown in the screenshot an
 ![Screenshot of Postman.](../images/Postman.png)
 
 ## Additional security
-The token essentially allows question export, import and delete for all contexts for which the webservice user has question edit permissions. It's like a manager password but less obscured - be careful! Restrict the contexts the user has access to for added security and to reduce the chance of user error. **Also create severely limited lifespan tokens and/or restrict the valid IP address.** You can have multiple tokens, each for a different IP address to allow access for different colleagues/computers. 
+The token essentially allows question export, import and delete for all contexts for which the webservice user has question edit permissions. It's like a manager password but less obscured - be careful! Restrict the contexts the user has access to for added security and to reduce the chance of user error. **Also create severely limited lifespan tokens and/or restrict the valid IP address.** You can have multiple tokens, each for a different IP address to allow access for different colleagues/computers.