fixes broken links

docs/_hooks/hooks.py

@@ -1,70 +1,21 @@
+# mypy: disable-error-code="typeddict-unknown-key"
+from datetime import datetime
+
 from mkdocs.config.defaults import MkDocsConfig
-from mkdocs.structure.files import File, Files
+from mkdocs.structure.files import Files
+from mkdocs.structure.nav import Navigation
 from mkdocs.structure.pages import Page
+from mkdocs.utils.templates import TemplateContext
 
-# https://www.mkdocs.org/dev-guide/plugins/#events
-
-def aaa():
-    from pathlib import Path
-
-    import mkdocs_gen_files
-    from mkdocs.structure.files import File, Files
-    from mkdocs.structure.pages import Page
-
-    PAT = '<a id="{id}" href="../{url}">{title}</a> | {description}'
-    PAT = '{description}'
-
-    config = mkdocs_gen_files.config
-
-    docs_dir = config["docs_dir"]
-    glossary_dir = "glossary"
-    terms_dir = Path(docs_dir) / f"{glossary_dir}/terms"
-    index = "glossary/index.md"
-
-    TABLE = []
-    TABLE.append("# Glossary")
-    TABLE.append("")
-    TABLE.append("Term | Definition")
-    TABLE.append("-----|-----------")
-
-    TERMS = {}
-
-    for filename in terms_dir.iterdir():
-        if filename.is_dir():
-            continue
-        if filename.stem.startswith("."):
-            continue
-        fl = File(str(filename.relative_to(docs_dir)), config.docs_dir, config.site_dir, config.use_directory_urls)
-        pg = Page(None, fl, config)
-        pg.read_source(config)
-        pg.render(config, Files([]))
-        if pg.meta.get("template", "") != "term.html":
-            raise Exception(f"File {filename} does not have a template meta descriptor")
-        for t in pg.toc.items:
-            LINE = PAT.format(id=filename.stem, title=t.title, url=f"{pg.url}{t.url}",
-                              description=pg.meta.get("description", ""))
-            TERMS[t.title] = LINE
-
-    for term in sorted(TERMS.keys()):
-        TABLE.append(TERMS[term])
 
-    with mkdocs_gen_files.open(index, "w") as f:
-        f.writelines("\n".join(TABLE))
+def on_pre_build(config: MkDocsConfig) -> None:
+    pass
 
-    with mkdocs_gen_files.open(index, "w") as f:
 
-        for term in sorted(TERMS.keys()):
-            f.write(f"\nglossary:{term}")
-            f.write(f"\n:{TERMS[term]}")
-            f.write(f"\n")
-            f.write(f"\n")
+def on_page_markdown(markdown: str, page: Page, config: MkDocsConfig, files: Files) -> None:
+    pass
 
-    mkdocs_gen_files.set_edit_path(index, "build_glossary.py")
 
-#
-# def on_pre_build(config: MkDocsConfig):
-#     aaa()
-#
-#
-# def on_page_markdown(markdown: str, page: Page, config: MkDocsConfig, files: Files):
-#     pass
+def on_page_context(context: TemplateContext, nav: Navigation, page: Page, config: MkDocsConfig) -> None:
+    context["build_date"] = datetime.now().strftime("%a, %d, %b %Y - %H:%M")
+    context["config"] = config

docs/components/.pages

@@ -1,9 +1,9 @@
 nav:
   - index.md
 #  - hope.md
-#  - hde.md
-#  - Payment Gateway: pg
-#  - aurora.md
+  - hde.md
+  - Payment Gateway: pg
+  - Aurora: aurora
 #  - kobo.md
 #  - reporting/index.md
 #  - workspace.md

docs/components/aurora.md

@@ -5,3 +5,5 @@ Aurora is an open source project to collect and register data. It is focused mai
 
 
 <https://github.com/unicef/aurora>
+
+## Install

docs/components/aurora/index.md

