Several improvements to the generation of docs

KaruroChori · Dec 17, 2024 · 0387d2f · 0387d2f
1 parent 5f0db7e
commit 0387d2f
Show file tree

Hide file tree

Showing 12 changed files with 67 additions and 56 deletions.
diff --git a/README.md b/README.md
@@ -131,8 +131,8 @@ You can read more about which features are planned in the [milestones page](./MI
 ## Useful documentation
 
 - Instuctions [for developers](./docs/developers/index.md)
-- Instuctions ~~[for users](./docs/intro.md) of vs~~
-- Complete ~~[specifications](./docs/developers/full-specs.md) for `vs`~~.
+- Instuctions ~~[for users](./docs/users/index.md) of vs~~
+- Complete ~~[specifications](./docs/full-specs/index.md) for `vs`~~.
 
 ## Licences
 
@@ -187,4 +187,3 @@ This project is based on the following dependencies:
 
 [Building-Testing-badge]: https://github.com/KaruroChori/vs-fltk/actions/workflows/build.yml/badge.svg?branch=master
 [Building-Testing-url]: https://github.com/KaruroChori/vs-fltk/actions/workflows/build.yml
-
diff --git a/docs/LICENCE.md b/docs/LICENCE.md
diff --git a/docs/developers/building.md b/docs/developers/building.md
@@ -65,6 +65,9 @@ There are also some more or less optional dependencies:
 To generate the additional documentation for distribution and consumption:
 
 - [mkdocs](https://www.mkdocs.org/) and several packages for themes and extensions.
+  - `mkdocs`
+  - `mkdocs-github-admonitions-plugin`
+  - more to be documented
 - [doxygen](https://www.doxygen.nl/) for documentation generated from the code itself.
 
 ### IDE integrations

diff --git a/docs/developers/index.md b/docs/developers/index.md
@@ -4,4 +4,4 @@
 - Information about [contributing](./contributing.md) to `vs`.
 - Conventions for [versioning](./versioning.md).
 - How to publish a [new release](./releasing.md).
-- Full [specifications](./full-specs/index.md) of `vs`.
+- Full [specifications](../full-specs/index.md) of `vs`.
diff --git a/docs/developers/todo.md b/docs/developers/todo.md
@@ -1,4 +1,4 @@
-# Missing for release 0.1.1
+## Missing for release 0.1.1
 
 ### Flatpak issues
 

diff --git a/docs/developers/full-specs/index.md → docs/full-specs/index.md b/docs/developers/full-specs/index.md → docs/full-specs/index.md
diff --git a/docs/developers/full-specs/paths.md → docs/full-specs/paths.md b/docs/developers/full-specs/paths.md → docs/full-specs/paths.md
diff --git a/docs/intro.md → docs/index.md b/docs/intro.md → docs/index.md
diff --git a/docs/env-vars.md → docs/users/env-vars.md b/docs/env-vars.md → docs/users/env-vars.md
diff --git a/docs/file-types.md → docs/users/file-types.md b/docs/file-types.md → docs/users/file-types.md
diff --git a/docs/safety-policies.md → docs/users/safety-policies.md b/docs/safety-policies.md → docs/users/safety-policies.md
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -3,8 +3,12 @@ repo_url: https://github.com/karurochori/vs-fltk
 site_dir: dist/website
 docs_dir: docs
 
-theme: readthedocs
+theme:
+  name: readthedocs
+  custom_dir: ./
+  logo: commons/assets/logos/vs.light.svg
 markdown_extensions:
+  - admonition
   - pymdownx.tilde
   - pymdownx.tasklist
   - sane_lists
@@ -13,3 +17,4 @@ markdown_extensions:
       permalink: "#"
 plugins:
   - search
+  - gh-admonitions