- Generate mkdocs.yml from mkdocs_template.yml

- Add doc about how to edit the docs

.gitignore

@@ -58,3 +58,6 @@ src/ext/curl/builds/
 src/ext/curl/winbuild/*.inc
 src/ext/curl/winbuild/*.idb
 src/ext/zlib/build/
+
+doc/mkdocs/docs/api
+doc/mkdocs/mkdocs.yml

doc/mkdocs/docs/documentation.md

@@ -0,0 +1,55 @@
+# Editing the Orca Documentation
+
+The documentation of Orca is published at [https://docs.orca-app.dev/](https://docs.orca-app.dev/).
+
+This document explains how this website is built and deployed, and how to edit it.
+
+## Overview
+
+The documentation website is built with [mkdocs](http://mkdocs.org/) from the markdown files found in `doc/mkdocs`. 
+
+Some docs like the index and quickstart guide are written manually, while the API reference is generated by a script.
+
+The `gen_doc.py` python script loads the API description found in `src/api.json`, cross-checks the type information with the C header files, and outputs the API reference markdown files. It also generates the yaml file necessary for `mkdocs` to build the navigation bar of the website.
+
+The website is build in CI and deployed through github pages when changes are pushed to the `main` branch.
+
+## Editing the Site Locally
+
+### Requirements
+
+You need a recent version of `python` (3.10 or newer) and `pip`.
+
+Install `mkdocs`:
+
+```
+pip install mkdocs
+```
+
+Install the `libclang` module, which is used to parse the C header files:
+
+```
+pip install libclang
+```
+
+### Building and Serving Locally
+
+Build the API markdown files and the `mkdocs.yml` file:
+
+```
+python scripts/gen_doc.py src/api.json doc/mkdocs
+```
+
+Serve the website locally:
+
+```
+cd doc/mkdocs
+mkdocs serve
+```
+
+Then visit `http://127.0.0.1:8000/` in your browser. Changes you make the markdown files should automatically trigger a reload and display the updated website.
+
+Don't forget that the API reference and the `mkdocs.yml` file are generated:
+
+- If you want to edit the API reference documentation, directly edit the documentation strings in `src/api.json`.
+- If you want to make changes to the `mkdocs.yml` file (for example to add a documentation section), edit `mkdocs_template.yml` file instead.

doc/mkdocs/mkdocs.yml

@@ -15,7 +15,7 @@ nav:
     - Quick Start: 'QuickStart.md'
   - User Guide:
     - API Spec:
-      - Overview: 'api_reference.md'
+      - Overview: 'api/api_reference.md'
       - Utility:
         - Overview: 'api/Utility.md'
         - Algebra: 'api/Utility/Algebra.md'
@@ -37,6 +37,8 @@ nav:
         - Canvas API: 'api/Graphics/Canvas API.md'
         - GLES Surface: 'api/Graphics/GLES Surface.md'
       - UI: 'api/UI.md'
+
   - Developper Guide:
     - Building: 'building.md'
+    - Editing the Documentation: 'documentation.md'
   - FAQ: 'faq.md'

doc/mkdocs/mkdocs_template.yml

@@ -0,0 +1,21 @@
+site_name: Orca Documentation
+site_url: https://docs.orca-app.dev
+site_description: Official Orca Documentation
+
+copyright: Copyright © 2024 Martin Fouilleul and the Orca project contributors
+
+extra_css:
+  - css/extra.css
+theme: readthedocs
+
+nav:
+  - Home: 'index.md'
+  - Getting Started:
+    - Installation: 'install.md'
+    - Quick Start: 'QuickStart.md'
+  - User Guide:
+    {{API_NAV}}
+  - Developper Guide:
+    - Building: 'building.md'
+    - Editing the Documentation: 'documentation.md'
+  - FAQ: 'faq.md'

scripts/gen_doc.py

@@ -517,6 +517,59 @@ def doc_module(outDir, module, dump):
 
 
 
+def gen_mkdoc_api_nav_recursive(dirPath, desc, indent):
+    s = ""
+    for module in desc:
+        moduleName = module["name"]
+        modulePath = os.path.join(dirPath, make_dir_name(moduleName) + ".md")
+
+        subModules = [x for x in module["contents"] if x["kind"] == "module"]
+        if len(subModules):
+            s += gen_indent(indent, width=2)
+            s += f"- {moduleName}:\n"
+            s += gen_indent(indent+1, width=2)
+            s += f"- Overview: '{modulePath}'\n"
+            s += gen_mkdoc_api_nav_recursive(os.path.join(dirPath, make_dir_name(moduleName)), subModules, indent+1)
+        else:
+            s += gen_indent(indent, width=2)
+            s += f"- {moduleName}: '{modulePath}'\n"
+
+    return s
+
+
+def gen_mkdoc_api_nav(dirPath, desc, indent):
+
+    s = "- API Spec:\n"
+    s += gen_indent(indent+1, width=2)
+    s += "- Overview: 'api/api_reference.md'\n"
+
+    s += gen_mkdoc_api_nav_recursive(dirPath, desc, indent+1)
+
+    return s
+
+def gen_mkdoc_yaml(outDir, desc):
+
+    with open(os.path.join(outDir, "mkdocs_template.yml"), "r") as f:
+        template = f.read()
+
+    lines = template.splitlines()
+    indent = -1
+    for line in lines:
+        if "{{API_NAV}}" in line:
+            indent = int((len(line) - len(line.lstrip(' '))) / 2)
+            break
+
+    if indent < 0:
+        print("error: no {{API_NAV}} placeholder found in mkdocs_template.yml")
+        exit(-1)
+
+    s = gen_mkdoc_api_nav("api", desc, indent)
+
+    s = template.replace('{{API_NAV}}', s)
+
+    with open(os.path.join(outDir, "mkdocs.yml"), "w") as f:
+        print(s, file=f, end="", flush=True)
+
 
 parser = ArgumentParser(prog='gen_doc')
 parser.add_argument("desc", help="a json description of the API")
@@ -553,54 +606,4 @@ def doc_module(outDir, module, dump):
 with open(os.path.join(docDir, "api_reference.md"), "w") as f:
     print(s, file=f, end="", flush=True)
 
-
-def gen_mkdoc_api_nav(dirPath, desc, indent):
-    s = ""
-    for module in desc:
-        moduleName = module["name"]
-        modulePath = os.path.join(dirPath, make_dir_name(moduleName) + ".md")
-
-        subModules = [x for x in module["contents"] if x["kind"] == "module"]
-        if len(subModules):
-            s += gen_indent(indent, width=2)
-            s += f"- {moduleName}:\n"
-            s += gen_indent(indent+1, width=2)
-            s += f"- Overview: '{modulePath}'\n"
-            s += gen_mkdoc_api_nav(os.path.join(dirPath, make_dir_name(moduleName)), subModules, indent+1)
-        else:
-            s += gen_indent(indent, width=2)
-            s += f"- {moduleName}: '{modulePath}'\n"
-
-
-    return s
-
-def gen_mkdoc_yaml(outDir, desc):
-    s = ("site_name: Orca Documentation\n"
-         "site_url: https://docs.orca-app.dev\n"
-         "site_description: Official Orca Documentation\n"
-         "\n"
-         "copyright: Copyright &copy; 2024 Martin Fouilleul and the Orca project contributors\n"
-         "\n"
-         "extra_css:\n"
-         "  - css/extra.css\n"
-         "theme: readthedocs\n"
-         "\n"
-         "nav:\n"
-         "  - Home: 'index.md'\n"
-         "  - Getting Started:\n"
-         "    - Installation: 'install.md'\n"
-         "    - Quick Start: 'QuickStart.md'\n"
-         "  - User Guide:\n"
-         "    - API Spec:\n"
-         "      - Overview: 'api_reference.md'\n")
-
-    s += gen_mkdoc_api_nav("api", desc, 3)
-
-    s += ("  - Developper Guide:\n"
-          "    - Building: 'building.md'\n"
-          "  - FAQ: 'faq.md'\n")
-
-    with open(os.path.join(outDir, "mkdocs.yml"), "w") as f:
-        print(s, file=f, end="", flush=True)
-
 gen_mkdoc_yaml(args.outDir, desc)