Merge pull request #43 from arcaneframework/doc-audit-2026-07-03-0948

Doc audit 2026 07 03 0948

Author: gratienj

README.md

@@ -139,6 +139,72 @@ In short:
   - `Main/` (ShArc.exe entry point).
 - `test/` contains the reference cases and CTest scenarios (TwoPhaseFlowSimulation, CAWF, ExaDiBench, ThermoChemicalConvection, large-scale SPE10).
 
+## IV/ Documentation
+
+ShArc ships with a Hugo + Doxygen documentation site under the `docs/` directory.
+
+There are two main usage modes:
+
+### IV.1/ Local documentation (developer mode)
+
+To browse the documentation locally while developing:
+
+1. Install Hugo (extended version), for example on Ubuntu:
+
+   ```bash
+   sudo apt install hugo
+   ```
+
+2. From the **root of the repository** (not from `docs/`), start the Hugo server:
+
+   ```bash
+   cd /path/to/sharc
+   hugo server --config docs/hugo.yaml -D
+   ```
+
+   Then open the URL printed by Hugo (typically `http://localhost:1313/` or a similar port).
+
+Internally:
+
+- Hugo uses `docs/hugo.yaml` as its configuration file.
+- Content is under `docs/content/` (sections `src/`, `test/`, `api/`, `architecture/`).
+- Layouts and theme are under `docs/layouts/` and `docs/themes/hugo-book/`.
+- The documentation pages for the main modules/tests **include** the Markdown files
+  from the project (`src/README.md`, `test/.../README.md`, `ARCHITECTURE.md`) via a
+  custom shortcode, which is why Hugo must be run from the repository root.
+
+### IV.2/ Deployed documentation (GitHub Pages via CI)
+
+The repository also includes a GitHub Actions workflow that automatically builds and
+publishes the documentation to the `docs/` folder on the `main` branch, suitable for
+GitHub Pages:
+
+- Workflow file: `.github/workflows/docs.yml`
+  - On each push to `main`, it runs:
+
+    ```bash
+    hugo --config docs/hugo.yaml
+    ```
+
+    which generates the static site into `docs/public/`.
+
+  - Then it copies the generated files into `docs/` (adds `.nojekyll`) and commits the
+    changes back to `main`.
+
+To use GitHub Pages with this workflow:
+
+1. In the GitHub repository settings, under **Pages**, choose:
+   - Branch: `main`
+   - Folder: `/docs`
+
+2. Ensure the workflow is enabled (default for Actions).
+
+3. After a push on `main`, GitHub Actions will regenerate the documentation website,
+   and GitHub Pages will serve it from the `/docs` directory.
+
+This setup keeps documentation generation automated while still allowing local
+preview (`hugho server`) and manual edits of the Markdown files in `src/` and `test/`.
+
 
 ### II.2/ Installation guide
 

docs/hugo.yaml

@@ -1,19 +1,31 @@
-baseURL: http://localhost:1313/
+baseURL: https://arcaneframework.github.io/sharc/
 title: "sharc"
 theme: hugo-book
 disableKinds: ["taxonomy", "term"]
 defaultContentLanguage: "fr"
 
-# IMPORTANT: on traite le dépôt racine comme projet Hugo, et la doc
-# vit dans le sous-répertoire `docs/`. Cela permet à Hugo de lire
-# les fichiers Markdown dans `src/` et `test/` via `readFile`.
+# IMPORTANT
+# ----------
+# On considère la RACINE du dépôt comme projet Hugo, et `docs/` comme
+# sous-répertoire :
+#   - contenu : docs/content
+#   - layouts : docs/layouts
+#   - thème   : docs/themes
+#   - static  : docs/static
+#   - output  : docs/public
+#
+# => Il faut lancer Hugo depuis la racine du dépôt, par exemple :
+#      hugo server --config docs/hugo.yaml -D
+#    ou  hugo --config docs/hugo.yaml
 
 contentDir: docs/content
-staticDir: ["docs/static"]
 layoutDir: docs/layouts
 themesDir: docs/themes
+staticDir: ["docs/static"]
 publishDir: docs/public
 
+canonifyURLs: true
+
 params:
   description: "Documentation du projet"
   BookSearch: true

docs/public/404.html

