me/breccia-mapper
1
0
Fork 0
mirror of https://github.com/Southampton-RSG/breccia-mapper.git synced 2026-03-03 03:17:07 +00:00
Code Issues Packages Projects Releases Wiki Activity

[DOCS] Proof-reading

Browse Source
This commit is contained in:
Matthew Grove
2023-03-26 18:33:47 +01:00
parent 74b6b3b27d
commit f69b7aa1f0
5 changed files with 85 additions and 85 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docs/source/1-deployment.md
View File

@@ -5,7 +5,7 @@ Ansible deployment has been tested on RHEL7 and RHEL8.
## Choosing How to Deploy
If you are an organisation deploying the app on a server, [Ansible](#ansible) is recommended. If Ansible is not used with your server, [Docker Compose](#docker-compose) or [][Vagrant](#vagrant) are recommended.
If you are an organisation deploying the app on a server, [Ansible](#ansible) is recommended. If Ansible is not used on your server, [Docker Compose](#docker-compose) or [Vagrant](#vagrant) are recommended.
If you are an individual deploying the app on your local machine, [Docker (for individuals)](#docker-for-individuals) is recommended. However, if you are planning on making the app accessible to other people (outside your computer), we advise deploying the app on a server.
@@ -16,7 +16,7 @@ Prerequisites:
- [Ansible](https://www.ansible.com/)
:::{note}
Deployment with Ansible has been tested on RHEL7 and RHEL8, but is compatible with other Linux distributions with minor changes to the playbook (`deploy/playbook.yml`)
Deployment with Ansible has been tested on RHEL7 and RHEL8, but is compatible with other Linux distributions with minor changes to the playbook (`playbook.yml`)
:::
To deploy the BRECcIA Network Mapper with Ansible:
@@ -163,7 +163,7 @@ Prerequisites:
- [Docker Compose](https://docs.docker.com/compose) is installed and running. If you are not familiar with Docker, we recommend using [Docker Desktop](https://docs.docker.com/desktop/). Simply install and run it.
To deploy the BRECcIA Network Mapper with Docker Desktop:
To deploy the BRECcIA Network Mapper with Docker:
1. Download `deploy-docker.zip` [from the latest release](https://github.com/Southampton-RSG/breccia-mapper/releases/latest).
2. Extract the zip file into an appropriate folder.

104
docs/source/2-configuration.md
View File

@@ -2,8 +2,8 @@
After installing the Network Mapper, some configuration must be done in the web interface. You will need to log in with an admin account.
:::{important}
Admin dashboard: this is the admin section of the site, accessed by clicking `Admin` on the navigation bar at the top.
:::{info}
Admin dashboard: this is the admin section of the site, accessed by clicking `Admin` in the navigation bar at the top of the screen.
:::
## Setup
@@ -50,32 +50,32 @@ Then click `Save`.
There are several general settings which must be configured. Open the admin dashboard and click `Config` under `CONSTANCE`, then configure the available settings, as explained below.
1. `CONSENT_TEXT`: The text shown to users when requesting consent to use their data. This text accompanies a checkbox captioned `I have read and understood this information and consent to my data being used in this way`.
2. `PERSON_LIST_HELP`: Help text to display at the top of the people list.
3. `ORGANISATION_LIST_HELP`: Help text to display at the top of the organisaton list.
4. `RELATIONSHIP_FORM_HELP`: Help text to display at the top of relationship forms.
5. `HOMEPAGE_HEADER_IMAGE_SHRINK`: Whether the homepage header image should be shrunk to display the whole image at all times.
6. `HOMEPAGE_HEADER_IMAGE`: The header image for the homepage.
7. `HOMEPAGE_CARD_1_TITLE`: The title for the first card displayed on the homepage.
8. `HOMEPAGE_CARD_1_DESCRIPTION`: The description for the first card displayed on the homepage.
9. `HOMEPAGE_CARD_1_ICON`: The icon for the first card displayed on the homepage. Icons are FontAwesome 6 icons, which are listed [here](https://fontawesome.com/v6/search?m=free).
10. `HOMEPAGE_CARD_2_TITLE`: The title for the second card displayed on the homepage.
11. `HOMEPAGE_CARD_2_DESCRIPTION`: The description for the second card displayed on the homepage.
12. `HOMEPAGE_CARD_2_ICON`: The icon for the second card displayed on the homepage. Icons are FontAwesome 6 icons, which are listed [here](https://fontawesome.com/v6/search?m=free).
13. `HOMEPAGE_CARD_3_TITLE`: The title for the third card displayed on the homepage.
14. `HOMEPAGE_CARD_3_DESCRIPTION`: The description for the third card displayed on the homepage.
15. `HOMEPAGE_CARD_3_ICON`: The icon for the third card displayed on the homepage. Icons are FontAwesome 6 icons, which are listed [here](https://fontawesome.com/v6/search?m=free).
16. `HOMEPAGE_ABOUT_TITLE`: The title for the about section on the homepage.
17. `HOMEPAGE_ABOUT_CONTENT`: The content for the about section on the homepage. HTML is accepted.
18. `HOMEPAGE_ABOUT_IMAGE`: The image for the about section on the homepage.
19. `NOTICE_TEXT`: Text to be displayed in a notice banner at the top of every page.
20. `NOTICE_CLASS`: CSS class to use for background of the notice banner.
21. `PARENT_PROJECT_NAME`: The name of the project's parent project, if one exists.
22. `PROJECT_LEAD`: The project's lead person, organisation, or similar.
23. `PROJECT_TAGLINE`: The project's tagline.
24. `ALLOW_SIGNUPS`: Whether new users should be able to sign themselves up through the site. This is useful for minimising the number of users that must be manually created, and it is recommended that this feature is disabled once all users have created their accounts.
25. `ENABLE_GOOGLE_LOGIN`: Whether login through Google should be enabled. Only enable this if Google login has been configured. See [Google login](#google).
25. `ENABLE_MICROSOFT_LOGIN`: Whether login through Microsoft should be enabled. Only enable this if Microsoft login has been configured. See [Microsoft login](#microsoft).
- `CONSENT_TEXT`: The text shown to users when requesting consent to use their data. This text accompanies a checkbox captioned `I have read and understood this information and consent to my data being used in this way`.
- `PERSON_LIST_HELP`: Help text to display at the top of the people list.
- `ORGANISATION_LIST_HELP`: Help text to display at the top of the organisaton list.
- `RELATIONSHIP_FORM_HELP`: Help text to display at the top of relationship forms.
- `HOMEPAGE_HEADER_IMAGE_SHRINK`: Whether the homepage header image should be shrunk to display the whole image at all times.
- `HOMEPAGE_HEADER_IMAGE`: The header image for the homepage.
- `HOMEPAGE_CARD_1_TITLE`: The title for the first card displayed on the homepage.
- `HOMEPAGE_CARD_1_DESCRIPTION`: The description for the first card displayed on the homepage.
- `HOMEPAGE_CARD_1_ICON`: The icon for the first card displayed on the homepage. Icons are FontAwesome 6 icons, which are listed [here](https://fontawesome.com/v6/search?m=free).
- `HOMEPAGE_CARD_2_TITLE`: The title for the second card displayed on the homepage.
- `HOMEPAGE_CARD_2_DESCRIPTION`: The description for the second card displayed on the homepage.
- `HOMEPAGE_CARD_2_ICON`: The icon for the second card displayed on the homepage. Icons are FontAwesome 6 icons, which are listed [here](https://fontawesome.com/v6/search?m=free).
- `HOMEPAGE_CARD_3_TITLE`: The title for the third card displayed on the homepage.
- `HOMEPAGE_CARD_3_DESCRIPTION`: The description for the third card displayed on the homepage.
- `HOMEPAGE_CARD_3_ICON`: The icon for the third card displayed on the homepage. Icons are FontAwesome 6 icons, which are listed [here](https://fontawesome.com/v6/search?m=free).
- `HOMEPAGE_ABOUT_TITLE`: The title for the about section on the homepage.
- `HOMEPAGE_ABOUT_CONTENT`: The content for the about section on the homepage. HTML is accepted.
- `HOMEPAGE_ABOUT_IMAGE`: The image for the about section on the homepage.
- `NOTICE_TEXT`: Text to be displayed in a notice banner at the top of every page.
- `NOTICE_CLASS`: CSS class to use for the background of the notice banner.
- `PARENT_PROJECT_NAME`: The name of the project's parent project, if one exists.
- `PROJECT_LEAD`: The project's lead person, organisation, or similar.
- `PROJECT_TAGLINE`: The project's tagline.
- `ALLOW_SIGNUPS`: Whether new users should be able to sign themselves up through the site. This is useful for minimising the number of users that must be manually created, and it is recommended that this feature is disabled once all users have created their accounts.
- `ENABLE_GOOGLE_LOGIN`: Whether login through Google should be enabled. Only enable this if Google login has been configured. See [Google login](#google).
- `ENABLE_MICROSOFT_LOGIN`: Whether login through Microsoft should be enabled. Only enable this if Microsoft login has been configured. See [Microsoft login](#microsoft).
Then click `Save`.
@@ -83,20 +83,20 @@ Then click `Save`.
There are several types of questions, but they all have the same set of information stored in them:
- Version: The version of the question - this should be incremented when the question is altered.
- Text: The main text of the question.
- Filter text: Each question appears as a filter on the `Network` page. This is alternative text to replace the full question as the filter title. If left blank, the main text of the question will be used.
- Help text: Help text shown below the question when people enter their answer.
- Answer is public: Whether answers to this question should be considered public.
- Is multiple choice: Whether users should only be allowed to select multiple options, instead of just one.
- Hardcoded field: The name of the hardcoded field that the question relates to. This is not applicable for non-default questions.
- Allow free text: Whether users should be allowed to enter their own text in addition to choosing an available option. When a user enters free text, a new option will be created with their input.
- Order: The priority order for the question to be displayed in. Lower priority questions will be displayed earlier in the list of questions.
- `Version`: The version of the question - this should be incremented when the question is altered.
- `Text`: The main text of the question.
- `Filter text`: Each question appears as a filter on the `Network` page. This is alternative text to replace the full question as the filter title. If left blank, the main text of the question will be used.
- `Help text`: Help text shown below the question when people enter their answer.
- `Answer is public`: Whether answers to this question should be considered public.
- `Is multiple choice`: Whether users should only be allowed to select multiple options, instead of just one.
- `Hardcoded field`: The name of the hardcoded field that the question relates to. This is not applicable for non-preset questions (i.e. ones that you create).
- `Allow free text`: Whether users should be allowed to enter their own text in addition to choosing an available option. When a user enters free text, a new option will be created with their input.
- `Order`: The priority order for the question to be displayed in. Lower priority questions will be displayed earlier in the list of questions.
- Question choices
- Text: The main text of the option.
- Order: The priority order for the option to be displayed in. Lower priority options will be displayed earlier in the list of options.
- Is negative response: Only applicable for relationship questions. Whether the option indicates the relationship is of the lowest level of closeness. This allows automatic population of questions if the relationship being reported is not at all close. All options marked as negative responses will be selected when this button is pressed.
- Delete?: Whether the option should be deleted when the question is saved.
- `Text`: The main text of the option.
- `Order`: The priority order for the option to be displayed in. Lower priority options will be displayed earlier in the list of options.
- `Is negative response`: Only applicable for relationship questions. Whether the option indicates the relationship is of the lowest level of closeness. This allows automatic population of questions if the relationship being reported is not at all close. All options marked as negative responses will be selected when this button is pressed.
- `Delete?`: Whether the option should be deleted when the question is saved.
There are various types of questions, which can be added by clicking `Add` next to the appropriate section in the admin dashboard:
@@ -125,23 +125,27 @@ At least one organisation must also exist for people to be able to create their
Organisations are created through the main site (not the admin dashboard).
1. Click `Organisations` in the banner at the top of the screen.
1. Click `Organisations` in the navigation bar at the top of the screen.
2. Click `New Organisation` at the top of the page.
2. Answer the questions shown.
4. Finally click `Submit`.
### People
Organisations are created through the main site (not the admin dashboard). People should only be created when it is known that the person will not have a login of their own to the site - e.g. for researchers logging data for multiple individuals.
:::{info}
When a `Person` is created for a user who does not have an account, an anonymous account is created for them - with login disabled and a random username (starting `autogen_`). This allows administrators to edit their details on their behalf. You should not delete these users unless you wish to delete all data relating to that person.
:::
1. Click `People` in the banner at the top of the screen.
People are created through the main site (not the admin dashboard). People should only be created when it is known that the person will not have a login of their own to the site - e.g. for researchers logging data for multiple individuals.
1. Click `People` in the navigation bar at the top of the screen.
2. Click `New Person` at the top of the page.
2. Answer the questions shown.
4. Finally click `Submit`.
## Federated Login
Federated login is supported for Google an Microsoft accounts, and can be set up through the `Social Accounts` section of the admin dashboard.
Federated login is supported for Google an Microsoft accounts, and can be set up through the `SOCIAL ACCOUNTS` section of the admin dashboard.
### Google
@@ -158,7 +162,7 @@ Then:
- Click `Choose all` under the `Available sites` box, to enable Google login on this site.
- Click `Save`.
Then enable Google login with the `ENABLE_GOOGLE_LOGIN` option in the `Config` section of the admin dashboard.
Then enable Google login with the `ENABLE_GOOGLE_LOGIN` option in the `Config` section of the admin dashboard, as per [these instructions](#main-configuration-options).
### Microsoft
@@ -175,14 +179,14 @@ Then:
- Click `Choose all` under the `Available sites` box, to enable Google login on this site.
- Click `Save`.
Then enable Microsoft login with the `ENABLE_MICROSOFT_LOGIN` option in the `Config` section of the admin dashboard.
Then enable Microsoft login with the `ENABLE_MICROSOFT_LOGIN` option in the `Config` section of the admin dashboard, as per [these instructions](#main-configuration-options).
## Inviting Users
In the admin dashboard, click `Add` next to `Users`. Choose a username for them, enter their email address, and enter a temporary password. It does not matter what this password is, and you do not need to remember or store it, as the new user is automatically sent an email welcoming them to the platform and containing instructions for how to reset their password.
In the admin dashboard, click `Add` next to `Users`. Choose a username for them, enter their email address, and enter a temporary password. It does not matter what this password is, and you do not need to remember or store it, as the new user is automatically sent an email welcoming them to the platform and providing instructions for how to reset their password.
If the user you wish to invite already has a `Person` created for them, they will already have an account with a random username and login disabled. To find this account, go to `People` (in the `People` section) in the admin dashboard and select the appropriate person. Then click the blue eye icon next to the `User` field.
If the user you wish to invite has already had a `Person` created for them, they will already have an account with login disabled and a random username (starting `autogen_`). To find this account, go to `People` (in the `PEOPLE` section) in the admin dashboard and select the appropriate person. Then click the blue eye icon next to the `User` field.
![Person's user relation with blue eye icon](images/2-person-user.png "Person's user relation with blue eye icon")
This will take you to the user, and you can then change their username along with add a first name, last name, and email address. Note that a welcome email will not be sent to the user in this case, so you will have to let them know that their account is active and what their username is. They can use the *forgot password* option when logging in to set their password.
This will take you to the user, and you can then change their username and add a first name, last name, and email address. Note that a welcome email will not be sent to the user in this case, so you will have to let them know that their account is active and what their username is. They can use the *forgot password* option when logging in to set their password.

28
docs/source/3-admin-usage.md
View File

@@ -2,13 +2,13 @@
You will need to log in with an administrator account to perform these actions.
:::{important}
Admin dashboard: this is the admin section of the site, accessed by clicking `Admin` on the navigation bar at the top.
:::{info}
Admin dashboard: this is the admin section of the site, accessed by clicking `Admin` in the navigation bar at the top of the screen.
:::
## Inviting Users
Please see [Configuration](2-configuration#inviting-users).
Please see {doc}`Configuration <2-configuration#inviting-users>`.
## Deleting Users
@@ -47,28 +47,28 @@ The user you wish to make an administrator must already exist. Then:
## View a Map of People and Organisations
To view an interactive map showing people and organisations that have recorded their locations, click `Map` in the banner at the top of the screen. You can toggle the visibility of people and organisations with the buttons at the top of the page.
Nodes for people on the map have the same colour as the buttons at the top of the page. Nodes can be clicked the name of the person or organisation they represent, and this can be clicked to view their profile.
:::{note}
This page is only available to administrators.
:::
To view an interactive map showing people and organisations that have reported their locations, click `Map` in the navigation bar at the top of the screen. You can toggle the visibility of people and organisations with the buttons at the top of the page.
`Person` nodes on the map have the same colour as the buttons at the top of the page. Nodes can be clicked to show the name of the person or organisation they represent, and these in turn can be clicked to view the person's or organisation's profile.
## View a Graph of the Network
The network mapper provides an interface to view the network as a graph. To access it, click `Network` in the banner at the top of the screen. This graph can be customised with various filters as shown on the page. Setting the date will show the state of the network as it was on the given date. People and organisations can be anonymised, organisations can be hidden, and the graph can be downloaded as an image. These options are all available as buttons on the page.
:::{note}
This page is only available to administrators.
:::
The network mapper provides an interface to view the network as a graph. To access it, click `Network` in the navigation bar at the top of the screen. This graph can be customised with various filters as shown on the page. Setting the date will show the state of the network as it was on the given date. People and organisations can be anonymised, organisations can be hidden, and the graph can be downloaded as an image. These options are all available as buttons on the page.
The graph can also be manipulated with the mouse.
:::{note}
This page is only available to administrators.
:::
## Export Data
All data relating to the network can be exported as CSV files. To do this, click `Export` in the banner at the top of the screen, then click `Export` next to the data you wish to export. This can then be manipulated as a spreadsheet or with a tool like R to perform more complex data analysis than is available natively in the network mapper.
:::{note}
This page is only available to administrators.
:::
All data relating to the network can be exported as CSV files. To do this, click `Export` in the navigation bar at the top of the screen, then click `Export` next to the data you wish to export. This can then be manipulated as a spreadsheet or with a tool like R to perform more complex data analysis than is available natively in the network mapper.

28
docs/source/4-general-usage.md
View File

@@ -11,43 +11,43 @@ Until you have created your profile, you will be prompted to do so. You cannot a
2. Fill in your name and continue to the next step.
3. Provide consent for your data to be stored and continue to the next step.
4. Fill in the questions shown, and find your location on the map at the bottom of the page (if available). Click your location to select it.
5. Finally click `Save`.
5. Click `Save`.
## Update Your Profile
Click the `Profile` button in the navigation bar at the top of the screen. If you have not yet provided consent for your data to be stored, you will first be asked for this. You will then be presented with your profile.
Click `Profile` in the navigation bar at the top of the screen. If you have not yet provided consent for your data to be stored, you will first be asked for this. You will then be presented with your profile.
1. Click `Update`
2. Update your answers to the questions, and optionally update your location on the map at the bottom of the page (if available). Click your location to select it.
3. Finally click `Save`.
3. Click `Save`.
## Add a Relationship
1. Click `People` in the banner at the top of the screen.
1. Click `People` in the navigation bar at the top of the screen.
2. Locate the person you wish to record a relationship with and click `Add Relationship` next to their name.
3. If you have no relationship with this person, you can click the `Autofill` button at the top of the page to automatically fill in appropriate responses. Otherwise, fill in the listed questions.
4. Finally click `Submit`.
3. If you have an existing but very limited relationship with this person, you can click the `Autofill` button at the top of the page to automatically fill in appropriate responses. This will default your relationship to the lowest level of closeness. Otherwise, fill in the listed questions.
4. Click `Submit`.
## Update a Relationship
1. Click `People` in the banner at the top of the screen.
1. Click `People` in the navigation bar at the top of the screen.
2. Locate the person you wish to update your relationship with and click `Update Relationship` next to their name.
3. If you have an existing but very limited relationship with this person, you can click the `Autofill` button at the top of the page to automatically fill in appropriate responses. This will default your relationship to the lowest level of closeness. Otherwise, fill in the listed questions.
4. Finally click `Submit`.
4. Click `Submit`.
## End a Relationship
1. Click `People` in the banner at the top of the screen.
1. Click `People` in the navigation bar at the top of the screen.
2. Locate the person you wish to record a relationship with and click `Profile` next to their name.
4. Click `End Relationship` at the top of the page.
## Create an Activity
1. Click `Activities` in the banner at the top of the screen.
1. Click `Activities` in the navigation bar at the top of the screen.
2. Click `New Activity` at the top of the page.
2. Answer the questions shown.
4. Finally click `Submit`.
4. Click `Submit`.
:::{note}
Once an ativity has been created, it can only be edited by administrators.
@@ -57,7 +57,7 @@ Once an ativity has been created, it can only be edited by administrators.
Once an activity has been created, users should record their attendance.
1. Click `Activities` in the banner at the top of the screen.
1. Click `Activities` in the navigation bar at the top of the screen.
2. Locate the activity you wish to record attendance for and click `Details` next to its name.
3. At the top of the page, click `Attend`.
@@ -65,7 +65,7 @@ Once an activity has been created, users should record their attendance.
Once an activity has been created, users should record their attendance. They can also remove their attendance after previously registering it.
1. Click `Activities` in the banner at the top of the screen.
1. Click `Activities` in the navigation bar at the top of the screen.
2. Locate the activity you wish to record attendance for and click `Details` next to its name.
3. At the top of the page, click `Cancel Attendance`.
@@ -75,7 +75,7 @@ To manage your account details, click your username in the top right corner of t
![Click your username to open your account details](images/4-open-account-details.png)
Alternatively, you can manage your account by going to your profile (click `Profile` in the banner at the top of the screen), then clicking `Account Details`.
Alternatively, you can manage your account by going to your profile (click `Profile` in the navigation bar at the top of the screen), then clicking `Account Details`.
## Enable Login With Google or Microsoft

4
docs/source/index.md
View File

@@ -6,10 +6,6 @@ It can be deployed by individuals or organisations, and supports login with user
This work was funded through the "Building REsearch Capacity for sustainable water and food security In drylands of sub-saharan Africa" (BRECcIA) project which is supported by UK Research and Innovation as part of the Global Challenges Research Fund, grant number NE/P021093/1.
:::{note}
This project is still under development until April 2023.
:::
## Contents
```{toctree}