Merge pull request #259 from Jeremy-Prior/main

Docs: Multiple Updates
kartoza · Jan 11, 2024 · 0089bdd · 0089bdd
2 parents 29b2fd1 + 8ce7aeb
commit 0089bdd
Show file tree

Hide file tree

Showing 55 changed files with 131 additions and 152 deletions.
diff --git a/docs/mkdocs-base.yml b/docs/mkdocs-base.yml
@@ -59,8 +59,6 @@ nav:
                         - Upload Metadata: user/guide/create-metadata.md
                         - Edit Metadata: user/guide/edit-metadata.md
                         - Report Issues: user/guide/opening-issues.md #Linked in a document
-                        - Disclaimer: about/disclaimer.md
-                        - License: about/license.md
                 - Manual: 
                         - user/manual/index.md
                         - Home Page: user/manual/home.md
@@ -122,11 +120,7 @@ nav:
                 - Documentation: 
                         - developer/documentation/index.md
                         - Setting up mkdocs: developer/documentation/make-docs.md
-                        - Writing: developer/documentation/writing.md
-                - API: # this might not be needed for this project
-                        - developer/api/index.md
-                        - Reference: developer/api/manual/index.md
-                        - Guide: developer/api/guide/index.md
+                        - Writing Documentation: developer/documentation/writing.md
                 - License: about/license.md
         - DevOps: 
                 - devops/index.md
@@ -136,3 +130,4 @@ nav:
                 - about/index.md
                 - License: about/license.md
                 - Code of Conduct: about/code-of-conduct.md
+                - Disclaimer: about/disclaimer.md
diff --git a/docs/src/about/disclaimer.md b/docs/src/about/disclaimer.md
@@ -1,4 +1,5 @@
 # Disclaimer
-<!-- To Be Populated -->
 
-Disclaimer about project.
+<div class="admonition warning">
+The software provided by this project is provided 'as is'. All information provided within the platform should be independently verified before using as the basis for action. The contributors and developers of this platform take no responsibility for any loss of revenue, life, physical harm or any other adverse outcome that may occur as a result of the use of this platform.
+</div>
diff --git a/docs/src/about/img/emc-1.png b/docs/src/about/img/emc-1.png
diff --git a/docs/src/about/running-instances.md b/docs/src/about/running-instances.md
@@ -1,2 +1,5 @@
 # Examples of Running Instances