@@ -11,7 +11,7 @@
 <meta name="description" content="">
 <meta name="theme-color" media="(prefers-color-scheme: light)" content="#ffffff">
 <meta name="theme-color" media="(prefers-color-scheme: dark)" content="#2e3440">
-<meta name="color-scheme" content="light dark"><meta property="og:url" content="http://localhost:1313/404.html">
+<meta name="color-scheme" content="light dark"><meta property="og:url" content="https://arcaneframework.github.io/sharc/404.html">
 	<meta property="og:site_name" content="sharc">
 	<meta property="og:title" content="404 Page not found">
 	<meta property="og:description" content="Documentation du projet">
@@ -23,13 +23,13 @@
 	<meta itemprop="description" content="Documentation du projet">
 
 <title>404 Page not found • sharc</title>
-<link rel="icon" href="/favicon.png" >
-<link rel="manifest" href="/manifest.json">
-<link rel="canonical" href="http://localhost:1313/404.html">
-<link rel="stylesheet" href="/book.min.98c83e4c8e1c8661368bcb29bbaf4dcc9d31b8164f76aae322d82d86a9750c65.css" integrity="sha256-mMg&#43;TI4chmE2i8spu69NzJ0xuBZPdqrjItgthql1DGU=" crossorigin="anonymous">
+<link rel="icon" href="https://arcaneframework.github.io/sharc/favicon.png" >
+<link rel="manifest" href="https://arcaneframework.github.io/sharc/manifest.json">
+<link rel="canonical" href="https://arcaneframework.github.io/sharc/404.html">
+<link rel="stylesheet" href="https://arcaneframework.github.io/sharc/book.min.98c83e4c8e1c8661368bcb29bbaf4dcc9d31b8164f76aae322d82d86a9750c65.css" integrity="sha256-mMg&#43;TI4chmE2i8spu69NzJ0xuBZPdqrjItgthql1DGU=" crossorigin="anonymous">
 
 
-  <script defer type="module" src="/fr.search.min.82a75c690351c998fc20be88fb7271f17457708ec2cd694bf7fe49fd04920d56.js" integrity="sha256-gqdcaQNRyZj8IL6I&#43;3Jx8XRXcI7CzWlL9/5J/QSSDVY=" crossorigin="anonymous"></script>
+  <script defer type="module" src="https://arcaneframework.github.io/sharc/fr.search.min.7c6ed2e0c014d5c79d3c8c54b307cb49561af63f3e18d0930c74e11645699b49.js" integrity="sha256-fG7S4MAU1cedPIxUswfLSVYa9j8&#43;GNCTDHThFkVpm0k=" crossorigin="anonymous"></script>
 
   <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.css">
 <script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.js"></script>
@@ -96,7 +96,7 @@ <h1>
       <span>Found</span>
     </h1>
     <h3>
-      <a href="/">sharc</a>
+      <a href="https://arcaneframework.github.io/sharc/">sharc</a>
     </h3>
   </main>
 

docs/public/api/index.xml

@@ -2,14 +2,14 @@
 <rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
 	<channel>
 		<title>API on sharc</title>
-		<link>http://localhost:1313/api/</link>
+		<link>https://arcaneframework.github.io/sharc/api/</link>
 		<description>Recent content in API on sharc</description>
 		<generator>Hugo</generator>
 		<language>fr</language>
 
 
 
 
-			<atom:link href="http://localhost:1313/api/index.xml" rel="self" type="application/rss+xml" />
+			<atom:link href="https://arcaneframework.github.io/sharc/api/index.xml" rel="self" type="application/rss+xml" />
 	</channel>
 </rss>

docs/public/architecture/index.html

@@ -16,7 +16,7 @@
 ">
 <meta name="theme-color" media="(prefers-color-scheme: light)" content="#ffffff">
 <meta name="theme-color" media="(prefers-color-scheme: dark)" content="#2e3440">
-<meta name="color-scheme" content="light dark"><meta property="og:url" content="http://localhost:1313/architecture/">
+<meta name="color-scheme" content="light dark"><meta property="og:url" content="https://arcaneframework.github.io/sharc/architecture/">
 	<meta property="og:site_name" content="sharc">
 	<meta property="og:title" content="Architecture">
 	<meta property="og:description" content="🧠 Cette page a été générée avec l’aide de l’IA à partir de l’analyse du code source et de recherches web.
