Skip to content

Commit

Permalink
Update documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
meomancer committed Aug 11, 2023
1 parent 8401e54 commit 0e36c56
Show file tree
Hide file tree
Showing 98 changed files with 776 additions and 786 deletions.
5 changes: 3 additions & 2 deletions .github/workflows/BuildMKDocsAndPublishToGithubPages.yml
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
# __date__ = '13/06/2023'
# __copyright__ = ('Copyright 2023, Unicef')

name: 📖 Build MKDocs And Publish To Github Pages.yml
name: 📖 Documentation
on:
push:
branches:
Expand All @@ -21,6 +21,7 @@ on:
paths:
- ".github/workflows/BuildMKDocsAndPublishToGithubPages.yml"
- "docs/**.md"
- "docs/**.py"
- "docs/assets/**"
# Allow manually running in the actions tab
workflow_dispatch:
Expand All @@ -46,4 +47,4 @@ jobs:
# The token is automatically generated by the GH Action
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
CONFIG_FILE: docs/mkdocs.yml
REQUIREMENTS: docs/requirements.txt
REQUIREMENTS: docs/requirements.txt
51 changes: 0 additions & 51 deletions .github/workflows/CompileMKDocsToPDF.yml

This file was deleted.

4 changes: 4 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -34,3 +34,7 @@ django_project/.env

