Merge pull request #492 from Blueprints-org/374-documentation-issue-change-doc-engine-sphinx-to-mkdocs

374 documentation issue change doc engine sphinx to mkdocs

Author: bro-wi

.readthedocs.yaml

@@ -11,9 +11,9 @@ build:
   tools:
     python: "3.12"
 
-# Build documentation in the "docs/" directory with Sphinx
-sphinx:
-   configuration: docs/source/conf.py
+# Build documentation in the "docs/" directory with mkdocs
+mkdocs:
+  configuration: mkdocs.yml
 
 # Optionally build your docs in additional formats such as PDF and ePub
 formats:

README.md

@@ -76,7 +76,7 @@ Our mission is to reduce the cost and time associated with civil engineering cal
 * Steel checks (NEN-EN 1993)
   - *To Be Determined*
 
-* Geotechnical checks (NEN-EN 9997-1
+* Geotechnical checks (NEN-EN 9997-1)
   - *To Be Determined*
 
 * Common calculations
@@ -88,12 +88,32 @@ Our mission is to reduce the cost and time associated with civil engineering cal
 
 <summary> Progress definitions </summary>
 
-| Icon | Definition  |
-| ---  | ---------   |
-| ![](https://img.shields.io/badge/20%25-grey?style=plastic&labelColor=orange) | Just started |
-| ![](https://img.shields.io/badge/50-%25-grey?style=plastic&labelColor=yellow) | Making progress |
-| ![](https://img.shields.io/badge/80%25--grey?style=plastic&labelColor=yellowgreen) | In Review |
-| ✔️  | Done |
+<table border="1">
+  <thead>
+    <tr>
+      <th>Icon</th>
+      <th>Definition</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><img src="https://img.shields.io/badge/20%25-grey?style=plastic&labelColor=orange" alt="20% Icon"></td>
+      <td>Just started</td>
+    </tr>
+    <tr>
+      <td><img src="https://img.shields.io/badge/50-%25-grey?style=plastic&labelColor=yellow" alt="50% Icon"></td>
+      <td>Making progress</td>
+    </tr>
+    <tr>
+      <td><img src="https://img.shields.io/badge/80%25--grey?style=plastic&labelColor=yellowgreen" alt="80% Icon"></td>
+      <td>In Review</td>
+    </tr>
+    <tr>
+      <td>✔️</td>
+      <td>Done</td>
+    </tr>
+  </tbody>
+</table>
 
 </details>
 
@@ -137,39 +157,39 @@ figures for streamlined access and reference.
         Eurocode 2: Design of concrete structures – Part 1-1: General rules and rules for buildings
         (<a href="blueprints/codes/eurocode/nen_en_1992_1_1_c2_2011">code</a>)
       </td>
-      <td><a href="docs/source/codes/eurocode/ec2_1992_1_1_2011/formulas.md">304</a></td>
-      <td><a href="docs/source/codes/eurocode/ec2_1992_1_1_2011/tables.md">38</a></td>
-      <td><a href="docs/source/codes/eurocode/ec2_1992_1_1_2011/figures.md">104</a></td>
+      <td><a href="docs/objects_overview/eurocode/ec2_1992_1_1_2011/formulas.md">304</a></td>
+      <td><a href="docs/objects_overview/eurocode/ec2_1992_1_1_2011/tables.md">38</a></td>
+      <td><a href="docs/objects_overview/eurocode/ec2_1992_1_1_2011/figures.md">104</a></td>
     </tr>
     <tr>
       <td>NEN-EN 1993-1-1+C2+A1:2016</td>
       <td>
         NEN-EN 1993-1-1+C2+A1:2016 | Eurocode 3: Design of steel structures – Part 1-1: General rules and rules for buildings
         (<a href="blueprints/codes/eurocode/nen_en_1993_1_1_c2_a1_2016">code</a>)
       </td>
-      <td><a href="docs/source/codes/eurocode/ec3_1993_1_1_2016/formulas.md">108</a></td>
-      <td><a href="docs/source/codes/eurocode/ec3_1993_1_1_2016/tables.md">20</a></td>
-      <td><a href="docs/source/codes/eurocode/ec3_1993_1_1_2016/figures.md">28</a></td>
+      <td><a href="docs/objects_overview/eurocode/ec3_1993_1_1_2016/formulas.md">108</a></td>
+      <td><a href="docs/objects_overview/eurocode/ec3_1993_1_1_2016/tables.md">20</a></td>
+      <td><a href="docs/objects_overview/eurocode/ec3_1993_1_1_2016/figures.md">28</a></td>
     </tr>
     <tr>
       <td>NEN-EN 1993-5:2008</td>
       <td>
         Eurocode 3: Design of steel structures – Part 5: Piling
         (<a href="blueprints/codes/eurocode/nen_en_1993_5_2008">code</a>)
       </td>
-      <td><a href="docs/source/codes/eurocode/nen_en_1993_5_2008/formulas.md">63</a></td>
-      <td><a href="docs/source/codes/eurocode/nen_en_1993_5_2008/tables.md">0</a></td>
-      <td><a href="docs/source/codes/eurocode/nen_en_1993_5_2008/figures.md">0</a></td>
+      <td><a href="docs/objects_overview/eurocode/nen_en_1993_5_2008/formulas.md">63</a></td>
+      <td><a href="docs/objects_overview/eurocode/nen_en_1993_5_2008/tables.md">0</a></td>
+      <td><a href="docs/objects_overview/eurocode/nen_en_1993_5_2008/figures.md">0</a></td>
     </tr>
     <tr>
       <td>NEN 9997-1+C2:2017</td>
       <td>
         Eurocode 7: Geotechnical design of structures - Part 1: General rules
         (<a href="blueprints/codes/eurocode/nen_9997_1_c2_2017">code</a>)
       </td>
-      <td><a href="docs/source/codes/eurocode/nen_9997_1_c2_2017/formulas.md">88</a></td>
-      <td><a href="docs/source/codes/eurocode/nen_9997_1_c2_2017/tables.md">11</a></td>
-      <td><a href="docs/source/codes/eurocode/nen_9997_1_c2_2017/figures.md">25</a></td>
+      <td><a href="docs/objects_overview/eurocode/nen_9997_1_c2_2017/formulas.md">88</a></td>
+      <td><a href="docs/objects_overview/eurocode/nen_9997_1_c2_2017/tables.md">11</a></td>
+      <td><a href="docs/objects_overview/eurocode/nen_9997_1_c2_2017/figures.md">25</a></td>
     </tr>
   </tbody>
 </table>

docs/DOCS_README.md

@@ -0,0 +1,11 @@
+// this javascript file has to be added according to the mkdocs materials documentation: https://squidfunk.github.io/mkdocs-material/reference/math/#katex
+document$.subscribe(({ body }) => { 
+    renderMathInElement(body, {
+      delimiters: [
+        { left: "$$",  right: "$$",  display: false },
+        { left: "$",   right: "$",   display: false },
+        { left: "\\(", right: "\\)", display: false },
+        { left: "\\[", right: "\\]", display: false}
+      ],
+    })
+  })

docs/Makefile

@@ -0,0 +1,24 @@
+// Use CustomEvent to generate the version selector
+document.addEventListener(
+    "readthedocs-addons-data-ready",
+    function (event) {
+    const config = event.detail.data();
+    const versioning = `
+<div class="md-version">
+<button class="md-version__current" aria-label="Select version">
+${config.versions.current.slug}
+</button>
+
+<ul class="md-version__list">
+${ config.versions.active.map(
+(version) => `
+<li class="md-version__item">
+<a href="${ version.urls.documentation }" class="md-version__link">
+    ${ version.slug }
+</a>
+        </li>`).join("\n")}
+</ul>
+</div>`;
+
+document.querySelector(".md-header__topic").insertAdjacentHTML("beforeend", versioning);
+});

docs/__init__.py

@@ -0,0 +1,54 @@
+/* settings for logo in dark and light mode */
+#logo_light_mode {
+    display: var(--md-footer-logo-light-mode);
+}
+
+#logo_dark_mode {
+    display: var(--md-footer-logo-dark-mode);
+}
+
+[data-md-color-scheme="default"] {
+    --md-footer-logo-dark-mode:         none;
+    --md-footer-logo-light-mode:         block;
+}
+
+[data-md-color-scheme="slate"] {
+    --md-footer-logo-dark-mode:         block;
+    --md-footer-logo-light-mode:         none;
+}
+
+/* hide site_name in header */
+.md-header__topic {
+    display: none;
+}
+
+/* make logo slightly bigger */
+.md-header__button.md-logo {
+    margin-top: 0;
+    margin-bottom: 0;
+    padding-top: 5;
+    padding-bottom: 0;
+}
+
+.md-header__button.md-logo img,
+.md-header__button.md-logo svg {
+    height: 50%;
+    width: 50%;
+}
+
+/* the module name can be too long, set break settings to prevent overlapping the TOC */
+.doc.doc-heading {
+    width: 100%;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;  
+}
+
+.doc.doc-heading:hover {
+    overflow: visible;            /* Reveal the full content */
+    width: 80%;
+    white-space: normal;          /* Allow text to wrap */
+    z-index: 10;                  /* Ensure it overlays nearby elements */
+    max-width: fit-content;       /* Expand to content width */
+    word-break: break-word;       /* Enable word breaks */
+}

docs/source/_static/blueprints_banner.png renamed to docs/_overrides/assets/images/blueprints_banner.png

@@ -0,0 +1,11 @@
+:root {
+    /* Reduce Read the Docs' flyout font a little bit */
+    --readthedocs-flyout-font-size: 0.7rem;
+
+    /* Reduce Read the Docs' notification font a little bit */
+    --readthedocs-notification-font-size: 0.8rem;
+
+    /* This customization is not yet perfect because we can't change the `line-height` yet. */
+    /* See https://github.com/readthedocs/addons/issues/197 */
+    --readthedocs-search-font-size: 0.7rem;
+}

docs/source/_static/favicon.ico renamed to docs/_overrides/assets/images/favicon.ico

@@ -0,0 +1,2 @@
+<img id="logo_light_mode" src="{{ config.theme.logo_light_mode | url }}" alt="logo">
+<img id="logo_dark_mode" src="{{ config.theme.logo_dark_mode | url }}" alt="logo">

docs/source/_static/logo-dark-mode.png renamed to docs/_overrides/assets/images/logo-dark-mode.png

@@ -0,0 +1,6 @@
+{% extends "base.html" %}
+
+{% block site_meta %}
+{{ super() }}
+<meta name="readthedocs-addons-api-version" content="1" />
+{% endblock %}

docs/source/_static/logo-light-mode.png renamed to docs/_overrides/assets/images/logo-light-mode.png

@@ -0,0 +1 @@
+"""Module with scripts for generating documentation."""

docs/_overrides/assets/images/logo.ico

@@ -0,0 +1,39 @@
+"""Generate the code reference pages."""
+
+from pathlib import Path
+
+import mkdocs_gen_files
+
+nav = mkdocs_gen_files.Nav()
+mod_symbol = '<code class="doc-symbol doc-symbol-nav doc-symbol-module"></code>'
+
+root = Path(__file__).parents[2]
+src = root / "blueprints"
+
+for path in sorted(src.rglob("*.py")):
+    module_path = path.relative_to(src).with_suffix("")
+    doc_path = path.relative_to(src).with_suffix(".md")
+    full_doc_path = Path("API reference", doc_path)
+
+    parts = tuple(module_path.parts)
+
+    if parts[-1] == "__init__" and len(parts) > 1:
+        parts = parts[:-1]
+        doc_path = doc_path.with_name("index.md")
+        full_doc_path = full_doc_path.with_name("index.md")
+    elif parts[-1].startswith("_"):
+        continue
+
+    nav_parts = [f"{mod_symbol} {part}" for part in parts]
+    nav[tuple(nav_parts)] = doc_path.as_posix()
+
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        ident = ".".join(parts)
+        title = parts[-1]
+
+        fd.write(f"#{title}\n\n::: {ident}")
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, ".." / path.relative_to(root))
+
+with mkdocs_gen_files.open("API reference/Overview.md", "w") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())