@@ -37,14 +37,14 @@
 	<meta itemprop="wordCount" content="921">
 
 <title>Architecture • sharc</title>
-<link rel="icon" href="/favicon.png" >
-<link rel="manifest" href="/manifest.json">
-<link rel="canonical" href="http://localhost:1313/architecture/">
-<link rel="stylesheet" href="/book.min.98c83e4c8e1c8661368bcb29bbaf4dcc9d31b8164f76aae322d82d86a9750c65.css" integrity="sha256-mMg&#43;TI4chmE2i8spu69NzJ0xuBZPdqrjItgthql1DGU=" crossorigin="anonymous">
+<link rel="icon" href="https://arcaneframework.github.io/sharc/favicon.png" >
+<link rel="manifest" href="https://arcaneframework.github.io/sharc/manifest.json">
+<link rel="canonical" href="https://arcaneframework.github.io/sharc/architecture/">
+<link rel="stylesheet" href="https://arcaneframework.github.io/sharc/book.min.98c83e4c8e1c8661368bcb29bbaf4dcc9d31b8164f76aae322d82d86a9750c65.css" integrity="sha256-mMg&#43;TI4chmE2i8spu69NzJ0xuBZPdqrjItgthql1DGU=" crossorigin="anonymous">
 
 
-  <script defer type="module" src="/fr.search.min.82a75c690351c998fc20be88fb7271f17457708ec2cd694bf7fe49fd04920d56.js" integrity="sha256-gqdcaQNRyZj8IL6I&#43;3Jx8XRXcI7CzWlL9/5J/QSSDVY=" crossorigin="anonymous"></script>
-<link rel="alternate" type="application/rss+xml" href="http://localhost:1313/architecture/index.xml" title="Architecture" />
+  <script defer type="module" src="https://arcaneframework.github.io/sharc/fr.search.min.7c6ed2e0c014d5c79d3c8c54b307cb49561af63f3e18d0930c74e11645699b49.js" integrity="sha256-fG7S4MAU1cedPIxUswfLSVYa9j8&#43;GNCTDHThFkVpm0k=" crossorigin="anonymous"></script>
+<link rel="alternate" type="application/rss+xml" href="https://arcaneframework.github.io/sharc/architecture/index.xml" title="Architecture" />
 
   <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.css">
 <script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.js"></script>
@@ -70,7 +70,7 @@
 
   <nav>
 <h2 class="book-brand">
-  <a class="flex align-center" href="/"><span>sharc</span>
+  <a class="flex align-center" href="https://arcaneframework.github.io/sharc/"><span>sharc</span>
   </a>
 </h2>
 
@@ -104,7 +104,7 @@ <h2 class="book-brand">
 
 
 
-    <a href="/docs/" class="">
+    <a href="https://arcaneframework.github.io/sharc/docs/" class="">
       Documentation</a>
 
 
@@ -123,7 +123,7 @@ <h2 class="book-brand">
 
 
 
-    <a href="/architecture/" class="active">
+    <a href="https://arcaneframework.github.io/sharc/architecture/" class="active">
       Architecture</a>
 
 
@@ -142,7 +142,7 @@ <h2 class="book-brand">
 
 
 
-    <a href="/src/" class="">
+    <a href="https://arcaneframework.github.io/sharc/src/" class="">
       src</a>
 
 
@@ -156,7 +156,7 @@ <h2 class="book-brand">
 
 
 
-    <a href="/src/cawf/" class="">
+    <a href="https://arcaneframework.github.io/sharc/src/cawf/" class="">
       CAWF</a>
 
 
@@ -175,7 +175,7 @@ <h2 class="book-brand">
 
 
 
-    <a href="/src/exadibench/" class="">
+    <a href="https://arcaneframework.github.io/sharc/src/exadibench/" class="">
       ExaDiBench</a>
 
 
@@ -194,7 +194,7 @@ <h2 class="book-brand">
 
 
 
-    <a href="/src/main/" class="">
+    <a href="https://arcaneframework.github.io/sharc/src/main/" class="">
       Main</a>
 
 
@@ -213,7 +213,7 @@ <h2 class="book-brand">
 
 
 
-    <a href="/src/sharc/" class="">
+    <a href="https://arcaneframework.github.io/sharc/src/sharc/" class="">
       ShArc</a>
 
 