@@ -0,0 +1,19 @@
+# Aurora
+
+Aurora is the official online registration tool for HOPE. Developed in 2022 for the Ukraine emergency, it quickly became the de-facto standard for online registration in almost all the countries served online by UNICEF. 
+
+The strengths of Aurora are:
+
+- Incredibly fast (reached 15.000 registrations per second)
+- Security (supports both 
+- Powerful form builder
+- Support complex validation logic
+- Database level user defined per form unique keys
+- Multilanguage
+- Open and protected online registrations
+- Straightforward architecture 
+- Custom form page (partner logos, header, footer, colors...)
+
+
+
+<https://github.com/unicef/hope-aurora>

docs/components/aurora/setup.md

@@ -0,0 +1,85 @@
+# Development Setup
+
+
+Prerequisites:
+
+- This project uses [pdm](https://github.com/pdm-project/pdm#installation) as package manager
+- A Postgres DB v14+
+- A Redis server
+
+!!! note
+
+    PDM will create a virtualenv in <project_root>/.venv, and install dependencies into it.
+    If you wand to change this behaviour please read the [PDM Documentation](https://pdm-project.org/en/latest/usage/venv/)
+
+
+## Create virtualenvironment
+
+2. Checkout code
+
+    ```
+    git clone https://github.com/unicef/hope-aurora
+    git config branch.autosetuprebase always
+
+    ```
+   
+1. In the shell:
+    
+    ```
+    pdm venv create
+    pdm use
+    pdm venv activate
+    ```
+   
+1. Check your virtualenv is properly created
+
+    ```pdm info```
+
+
+1. Install the package
+
+    ```
+     pdm install
+     pdm run pre-commit install
+    ```
+
+
+1. Add `export PYTHONPATH="$PYTHONPATH:./src"`
+
+
+1. Check your environment: 
+
+    `./manage.py env --check` and configure the missing variables.
+
+    !!! hint
+    
+        You can generate a list for your development environment with the command 
+    
+            ./manage.py env --develop --config --pattern='export {key}={value}'   
+
+1. Run upgrade command to properly initialize the application: 
+
+    `./manage.py upgrade --admin-email ${ADMIN_EMAIL} --admin-password ${ADMIN_PASSWORD}`
+    
+    !!! note
+        
+          Django migrations and collectstatic commands are automatically included in this step
+
+
+## Configure environment for .direnv
+
+If you want to use [direnv](https://direnv.net/) and automatic loading of environment variables from a _.envrc_ file:
+    
+```
+./manage.py env --develop --config --pattern='{key}={value}' > .envrc
+
+echo 'export PYTHONPATH="$PYTHONPATH:./src"' >> .envrc
+echo 'eval $(pdm venv activate)' >> .envrc
+echo "unset PS1" >> .envrc
+```
+
+!!! warning
+
+    The first time after you have created or modified the _.envrc_ file you will have to authorize it using:
+
+        direnv allow

docs/components/index.md

@@ -9,16 +9,26 @@ and extend the platform according to their unique needs.
 It’s built to be scalable, adaptable, and interoperable, making it simple to integrate with other 
 systems and platforms, ensuring smooth workflows and easy expansion as your needs grow.
 
-- Aurora <https://github.com/unicef/aurora>
-- Kobo <https://www.kobotoolbox.org/> 
-- DeduplicationEngine <https://github.com/unicef/hope-dedup-engine>
-- Country Report <https://github.com/unicef/hope-country-report>
-- Payment Gateway <https://github.com/unicef/hope-payment-gateway>
-- Country Workspace <https://github.com/unicef/hope-country-workspace> _(not yet released)_
-- User Management Module <https://github.com/unicef/hope-user-management> _(not yet released)_
+[//]: # ()
+[//]: # (- Aurora <https://github.com/unicef/aurora>)
 
-## Hope supporting libraries
+[//]: # (- Kobo <https://www.kobotoolbox.org/> )
 
-These are some of the libraries developed to support HOPE that are released under the OpenSource License
+[//]: # (- DeduplicationEngine <https://github.com/unicef/hope-dedup-engine>)
 
-- Flex Fields <https://github.com/unicef/hope-flex-fields>
+[//]: # (- Country Report <https://github.com/unicef/hope-country-report>)
+
+[//]: # (- Payment Gateway <https://github.com/unicef/hope-payment-gateway>)
+
+[//]: # (- Country Workspace <https://github.com/unicef/hope-country-workspace> _&#40;not yet released&#41;_)
+
+[//]: # (- User Management Module <https://github.com/unicef/hope-user-management> _&#40;not yet released&#41;_)
+
+[//]: # ()
+[//]: # (## Hope supporting libraries)
+
+[//]: # ()
+[//]: # (These are some of the libraries developed to support HOPE that are released under the OpenSource License)
+
+[//]: # ()
+[//]: # (- Flex Fields <https://github.com/unicef/hope-flex-fields>)

docs/guide-adm/docker.md

@@ -7,5 +7,5 @@ tags:
 # Run
 
 ```yaml
---8<-- "https://raw.githubusercontent.com/unicef/hct-mis/develop/compose.yml"
+--8<-- "https://raw.githubusercontent.com/unicef/hope/refs/heads/develop/development_tools/compose.yml"
 ```

docs/guide-dev/stack.md

@@ -16,5 +16,5 @@ Here a brief list of the relevant technologies
 ## pyproject.toml
 
 ``` ini
---8<-- "https://raw.githubusercontent.com/unicef/hope/develop/backend/pyproject.toml"
+--8<-- "https://raw.githubusercontent.com/unicef/hope/refs/heads/develop/src/pyproject.toml"
 ```

mkdocs.yml

@@ -26,7 +26,7 @@ markdown_extensions:
   - admonition
   - attr_list
 #  - def_list
-#  - md_in_html
+  - md_in_html
 #  - mkdocs-click
   - pymdownx.superfences:
       custom_fences:
@@ -102,8 +102,8 @@ theme:
 #    - navigation.sections
 #    - toc.integrate
     - navigation.instant
-#    - navigation.instant.prefetch
-#    - navigation.instant.progress
+    - navigation.instant.prefetch
+    - navigation.instant.progress
 
 plugins:
 #  - alias
@@ -126,17 +126,19 @@ plugins:
       list_references: true
       tooltip: heading
 #  - ezlinks
+  - gitsnippet
   - link-marker
-#  - mkdocstrings
-#  - include-markdown:
-#      encoding: ascii
-#      preserve_includer_indent: false
-#      dedent: false
-#      trailing_newlines: true
-#      comments: false
-#      rewrite_relative_urls: true
-#      heading_offset: 0
-#      recursive: true
+  - macros
+  #  - mkdocstrings
+  - include-markdown:
+      encoding: ascii
+      preserve_includer_indent: false
+      dedent: false
+      trailing_newlines: true
+      comments: false
+      rewrite_relative_urls: true
+      heading_offset: 0
+      recursive: true
   - privacy
   - search
   - social:

pyproject.toml

@@ -29,6 +29,7 @@ dependencies = [
     "mkdocs-pdf-export-plugin>=0.5.10",
     "mike>=2.1.3",
     "mkdocs-gitsnippet-plugin>=1.2.0",
+    "mkdocs-macros-plugin>=1.2.0",
 ]
 requires-python = "==3.12.*"
 readme = "README.md"