#direnv for docs building
docs/.direnv
# Autogenerated api docs
docs/src/developer/manual/*.md

*.swp
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ A **project** (dashboard) is the most important feature of GeoSight. Projects co

[![Tests](https://github.com/unicef-drp/GeoSight-OS/workflows/Tests/badge.svg)](https://github.com/unicef-drp/GeoSight-OS/actions/workflows/tests.yaml)
[![Flake8](https://github.com/unicef-drp/GeoSight-OS/workflows/Flake8/badge.svg)](https://github.com/unicef-drp/GeoSight-OS/actions/workflows/flake8.yml)
[![Documentation](https://github.com/unicef-drp/GeoSight-OS/workflows/Documentation/badge.svg)](https://unicef-drp.github.io/GeoSight/)
[![Documentation](https://github.com/unicef-drp/GeoSight-OS/actions/workflows/BuildMKDocsAndPublishToGithubPages.yml/badge.svg)](https://unicef-drp.github.io/GeoSight-OS/)

### Production

Expand Down
5 changes: 5 additions & 0 deletions docs/create-uuid.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
#! /usr/bin/env python

import shortuuid
uuid = shortuuid.uuid()
print (uuid)
1 change: 1 addition & 0 deletions docs/default.nix
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ in pkgs.mkShell rec {
libxslt
libzip
zlib
gnused
httplz # for serving up the static site while testing
];

Expand Down
79 changes: 24 additions & 55 deletions docs/mkdocs-base.yml
Original file line number Diff line number Diff line change
Expand Up @@ -35,16 +35,13 @@ markdown_extensions:
emoji_generator: !!python/name:materialx.emoji.to_svg
emoji_index: !!python/name:materialx.emoji.twemoji


nav:
- Home:
- index.md
- About: about/index.md
- Contributing:
- about/contributing.md
- Commit Messages: about/documentation/commit-message-convention.md
- Pull Request Template: about/documentation/pull-request-template.md
- Contributing: about/contributing.md
- Code of Conduct: about/code-of-conduct.md
- Running Instances: about/running-instances.md
- Users:
- Overview:
- user/index.md
Expand All @@ -53,7 +50,6 @@ nav:
- Guide:
- user/guide/index.md
- Disclaimer: about/disclaimer.md
- Credits: about/credits.md
- License: about/license.md
- Manual:
- user/manual/index.md
Expand All @@ -68,57 +64,30 @@ nav:
- Developers:
- Overview:
- developer/index.md
- Guide:
- developer/guide/index.md
- Project Prerequisites: developer/guide/project-prerequisites.md
- IDE to Use: developer/guide/ide-to-use.md
- Checking Out The Code: developer/guide/checking-out-the-code.md
- Building/Compiling Code: developer/guide/building-compiling-code.md
- Running Instances: developer/guide/running-instances.md
- Setup:
- developer/guide/setup/index.md
- Installation:
- Preparation: developer/guide/setup/installation/preparation.md
- Project setup: developer/guide/setup/installation/project-setup.md
- Development setup:
- Overview: developer/guide/setup/installation/development-setup/index.md
- Using pycharm: developer/guide/setup/installation/development-setup/pycharm.md
- Road Map: developer/guide/setup/roadmap.md
- Configuration:
- Geography: developer/guide/setup/configuration/geography.md
- Indicator: developer/guide/setup/configuration/indicator.md
- Instances: developer/guide/setup/configuration/instances.md
- Layer: developer/guide/setup/configuration/layer.md
- Navigation Link: developer/guide/setup/configuration/navigation-link.md
- Preferences: developer/guide/setup/configuration/preferences.md
- Program Intervention: developer/guide/setup/configuration/program-intervention.md
- Scenario: developer/guide/setup/configuration/scenario.md
- User: developer/guide/setup/configuration/user.md
- Building/Compiling Code: developer/guide/building-compiling-code.md
- Checking Out The Code: developer/guide/checking-out-the-code.md
- Developer Workflows: developer/guide/developer-workflows.md
- IDE to Use: developer/guide/ide-to-use.md
- Running Instances: developer/guide/running-instances.md

- Architecture:
- developer/architecture/index.md
- Documentation:
- developer/documentation/index.md
- Manual:
- developer/manual/index.md
- License: about/license.md
- API:
- developer/api/index.md
- API Manual: developer/api/api.md
- API Settings: developer/api/api_settings.md
- Design:
- developer/design/index.md
- DevOps:
- Overview:
- devops/index.md
- Guide: developer/api/guide/index.md
- Reference: developer/api/manual/index.md
- Guide:
- devops/guide/index.md
- Tutorial 1: devops/guide/tutorial1.md
- Overview: developer/guide/index.md
- Architecture: developer/guide/architecture.md
- Design: developer/guide/design.md
- Prerequisites: developer/guide/project-prerequisites.md
- IDE Setup: developer/guide/ide-setup.md
- Cloning: developer/guide/checking-out-the-code.md
- Configuration: developer/guide/configuration.md
- Building: developer/guide/building.md
- Workflows: developer/guide/developer-workflows.md
- Road Map: developer/guide/roadmap.md
# Pages to render but exclude from Nav
- "": developer/guide/templates/commit-message-convention.md
- "": developer/guide/templates/pull-request-template.md
- Documentation: developer/documentation/index.md
- Manual:
- devops/manual/index.md
- developer/manual/index.md
- License: about/license.md
- DevOps:
- devops/index.md
- Guide: devops/guide/index.md
- Manual: devops/manual/index.md

31 changes: 30 additions & 1 deletion docs/mkdocs-html.yml
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,32 @@ extra_javascript:
# Needed for the hooks below to work
plugins:
- search
- git-revision-date-localized
- mkdocs-video
- mkdocstrings:
handlers:
python:
paths: [../django_project]
import:
- https://docs.python.org/3/objects.inv
- https://mkdocstrings.github.io/autorefs/objects.inv
options:
# Lots of other nice options can be found at
# https://mkdocstrings.github.io/python/usage/
docstring_style: sphinx
heading_level: 2
show_bases: true
show_signature: true
separate_signature: true
show_signature_annotations: true
show_source: true
show_root_heading: true
show_root_full_path: true
show_root_members_full_path: true
merge_init_into_class: true
docstring_options:
ignore_init_summary: false

- redirects:
redirect_maps:
#see https://github.com/mkdocs/mkdocs-redirects/tree/master#using
Expand All @@ -82,6 +108,7 @@ plugins:
- user/index.md
- administrator/index.md
- developer/index.md
- developer/manual/*.md
- devops/index.md
restart_increment_after:
- second_section.md
Expand All @@ -90,4 +117,6 @@ plugins:
# see also hook.py and https://github.com/squidfunk/mkdocs-material/discussions/3758#discussioncomment-4397373
# Note that although the above link implies you can use UUIDs, you have to use numeric IDS not UUIDS
hooks:
- ./hook.py
- ./uuid_redirects_hook.py
- ./python_manual_hook.py

43 changes: 43 additions & 0 deletions docs/python_manual_hook.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
import logging
import mkdocs.plugins
import os

log = logging.getLogger('mkdocs')

@mkdocs.plugins.event_priority(-50)


def on_startup(command, dirty):


template = """
---
title: Automatically Generated Python Documentation
summary: DO NOT EDIT THIS FILE MANUALLY : It is created during the mkdocs build process
date: 2023-08-03
---
# Python Reference Manual
"""
ignore_list = [
"__init__",
"migrations",
"tests"]

for root, dirs, files in os.walk("../django_project"):
for file in files:
file = os.path.join(root, file)
if file.endswith(".py"):
ignored = False;
for item in ignore_list:
if item in file:
ignored = True;
#print (item, file, ignored)
if not ignored:
file = file.replace("../django_project/", "::: ")
file = file.replace("/", ".")
file = file.replace(".py", "")
template = template + file + "\n"
file = open("docs/src/developer/manual/index.md","wt")
file.write(template)
file.close()
5 changes: 5 additions & 0 deletions docs/requirements.txt
Original file line number Diff line number Diff line change
Expand Up @@ -7,3 +7,8 @@ mkdocstrings-python
mkdocs-video
mkdocs-redirects
mkdocs-enumerate-headings-plugin
mkdocs-git-revision-date-localized-plugin
# needed for the create-uuid.py helper script
shortuuid
# Needed for mkdocstrings python documentation generator
black
29 changes: 14 additions & 15 deletions docs/src/about/contributing.md
Original file line number Diff line number Diff line change
@@ -1,16 +1,15 @@
[//]: # "GeoSight is UNICEF's geospatial web-based business intelligence platform."
[//]: #
[//]: # "Contact : [email protected]"
[//]: #
[//]: # ".. note:: 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."
[//]: #
[//]: # "__author__ = '[email protected]'"
[//]: # "__date__ = '13/06/2023'"
[//]: # "__copyright__ = ('Copyright 2023, Unicef')"
[//]: # "__copyright__ = ('Copyright 2023, Unicef')"
---
title: GeoSight-OS Documentation Home
summary: GeoSight is UNICEF's geospatial web-based business intelligence platform.
- Tim Sutton
- Irwan Fathurrahman
date: 2023-08-03
some_url: https://github.com/unicef-drp/GeoSight-OS
copyright: Copyright 2023, Unicef
contact: [email protected]
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
---

# Contributing to GeoSight

Expand Down Expand Up @@ -107,7 +106,7 @@ If you are adding new commands or features, they must include tests.
If you are changing functionality, update the tests if you need to.

#### Commit
Follow our [commit message conventions](./documentation/commit-message-convention.md).
Follow our [commit message conventions](../developer/guide/templates/commit-message-convention.md).

### Yes! Pull request

Expand All @@ -126,7 +125,7 @@ Follow other PR title format on below.
#### Description

If it has related issues, add links to the issues(like `#123`) in the description.
Fill in the [Pull Request Template](./documentation/pull-request-template.md) by check your case.
Fill in the [Pull Request Template](../developer/guide/templates/pull-request-template.md) by check your case.

## Code of Conduct

Expand Down
16 changes: 0 additions & 16 deletions docs/src/about/credits.md

This file was deleted.

Loading

0 comments on commit 0e36c56

Please sign in to comment.