docs/_overrides/assets/javascripts/katex.js

@@ -0,0 +1,3 @@
+# Examples
+
+Here are some examples of how to use the 'Blueprints'.

docs/_overrides/assets/javascripts/readthedocs.js

@@ -0,0 +1,74 @@
+# Nominal Concrete Cover
+
+Calculating the nominal concrete cover is an important step in the design of reinforced concrete structures.
+The nominal concrete cover is the minimum thickness of concrete that separates the reinforcing steel from the environment.
+This thickness is necessary to protect the steel from corrosion and to ensure the durability of the structure.
+
+`Blueprints` provides a simple way to calculate the nominal concrete cover using NEN-EN 1992-1-1:2011.
+This example can be followed step by step by first importing the necessary classes and functions, (or [go to the full code example](#full-code-example)):
+
+```python
+--8<-- "examples/_code/nominal_concrete_cover.py:4:8"
+```
+
+Define the concrete material properties to be used in the calculation:
+
+```python
+--8<-- "examples/_code/nominal_concrete_cover.py:11"
+```
+
+Calculate the structural class by its exposure classes, design working life and other parameters:
+
+```python
+--8<-- "examples/_code/nominal_concrete_cover.py:14:20"
+```
+
+Start the nominal concrete cover calculation:
+
+```python
+--8<-- "examples/_code/nominal_concrete_cover.py:23:34"
+```
+
+Then just print the results:
+
+```python
+--8<-- "examples/_code/nominal_concrete_cover.py:37:47"
+```
+
+The output will be:
+
+```python
+Structural class: S5
+
+C,min,dur: 20.0 mm
+C,min,b: 32.0 mm
+C,min,total: 32.0 mm
+    Cover increase due to uneven surface: 0 mm
+    Cover increase due to abrasion: 0 mm
+
+Nominal concrete cover: 60.0 mm
+    C,nom: 42.0 mm
+    Minimum cover with regard to casting surface: 60.0 mm
+```
+
+You could also use the `NominalConcreteCover` to get a latex representation of the calculation by using:
+
+```python
+--8<-- "examples/_code/nominal_concrete_cover.py:51"
+```
+
+The output will be:
+
+```latex
+Nominal~concrete~cover~according~to~art.~4.4.1~from~NEN-EN~1992-1-1+C2:2011:\newline~\max~\left\{Nominal~concrete~cover~according~to~art.~4.4.1~(c_{nom});~Minimum~cover~with~regard~to~casting~surface~according~to~art.~4.4.1.3~(4)\right\}\newline~=~\max~\left\{42.0;~60.0\right\}~=~60.0~mm\newline~\newline~Where:\newline~\hspace{4ex}c_{nom}~=~c_{min,total}+\Delta~c_{dev}~=~32.0+10~=~42.0~mm\newline~\hspace{4ex}\Delta~c_{dev}~is~determined~according~to~art.~4.4.1.3~(1)\newline~\hspace{4ex}c_{min,total}~=~c_{min}~+~\Delta~c_{uneven~surface}~~+~\Delta~c_{abrasion~class}~=~32.0~+~0~+~0~=~32.0~mm\newline~\hspace{4ex}\Delta~c_{uneven~surface}~and~\Delta~c_{abrasion~class}~are~determined~according~to~art.~4.4.1.2~(11)~and~(13)\newline~\hspace{4ex}c_{min}~=~\max~\left\{c_{min,b};~c_{min,dur}+\Delta~c_{dur,\gamma}-\Delta~c_{dur,st}-\Delta~c_{dur,add};~10~\text{mm}\right\}~=~\max~\left\{32.0;~20.0+10-0-0;~10\right\}~=~32.0~mm\newline~\hspace{4ex}\Delta~c_{dur,\gamma}~,~\Delta~c_{dur,st}~and~\Delta~c_{dur,add}~are~determined~according~to~art.~4.4.1.2~(6),~(7)~and~(8)\newline~\hspace{4ex}c_{min,b}~is~determined~according~to~table~4.2~based~on~(equivalent)~rebar~diameter~=~32~=~32~mm\newline~\hspace{4ex}c_{min,dur}~is~determined~according~to~table~4.4~based~on~structural~class~S5~\&~exposure~classes~(XC1)~=~20~mm
+```
+
+You could use an external service like [lagrida](https://latexeditor.lagrida.com/) to render the latex code or use this output inside a latex or word document of your choice.
+
+<a name="full-code-example">
+The full code example:
+
+```python
+--8<-- "examples/_code/nominal_concrete_cover.py"
+```
+</a>