-<!-- To Be Populated -->
+
+* The [Electronic Metadata Catalogue (EMC)](https://catalogue.sasdi.gov.za/) is another CKANext project that functions in a similar manner to the SAEOSS Portal.
+
+    ![EMC 1](./img/emc-1.png)
diff --git a/docs/src/administrator/manual/index.md b/docs/src/administrator/manual/index.md
@@ -11,7 +11,7 @@ The administrator manual aims to assist user in learning the fundamentals of usi
 ## Index
 
 - [**Dashboard**]()
-- [**Harvesting Settings**]()
+- [**Harvesting Settings**](./harvesting-settings.md)
 - [**Profile**]()
 - [**Metadata**]()
 - [**Map**]()

diff --git a/docs/src/developer/api/guide/img/naming-convention.README b/docs/src/developer/api/guide/img/naming-convention.README
diff --git a/docs/src/developer/api/guide/index.md b/docs/src/developer/api/guide/index.md
diff --git a/docs/src/developer/api/img/naming-convention.README b/docs/src/developer/api/img/naming-convention.README
diff --git a/docs/src/developer/api/index.md b/docs/src/developer/api/index.md
diff --git a/docs/src/developer/api/manual/img/naming-convention.README b/docs/src/developer/api/manual/img/naming-convention.README
diff --git a/docs/src/developer/api/manual/index.md b/docs/src/developer/api/manual/index.md
diff --git a/docs/src/developer/documentation/writing.md b/docs/src/developer/documentation/writing.md
@@ -40,10 +40,10 @@ src
 │   ├── guide
 │   └── manual
 └── user
-│   ├── api
     ├── guide
     ├── manual
-    └── quickstart
+    ├── quickstart
+    └── research
 ```
 
 ## File naming conventions
@@ -105,44 +105,41 @@ On the next screen, 1️⃣ give your pull request a meaningful title, 2️⃣ g
 Once your pull request is opened you need to wait for it to be merged before you can open a new one.
 
 ## Creating new files
-<!-- 
+
 ### Page metadata
+
 Whenever you create a new file, you should add the standard header to the top of the file:
 
 ```
 ---
-title: GeoRepo-OS Documentation 
-summary: GeoRepo is a UNICEF's geospatial web-based data storage and administrative boundary harmonization platform.
+title: SAEOSS Portal Documentation 
+summary: The SAEOSS-Portal is a system of software components functioning together as the National Central Earth Observation Geospatial Repository.
     - Tim Sutton
-    - Dimas Tri Ciputra
-    - Danang Tri Massandy
-date: 2023-08-03
-copyright: Copyright 2023, Unicef
-contact: [email protected]
+    - Juanique Voogt
+date: 2024-01-10
+copyright: Copyright 2024, SANSA
+contact: 
 license: This program is free software; you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
 #context_id: 1234
 ---
 ```
 
 The summary can be updated to include your name for documents you contribute to.
 
-The context_id is used to create a unique permalink to this document, and is optional. See further down in this document for more details. -->
+The context_id is used to create a unique permalink to this document, and is optional. See further down in this document for more details.
 
 ### Navigation
 
 All pages need to be added to the 'Nav' section of the `mkdocs-base.yml` file. This will ensure that it is available in the menus and that mkdocs renders without errors. For example, if you wish to add a new page to the User Guide area, in Nav you would add a line like this:
 
-
 `- "Navigating the map": users/guide/map-navigation.md`
 
-Sometimes you may not wish to have the new page displayed in the menu system (this can be useful when, for example, it is accessed via a link in another page. In these cases, leave the menu entry part blank e.g.
+Sometimes you may not wish to have the new page displayed in the menu system (this can be useful when, for example, it is accessed via a link in another page). In these cases, leave the menu entry part blank e.g.
 
 `- "": users/guide/map-navigation.md`
 
-
 Mkdocs will still generate the page but it will not be added to the menu.
 
-
 ## Technical notes
 
 ### Working locally
@@ -156,8 +153,8 @@ If you want to work with the documentation locally (i.e. directly on your PC), y
 4. Create the virtual env in the docs folder (`python -m venv env`)
 5. Activate the venv (`source env/bin/activate`)
 5. Install the python modules listed in docs/requirements.txt (`pip install -r requirements.txt`)
-6. If you are on Linux or macOS, open the docs directory in a shell and run ``build-docs-html.sh``
-7. In the docs directory, run ``mkdocs serve``
+6. If you are on Linux or macOS, open the docs directory in a shell and run `build-docs-html.sh`
+7. In the docs directory, run `mkdocs serve`
 8. Open your web browser at https://localhost:8000 to view the rendered docs.
 
 Note that ``mkdocs serve`` will dynamically re-render the docs any time you make a change. The process above is illustrated in the diagram below:
@@ -184,7 +181,6 @@ Every page should have a help link on it that leads to the appropriate manual pa
 
 Whenever the user visits the page using the UUID URL, they will be redirected to the correct page e.g. ``https://siteurl/login/``. This system protects us from file renaming and reorganising on the site, and ensures that the help link will always remain valid.
 
-
 ### Generating PDFS
 
 To generate PDFS, `cd` into `SAEOSS-Portal/docs` and then run the `build-docs-pdf` in a local terminal

diff --git a/docs/src/developer/index.md b/docs/src/developer/index.md
@@ -5,5 +5,3 @@ This is the homepage for all developer related documentation.
 
 * The [developer guide](guide/index.md), which describes common workflows for developers in a tutorial format. This includes instructions on how to set up your developer environment, check out the code, run it locally etc.
 * The [developer manual](manual/index.md), which describes each python module and its classes, functions etc. This section is autogenerated.
-* The [api guide](api/guide/index.md), which describes common workflows for using the restful API.
-* The [api manual](api/manual/index.md), which describes each API endpoint and its parameters, return values etc. This section is autogenerated.
diff --git a/docs/src/developer/manual/index.md b/docs/src/developer/manual/index.md
@@ -14,6 +14,22 @@ Below is linked reference manuals for coding languages and frameworks used in SA
 [Ckan API Reference](https://docs.ckan.org/en/2.10/api/index.html)
 
 ## Index
-<!-- List of other pages needs to be added here in the order of the nav -->
 
-* **[Coding Conventions:]()** <!-- Add explanation -->
+* **[Coding Conventions](./coding-conventions.md)**
+* **[Project SCrum Board](./project-scrum-board.md)**
+* **[Assets](./assets.md)**
+* **[Blueprints](./blueprints.md)**
+* **[Command Line Interface](./cli.md)**
+* **[Constants](./constants.md)**
+* **[Email Notifications](./email-notification.md)**
+* **[Get Releases](./get-releases.md)**
+* **[Helpers](./helpers.md)**
+* **[Jobs](./jobs.md)**
+* **[Logic](./logic.md)**
+* **[Model](./model.md)**
+* **[Plugins](./plugins.md)**
+* **[Public](./plugins.md)**
+* **[Scheming](./scheming.md)**
+* **[Web Server Gateway Interface](./wsgi.md)**
+* **[Test Local Instance](./test_local.md)**
+* **[CSW](./csw.md)**
diff --git a/docs/src/user/guide/img/chatbox-1.png b/docs/src/user/guide/img/chatbox-1.png
diff --git a/docs/src/user/guide/img/crisp-1.png b/docs/src/user/guide/img/crisp-1.png
diff --git a/docs/src/user/guide/img/crisp-2.png b/docs/src/user/guide/img/crisp-2.png
diff --git a/docs/src/user/guide/img/login-1.png b/docs/src/user/guide/img/login-1.png
diff --git a/docs/src/user/guide/img/login-2.png b/docs/src/user/guide/img/login-2.png
diff --git a/docs/src/user/guide/img/login-3.png b/docs/src/user/guide/img/login-3.png
diff --git a/docs/src/user/guide/img/non-owned-profile-1.png b/docs/src/user/guide/img/non-owned-profile-1.png
diff --git a/docs/src/user/guide/img/non-owned-profile-2.png b/docs/src/user/guide/img/non-owned-profile-2.png
diff --git a/docs/src/user/guide/img/non-owned-profile-3.png b/docs/src/user/guide/img/non-owned-profile-3.png
diff --git a/docs/src/user/guide/img/non-owned-profile-4.png b/docs/src/user/guide/img/non-owned-profile-4.png
diff --git a/docs/src/user/guide/img/non-owned-profile-5.png b/docs/src/user/guide/img/non-owned-profile-5.png
diff --git a/docs/src/user/guide/img/non-owned-profile-6.png b/docs/src/user/guide/img/non-owned-profile-6.png
diff --git a/docs/src/user/guide/img/organisations-1.png b/docs/src/user/guide/img/organisations-1.png
diff --git a/docs/src/user/guide/img/organisations-2.png b/docs/src/user/guide/img/organisations-2.png
diff --git a/docs/src/user/guide/img/organisations-3.png b/docs/src/user/guide/img/organisations-3.png
diff --git a/docs/src/user/guide/img/registration-1.png b/docs/src/user/guide/img/registration-1.png
diff --git a/docs/src/user/guide/index.md b/docs/src/user/guide/index.md
@@ -6,12 +6,12 @@ The guide section of the documentation provides short narrative/workflow based t
 ## Index
 
 * **[Registering:](./registering.md)** This page will show you how to register on the platform.
-* **[Logging In:](./logging-in.md)**
-* **[Profile Settings:](./profile-management.md)**
-* **[Organisation Management:](./organisation-management.md)**
-* **[Search Metadata:](./search-metadata.md)**
-* **[Upload Metadata:](./create-metadata.md)**
-* **[Edit Metadata:](./edit-metadata.md)**
+* **[Logging In:](./logging-in.md)** This page will show you how to log in to the platform.
+* **[Profile Settings:](./profile-management.md)** This page will show you how to manage your profile on the platform.
+* **[Organisation Management:](./organisation-management.md)** This page will show you how to manage organisations on the platform.
+* **[Search Metadata:](./search-metadata.md)** This page will show you how to search for metadata on the platform.
+* **[Upload Metadata:](./create-metadata.md)** This page will show you how to upload metadata to the platform.
+* **[Edit Metadata:](./edit-metadata.md)** This page will show you how to edit metadata on the platform.
 
 ## Error reporting
 

diff --git a/docs/src/user/guide/logging-in.md b/docs/src/user/guide/logging-in.md
@@ -1,2 +1,15 @@
 # Logging In
-<!-- To be populated -->
+
+**Applicable roles:** All registered users.
+
+To log in to the site, click on the `LOG IN` button.
+
+![Login 1](./img/login-1.png)
+
+On the Login Page, enter your username and password in the relevant fields. Then click on the `Login` button.
+
+![Login 2](./img/login-2.png)
+
+After that you will be redirected to your news feed.
+
+![Login 3](./img/login-3.png)
diff --git a/docs/src/user/guide/opening-issues.md b/docs/src/user/guide/opening-issues.md
@@ -1,6 +1,6 @@
 # GitHub Issues/Tickets
 
-![GitHub Logo](../img/GitHub-Mark.png)
+![GitHub Logo](../img/GitHub-Mark.png){: style="height:150px"}
 
 This GitHub project repository serves as a project planning and progress tracking platform for the development teams and clients. This repository is public and for anyone to view. The repository can be accessed [here](https://github.com/kartoza/SAEOSS-Portal).
 

diff --git a/docs/src/user/guide/organisation-management.md b/docs/src/user/guide/organisation-management.md
@@ -2,17 +2,31 @@
 
 **Applicable roles:** System administrator and organisational publisher
 
+## Navigating to Organisations
+
+From any page on the site, click on `ORGANISATIONS` in the navigation bar at the top of the page.
+
+![Organisations 1](./img/organisations-1.png)
+
+This will redirect you to the Organisations Page. On this page, click on the block of organisation you would like to view.
+
+![Organisations 2](./img/organisations-2.png)
+
+This will redirect to that organisation's home page.
+
+![Organisations 3](./img/organisations-3.png)
+
 ## Managing organisation members
 
-A s a system administrator or an organisational publisher, you have the ability to manage profiles belonging to certain organisations. First you need to navigate to the organisation and then click `Manage`
+As a system administrator or an organisational publisher, you have the ability to manage organisation members. First you need to navigate to the organisation and then click `Manage`.
 
 ![manage organisation](img/manage-members-1.png)
 
 Then click on the `Members` tab.
 
 ![manage organisation](img/manage-members-2.png)
 
-You can:
+From here you can:
 
 1. Add new members to the organisation.
 2. Edit the member's role.
@@ -21,3 +35,27 @@ You can:
 ![manage members](img/manage-members-3.png)
 
 ## Managing non-owned profile
+
+As a system administrator, you have the ability to manage a non-owned user profile. To do so, navigate to an organisation's home page and then click on `Manage`.
+
+![non-owned profile 1](img/non-owned-profile-1.png)
+
+Then click on the `Members` tab.
+
+![non-owned profile 2](img/non-owned-profile-2.png)
+
+Then click on a user's name that you would like to manage.
+
+![non-owned profile 3](img/non-owned-profile-3.png)
+
+You will be redirected to the user's profile page. On this page you should click on the `Manage` button.
+
+![non-owned profile 4](img/non-owned-profile-4.png)
+
+You will be redirected to the `Change details` page, here you can manage the user's profile details. Once you have made your changes to the user's profile, scroll down and enter your `Sysadmin Password` (i.e. the password you use to log in to the administrator account), and then click on the `Update Profile` button.
+
+![non-owned profile 5](img/non-owned-profile-5.png)
+
+If you would like to remove the user, you can scroll down and enter your `Sysadmin Password` (i.e. the password you use to log in to the administrator account), and then click on the `Delete` button.
+
+![non-owned profile 6](img/non-owned-profile-6.png)
diff --git a/docs/src/user/guide/registering.md b/docs/src/user/guide/registering.md
@@ -1,15 +1,17 @@
 # Create an Account
 
-In order to register on the site, navigate to `SIGN UP` on the top right hand corner of the page.
+In order to register on the site, click on the `SIGN UP` button on the top right hand corner of the page.
 
 ![register](img/registration-1.png)
 
-Then fill in the form below.
+Then fill in the registration form (example below).
 
 ![register](img/registration-2.png)
 
 > Please note that your **username needs to be lowercase** and you are required to have a **password with a minimum of 8 characters**.
 
-Once you have successfully registered, you can request to be a part of an organisation using the CRISP help-desk.
+Once you have successfully registered, you can request to be added to an organisation using the CRISP help-desk.
 
-![chat-box](img/chatbox-1.png)
+![CRISP 1](img/crisp-1.png)
+
+![CRISP 2](img/crisp-2.png)
diff --git a/docs/src/user/index.md b/docs/src/user/index.md
@@ -7,14 +7,4 @@ The user content is divided into three sections:
 * The [quickstart tutorial](quickstart/index.md), which aims to get you familiar with the basics of the platform in around 5 minutes.
 * The [user guide](guide/index.md), which describes common workflows in a tutorial format.
 * The [user manual](manual/index.md), which describes each page of the user interface and what the various options on that page do.
-* The [metadata standard](./research/index.md)
-
-<!-- Luna create these .md files and add the links here -->
-Additional roles:
-
-* Publisher
-* Editor
-* Member/Viewer
-
-<!-- Manual: briefly explain role is it purpose -->
-<!-- guide: workflows for other roles (step by step)-->
+* The [metadata standard](./research/index.md), which explains the all of the metadata elements utilised by the portal.
diff --git a/docs/src/user/manual/about.md b/docs/src/user/manual/about.md
@@ -1,11 +1,7 @@
-###### Previous Page: [Map](./map.md)
-
 # About
 
 User can navigate to the page by select `About` on the tab. Users will be able to read on the vision of the portal and the reason to contribute.
 
 ![about](img/about-page-1.png)
 
 ![vision](img/about-page-2.png)
-
-###### Next Page: [Help](./help.md)
diff --git a/docs/src/user/manual/dashboard.md b/docs/src/user/manual/dashboard.md
@@ -1,5 +1,3 @@
-###### The previous chapter to this is the [Home Page](./home.md)
-
 # Dashboard Page
 
 Once a user has logged in, the dashboard page will be displayed. This is a central notification hub for communications from the SAEOSS-Portal platform.
@@ -52,7 +50,3 @@ The news feed provides an overview of all recent activities of groups, organizat
 By selecting the `Profile Settings` button, you can adjust your profile settings like your username, bio, password, change profile picture, and generate API Keys. This page is explained in detail here: [Profile Settings](./profile-settings.md)
 
 ![Profile_settings](./img/profile_settings_button.png)
-
-###### Next Chapter
-
-In the next chapter, look at [Profile Page](./profile-page.md)
diff --git a/docs/src/user/manual/help.md b/docs/src/user/manual/help.md
@@ -1,5 +1,3 @@
-###### Previous Page:  [About](./about.md)
-
 # Help Page
 
 The help page is the documentation site. Here you can find out all there is to know and how things work on the SAEOSS-Platform. The documentation is quite informative and includes documentation for all workflows on the platform, however, if you find it lacking, please consider contributing to it or creating a GitHub issue so we may improve it.
@@ -14,4 +12,3 @@ In all cases, your support and contributions are not only welcome but greatly ap
 
 If you have made it thus far into the documentation, you may want to review the [user guide](../guide/index.md), which provides workflow-based tutorials in the same page-by-page manner.
 
-###### Next Page: [User Roles](user-roles.md)