@@ -232,7 +232,7 @@ <h2 class="book-brand">
 
 
 
-    <a href="/src/twophaseflowsimulation/" class="">
+    <a href="https://arcaneframework.github.io/sharc/src/twophaseflowsimulation/" class="">
       TwoPhaseFlowSimulation</a>
 
 
@@ -256,7 +256,7 @@ <h2 class="book-brand">
 
 
 
-    <a href="/test/" class="">
+    <a href="https://arcaneframework.github.io/sharc/test/" class="">
       test</a>
 
 
@@ -270,7 +270,7 @@ <h2 class="book-brand">
 
 
 
-    <a href="/test/cawf/" class="">
+    <a href="https://arcaneframework.github.io/sharc/test/cawf/" class="">
       Tests CAWF</a>
 
 
@@ -289,7 +289,7 @@ <h2 class="book-brand">
 
 
 
-    <a href="/test/exadibench/" class="">
+    <a href="https://arcaneframework.github.io/sharc/test/exadibench/" class="">
       Tests ExaDiBench</a>
 
 
@@ -308,7 +308,7 @@ <h2 class="book-brand">
 
 
 
-    <a href="/test/thermochemicalconvection/" class="">
+    <a href="https://arcaneframework.github.io/sharc/test/thermochemicalconvection/" class="">
       Tests ThermoChemicalConvection</a>
 
 
@@ -327,7 +327,7 @@ <h2 class="book-brand">
 
 
 
-    <a href="/test/twophaseflowsimulation/" class="">
+    <a href="https://arcaneframework.github.io/sharc/test/twophaseflowsimulation/" class="">
       Tests TwoPhaseFlowSimulation</a>
 
 
@@ -351,7 +351,7 @@ <h2 class="book-brand">
 
 
 
-    <a href="/api/" class="">
+    <a href="https://arcaneframework.github.io/sharc/api/" class="">
       API</a>
 
 
@@ -395,14 +395,14 @@ <h2 class="book-brand">
 
   <div class="flex align-center justify-between">
   <label for="menu-control">
-    <img src="/icons/menu.svg" class="book-icon" alt="Menu" />
+    <img src="https://arcaneframework.github.io/sharc/icons/menu.svg" class="book-icon" alt="Menu" />
   </label>
 
   <h3>Architecture</h3>
 
   <label for="toc-control">
 
-    <img src="/icons/toc.svg" class="book-icon" alt="Table of Contents" />
+    <img src="https://arcaneframework.github.io/sharc/icons/toc.svg" class="book-icon" alt="Table of Contents" />
 
   </label>
 </div>
@@ -706,17 +706,17 @@ <h2 id="5-architecture-de-la-documentation">5. Architecture de la documentation<
 <div class="flex flex-wrap justify-between">
     <span>
 
-      <a href="/docs/" class="flex align-center">
-        <img src="/icons/backward.svg" class="book-icon" alt="Backward" />
+      <a href="https://arcaneframework.github.io/sharc/docs/" class="flex align-center">
+        <img src="https://arcaneframework.github.io/sharc/icons/backward.svg" class="book-icon" alt="Backward" />
         <span>Documentation</span>
       </a>
 
     </span>
     <span>
 
-      <a href="/src/" class="flex align-center">
+      <a href="https://arcaneframework.github.io/sharc/src/" class="flex align-center">
         <span>src</span>
-        <img src="/icons/forward.svg" class="book-icon" alt="Forward" />
+        <img src="https://arcaneframework.github.io/sharc/icons/forward.svg" class="book-icon" alt="Forward" />
       </a>
 
     </span>

docs/public/architecture/index.xml

@@ -2,14 +2,14 @@
 <rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
 	<channel>
 		<title>Architecture on sharc</title>
-		<link>http://localhost:1313/architecture/</link>
+		<link>https://arcaneframework.github.io/sharc/architecture/</link>
 		<description>Recent content in Architecture on sharc</description>
 		<generator>Hugo</generator>
 		<language>fr</language>
 
 
 
 
-			<atom:link href="http://localhost:1313/architecture/index.xml" rel="self" type="application/rss+xml" />
+			<atom:link href="https://arcaneframework.github.io/sharc/architecture/index.xml" rel="self" type="application/rss+xml" />
 	</channel>
 </rss>