From b64afe87737bc828b9b9b99e68ac0211c3e822c2 Mon Sep 17 00:00:00 2001 From: AndreaRigoni Date: Fri, 6 Mar 2026 10:45:33 +0000 Subject: [PATCH] add documention workflow --- .gitea/workflows/publish-docs.yaml | 41 ++ .gitignore | 1 + CMakePresets.json | 16 + docs/assets/css/extensions/tabbed.css | 41 ++ docs/assets/css/extra.css | 17 + docs/docker/Dockerfile | 30 ++ docs/docker/Dockerfile.dev | 14 + docs/docker/docker-compose.yml | 13 + docs/docker/requirements.txt | 17 + docs/docker/runtime.txt | 1 + docs/index.md | 63 +++ docs/python/developer_guide.md | 179 ++++++++ docs/python/installation.md | 146 +++++++ docs/python/usage.md | 373 +++++++++++++++++ mkdocs.yml | 561 ++++++++++++++++++++++++++ 15 files changed, 1513 insertions(+) create mode 100644 .gitea/workflows/publish-docs.yaml create mode 100644 CMakePresets.json create mode 100644 docs/assets/css/extensions/tabbed.css create mode 100644 docs/assets/css/extra.css create mode 100644 docs/docker/Dockerfile create mode 100644 docs/docker/Dockerfile.dev create mode 100644 docs/docker/docker-compose.yml create mode 100644 docs/docker/requirements.txt create mode 100644 docs/docker/runtime.txt create mode 100644 docs/index.md create mode 100644 docs/python/developer_guide.md create mode 100644 docs/python/installation.md create mode 100644 docs/python/usage.md create mode 100644 mkdocs.yml diff --git a/.gitea/workflows/publish-docs.yaml b/.gitea/workflows/publish-docs.yaml new file mode 100644 index 0000000..da24dc1 --- /dev/null +++ b/.gitea/workflows/publish-docs.yaml @@ -0,0 +1,41 @@ +name: MkDocs Subpath Deploy + +on: + push: + branches: + - andrea-dev # Trigger on main branch + +jobs: + build-and-deploy: + runs-on: mildpub # Runner that can access to SSH_YFINPUB_HOST + + steps: + - name: Checkout del codice + uses: actions/checkout@v4 + + - name: Configura Python + uses: actions/setup-python@v5 + with: + python-version: '3.x' + + - name: Installa dipendenze + run: | + python -m pip install --upgrade pip + pip install mkdocs-material + pip install -r requirements.txt + + - name: Build del sito + run: mkdocs build + + - name: Deploy via SSH (SCP) + uses: https://github.com/appleboy/scp-action@master + with: + host: ${{ vars.SSH_YFINPUB_HOST }} + username: ${{ vars.SSH_YFINPUB_USER }} + key: ${{ secrets.MILD_PUB }} + port: 22 + source: "site/*" + # Il percorso sul server deve corrispondere alla tua sottopagina + target: "/var/www/docs/cmt/uLib/" + strip_components: 1 # Rimuove la cartella "site/" e mette solo il contenuto + rm: true # Pulisce la cartella prima di copiare (opzionale, stile Vercel) \ No newline at end of file diff --git a/.gitignore b/.gitignore index 07b2233..f51005d 100644 --- a/.gitignore +++ b/.gitignore @@ -12,3 +12,4 @@ src/Python/uLib/*.so* src/Python/uLib/*.pyd src/Python/uLib/*.pyc src/Python/uLib/__pycache__ +src/Python/uLib/.nfs* diff --git a/CMakePresets.json b/CMakePresets.json new file mode 100644 index 0000000..99c234f --- /dev/null +++ b/CMakePresets.json @@ -0,0 +1,16 @@ +{ + "version": 8, + "configurePresets": [ + { + "name": "andrea", + "displayName": "Custom configure preset", + "description": "Sets Ninja generator, build and install directory", + "generator": "Ninja", + "binaryDir": "${sourceDir}/out/build/${presetName}", + "cacheVariables": { + "CMAKE_BUILD_TYPE": "Debug", + "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}" + } + } + ] +} \ No newline at end of file diff --git a/docs/assets/css/extensions/tabbed.css b/docs/assets/css/extensions/tabbed.css new file mode 100644 index 0000000..7fc9ae2 --- /dev/null +++ b/docs/assets/css/extensions/tabbed.css @@ -0,0 +1,41 @@ +.tabbed-set { + display: flex; + position: relative; + flex-wrap: wrap; +} + +.tabbed-set .highlight { + background: #ddd; +} + +.tabbed-set .tabbed-content { + display: none; + order: 99; + width: 100%; +} + +.tabbed-set label { + width: auto; + margin: 0 0.5em; + padding: 0.25em; + font-size: 120%; + cursor: pointer; + color: #ffffff !important; +} + +.tabbed-set input { + position: absolute; + opacity: 0; +} + +.tabbed-set input:nth-child(n+1) { + color: #333333; +} + +.tabbed-set input:nth-child(n+1):checked + label { + color: cyan !important; +} + +.tabbed-set input:nth-child(n+1):checked + label + .tabbed-content { + display: block; +} \ No newline at end of file diff --git a/docs/assets/css/extra.css b/docs/assets/css/extra.css new file mode 100644 index 0000000..d3d01e7 --- /dev/null +++ b/docs/assets/css/extra.css @@ -0,0 +1,17 @@ +@import "extensions/tabbed.css"; + +.md-grid { + max-width: 100%; +} + +.md-main__inner { + margin-top: 0; + padding-top: 0; +} + +.md-sidebar--secondary { + right: 1.5rem; + top: 4.8rem; + transform: none; + width: 18rem; +} diff --git a/docs/docker/Dockerfile b/docs/docker/Dockerfile new file mode 100644 index 0000000..876ba06 --- /dev/null +++ b/docs/docker/Dockerfile @@ -0,0 +1,30 @@ +# Stage 1: Build the static site using MkDocs +FROM python:3.9-slim-buster as builder + +# Set the working directory +WORKDIR /app + +# Copy the requirements file +COPY requirements.txt . + +# Install the Python dependencies +RUN pip install --no-cache-dir -r requirements.txt + +# Copy the rest of the application files +COPY ../.. . + +# Build the MkDocs site +RUN mkdocs build + + +# Stage 2: Serve the static files with Nginx +FROM nginx:alpine + +# Copy the built site from the builder stage +COPY --from=builder /app/site /usr/share/nginx/html + +# Expose port 80 for the web server +EXPOSE 80 + +# Command to run Nginx in the foreground +CMD ["nginx", "-g", "daemon off;"] diff --git a/docs/docker/Dockerfile.dev b/docs/docker/Dockerfile.dev new file mode 100644 index 0000000..03e90fc --- /dev/null +++ b/docs/docker/Dockerfile.dev @@ -0,0 +1,14 @@ +# Dockerfile for development with live-reloading +FROM python:3.9-slim-buster + +WORKDIR /app + +# Copy and install dependencies +COPY requirements.txt . +RUN pip install --no-cache-dir -r requirements.txt + +# Expose the port MkDocs serve will run on +EXPOSE 8000 + +# Command to run the development server +CMD ["mkdocs", "serve", "--dev-addr", "0.0.0.0:8000"] diff --git a/docs/docker/docker-compose.yml b/docs/docker/docker-compose.yml new file mode 100644 index 0000000..72f8e0a --- /dev/null +++ b/docs/docker/docker-compose.yml @@ -0,0 +1,13 @@ +version: '3.8' + +services: + mkdocs: + build: + context: . + dockerfile: Dockerfile.dev + ports: + - "8000:8000" + volumes: + - ../..:/app + environment: + - GIT_DISCOVERY_ACROSS_FILESYSTEM=1 diff --git a/docs/docker/requirements.txt b/docs/docker/requirements.txt new file mode 100644 index 0000000..c3d1317 --- /dev/null +++ b/docs/docker/requirements.txt @@ -0,0 +1,17 @@ +# ------------------------------------------------------------------ +# MkDocs runtime dependencies for the docs Docker image +# ------------------------------------------------------------------ + +# Core: theme (provides mkdocs itself as a transitive dep) +mkdocs-material==9.7.1 + +# pymdownx.* extensions used in mkdocs.yml: +# arithmatex, highlight, superfences, tabbed, details, blocks.caption +# (also a hard dep of mkdocs-material, pinned here for reproducibility) +pymdown-extensions>=10.0 + +# Markdown math rendering support (arithmatex generic mode) +# JS side is loaded via CDN (polyfill.io + MathJax), no extra Python pkg needed + +# Optional: PDF export plugin (exporter: block, currently commented out in mkdocs.yml) +mkdocs-exporter \ No newline at end of file diff --git a/docs/docker/runtime.txt b/docs/docker/runtime.txt new file mode 100644 index 0000000..548d713 --- /dev/null +++ b/docs/docker/runtime.txt @@ -0,0 +1 @@ +3.7 \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..70e03c7 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,63 @@ +# uLib + +[![DOI](https://zenodo.org/badge/36926725.svg)](https://zenodo.org/badge/latestdoi/36926725) + +**uLib** is the base toolkit library for the **CMT (Cosmic Muon Tomography)** project, developed at the University of Padova and INFN Sezione di Padova, Italy. + +It provides: + +- **Core** – object model, timers, configuration, UUID utilities. +- **Math** – linear algebra (Eigen3), structured grids, voxel images, ray-tracing, image filters. +- **Python bindings** – full pybind11 interface for scripting and analysis workflows. +- Optional **CUDA** acceleration for voxel filtering (transparent RAM ↔ VRAM management). + +--- + +## Quick Start + +=== "Users (pip / poetry)" + ```bash + # Activate your conda/micromamba environment first + micromamba activate mutom + + poetry install # CPU build + USE_CUDA=ON poetry install # GPU build + ``` + +=== "Developers (CMake)" + ```bash + conan install . --output-folder=build --build=missing + cmake --preset conan-release + cmake --build build --target uLib_python -j$(nproc) + + export PYTHONPATH="$(pwd)/build/src/Python:$(pwd)/src/Python" + ``` + +Then in Python: + +```python +import uLib + +# Core +timer = uLib.Core.Timer() +timer.Start() + +# Math +grid = uLib.Math.StructuredGrid([10, 10, 10]) +grid.SetSpacing([1.0, 1.0, 1.0]) + +img = uLib.Math.VoxImage([10, 10, 10]) +img.SetValue(0, 3.14) +print(img.GetValue(0)) +``` + +--- + +## Documentation Sections + +| Section | Description | +|---|---| +| [Python – Installation](python/installation.md) | Environment setup, user install, developer build | +| [Python – API Usage](python/usage.md) | Full API reference with examples | +| [Python – Developer Guide](python/developer_guide.md) | Adding bindings, running tests, build details | +| [C++ Build – Usage & CUDA](usage/usage.md) | CMake build, CUDA configuration | diff --git a/docs/python/developer_guide.md b/docs/python/developer_guide.md new file mode 100644 index 0000000..dea4495 --- /dev/null +++ b/docs/python/developer_guide.md @@ -0,0 +1,179 @@ +# Developer Guide – Python Bindings + +This guide is aimed at contributors who want to extend or modify the Python bindings for `uLib`. + +--- + +## Repository Layout + +``` +ulib/ +├── src/ +│ └── Python/ +│ ├── module.cpp # pybind11 module entry point +│ ├── core_bindings.cpp # uLib::Core bindings +│ ├── math_bindings.cpp # uLib::Math bindings +│ ├── math_filters_bindings.cpp# VoxImageFilter bindings +│ ├── CMakeLists.txt # builds uLib_python shared lib +│ ├── testing/ # Python unit tests +│ │ ├── pybind_test.py +│ │ ├── core_pybind_test.py +│ │ ├── math_pybind_test.py +│ │ └── math_filters_test.py +│ └── uLib/ # Python package (uLib_python.so lands here) +│ └── __init__.py +├── build_python.py # poetry build hook (calls CMake) +├── pyproject.toml # poetry metadata +└── condaenv.yml # conda/micromamba environment +``` + +--- + +## Adding a New Binding + +All bindings live in the four source files listed above. The module entry point `module.cpp` calls `init_core()`, `init_math()`, and `init_math_filters()` in order. + +### 1. Pick (or create) the right binding file + +| C++ header location | Binding file | +|---|---| +| `src/Core/` | `core_bindings.cpp` | +| `src/Math/` (geometry, grids, VoxImage) | `math_bindings.cpp` | +| `src/Math/VoxImageFilter*.hpp` | `math_filters_bindings.cpp` | + +### 2. Add the `#include` directive + +```cpp +// math_bindings.cpp +#include "Math/MyNewClass.h" +``` + +### 3. Write the pybind11 binding inside the appropriate `init_*` function + +```cpp +void init_math(py::module_ &m) { + // ... existing bindings ... + + py::class_(m, "MyNewClass") + .def(py::init<>()) + .def("MyMethod", &MyNewClass::MyMethod) + .def("AnotherMethod", &MyNewClass::AnotherMethod, + py::arg("x"), py::arg("y") = 0.0f); +} +``` + +### 4. Rebuild only the Python target + +```bash +cmake --build build --target uLib_python -j$(nproc) +``` + +### 5. Write a Python test + +Add a new test class to the relevant test file (or create a new one under `src/Python/testing/`): + +```python +# src/Python/testing/math_pybind_test.py +class TestMyNewClass(unittest.TestCase): + def test_basic(self): + obj = uLib.Math.MyNewClass() + result = obj.MyMethod() + self.assertAlmostEqual(result, expected_value) +``` + +Register the test in `src/Python/CMakeLists.txt` if you add a new file: + +```cmake +add_test(NAME pybind_my_new + COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/testing/my_new_test.py) +set_tests_properties(pybind_my_new PROPERTIES + ENVIRONMENT "PYTHONPATH=$:${PROJECT_SOURCE_DIR}/src/Python") +``` + +--- + +## Build System Details + +### CMakeLists.txt (`src/Python/`) + +`pybind11_add_module` compiles the shared library `uLib_python` and links it against the C++ static/shared libraries `uLibCore` and `uLibMath`. The install target copies the `.so` into the standard library directory. + +```cmake +pybind11_add_module(uLib_python + module.cpp core_bindings.cpp math_bindings.cpp math_filters_bindings.cpp) + +target_link_libraries(uLib_python PRIVATE uLibCore uLibMath) +``` + +### poetry / build_python.py + +`pyproject.toml` declares `build_python.py` as the custom build hook. When `poetry install` or `poetry build` is invoked it: + +1. Calls `cmake -DCMAKE_LIBRARY_OUTPUT_DIRECTORY= ...` in `build_python/`. +2. Builds only the `uLib_python` target. +3. The resulting `.so` is placed inside `src/Python/uLib/` so it is picked up by Poetry as a package data file. + +The `USE_CUDA` environment variable gates CUDA support at build time: + +```bash +USE_CUDA=ON poetry install # with CUDA +USE_CUDA=OFF poetry install # CPU only (default) +``` + +--- + +## Running All Tests + +```bash +# From the repository root, with PYTHONPATH set: +export PYTHONPATH="$(pwd)/build/src/Python:$(pwd)/src/Python" + +python -m pytest src/Python/testing/ -v +``` + +Or through CMake's test runner (after building the full project): + +```bash +cd build +ctest --output-on-failure -R pybind +``` + +Expected output (all passing): + +``` + Start 1: pybind_general +1/4 Test #1: pybind_general ............. Passed + Start 2: pybind_core +2/4 Test #2: pybind_core ................ Passed + Start 3: pybind_math +3/4 Test #3: pybind_math ................ Passed + Start 4: pybind_math_filters +4/4 Test #4: pybind_math_filters ........ Passed +``` + +--- + +## Memory Management Notes + +`uLib::Vector` has explicit GPU memory management. When wrapping methods that return references to internal data, use `py::return_value_policy::reference_internal` to avoid dangling references: + +```cpp +.def("Data", &VoxImage::Data, + py::return_value_policy::reference_internal) +``` + +For objects held by `std::unique_ptr` without Python-side deletion, use `py::nodelete`: + +```cpp +py::class_>(m, "AbstractVoxImageFilter") +``` + +--- + +## Useful References + +- [pybind11 documentation](https://pybind11.readthedocs.io) +- [pybind11 – STL containers](https://pybind11.readthedocs.io/en/stable/advanced/cast/stl.html) +- [pybind11 – Eigen integration](https://pybind11.readthedocs.io/en/stable/advanced/cast/eigen.html) +- [CMake – pybind11 integration](https://pybind11.readthedocs.io/en/stable/compiling.html) diff --git a/docs/python/installation.md b/docs/python/installation.md new file mode 100644 index 0000000..281b164 --- /dev/null +++ b/docs/python/installation.md @@ -0,0 +1,146 @@ +# Python Installation + +The `uLib` Python package exposes the Core and Math C++ libraries via [pybind11](https://pybind11.readthedocs.io) bindings. There are two ways to install it: as an **end user** (pre-built wheel / pip) or as a **developer** (editable build from source). + +--- + +## Prerequisites + +`uLib` depends on native C++ libraries that must be compiled. Ensure the following are available in your environment before installing: + +| Dependency | Minimum version | Notes | +|---|---|---| +| Python | 3.9 | | +| CMake | 3.12 | | +| pybind11 | 2.6.0 | | +| Conan | 2.x | for Eigen3 / Boost | +| micromamba / conda | any | recommended – provides ROOT, VTK | + +### Creating the `mutom` Conda/Micromamba Environment + +A ready-to-use environment definition is provided as `condaenv.yml` at the repository root. + +=== "Micromamba" + ```bash + micromamba env create -f condaenv.yml + micromamba activate mutom + ``` + +=== "Conda" + ```bash + conda env create -f condaenv.yml + conda activate mutom + ``` + +The environment installs CMake, Conan, ROOT, VTK, and the compiler toolchain. + +> **CUDA (optional)** +> If you want GPU-accelerated voxel filtering, you also need NVCC inside the environment: +> ```bash +> micromamba install cuda-nvcc -c conda-forge +> ``` + +--- + +## User Installation (wheel / pip) + +Once the native dependencies are present in your environment, install the package with Poetry or pip: + +```bash +# Activate your environment first +micromamba activate mutom + +# Build and install (CUDA disabled by default) +poetry install + +# Build and install with CUDA support +USE_CUDA=ON poetry install +``` + +After installation the module is importable from anywhere in the environment: + +```python +import uLib +print(dir(uLib.Core)) +print(dir(uLib.Math)) +``` + +--- + +## Developer Installation (editable / in-tree build) + +For development you typically want to skip the packaging layer and work directly against the CMake build tree. + +### Step 1 – Install Conan dependencies + +```bash +conan profile detect # first time only +conan install . --output-folder=build --build=missing +``` + +### Step 2 – Configure and build + +```bash +# Standard release build +cmake --preset conan-release + +# …or manually +cmake -B build \ + -DCMAKE_TOOLCHAIN_FILE=build/conan_toolchain.cmake \ + -DCMAKE_BUILD_TYPE=Release \ + -DUSE_CUDA=OFF # set to ON when a GPU is available + +cmake --build build --target uLib_python -j$(nproc) +``` + +The shared library (`uLib_python*.so`) is written to `build/src/Python/`. + +### Step 3 – Make the module importable + +Point `PYTHONPATH` at the build output **and** the Python source directory (the latter carries the `uLib/__init__.py` that stitches sub-modules together): + +```bash +export PYTHONPATH="$(pwd)/build/src/Python:$(pwd)/src/Python:$PYTHONPATH" +python -c "import uLib; print(uLib.__version__)" +``` + +Or, for a one-shot check: + +```bash +PYTHONPATH="build/src/Python:src/Python" python src/Python/testing/pybind_test.py +``` + +### Step 4 – Run the tests + +CMake registers the Python tests alongside the C++ ones; use `ctest` from the build directory: + +```bash +cd build +ctest --output-on-failure -R pybind +``` + +Individual test scripts can also be run directly once `PYTHONPATH` is set: + +```bash +python src/Python/testing/core_pybind_test.py +python src/Python/testing/math_pybind_test.py +python src/Python/testing/math_filters_test.py +``` + +--- + +## Verifying the Installation + +```python +import uLib + +# Core module +obj = uLib.Core.Object() +timer = uLib.Core.Timer() +timer.Start() +elapsed = timer.StopWatch() # float, seconds + +# Math module +v3 = uLib.Math.Vector3f([1.0, 0.0, 0.0]) +print(v3[0]) # 1.0 +``` diff --git a/docs/python/usage.md b/docs/python/usage.md new file mode 100644 index 0000000..3b1a771 --- /dev/null +++ b/docs/python/usage.md @@ -0,0 +1,373 @@ +# Python API Usage + +The `uLib` Python package is split into two sub-modules mirroring the C++ library: + +| Sub-module | Contents | +|---|---| +| `uLib.Core` | Low-level utilities: `Object`, `Timer`, `Options`, `TypeRegister` | +| `uLib.Math` | Geometry, grids, voxel images, ray-tracing, image filters | + +```python +import uLib +# Sub-modules are accessible as attributes +uLib.Core # core utilities +uLib.Math # mathematical structures +``` + +--- + +## uLib.Core + +### Object + +Base class for uLib objects; exposed to Python for type-hierarchy purposes. + +```python +obj = uLib.Core.Object() +copy = obj.DeepCopy() +``` + +### Timer + +Precision wall-clock timer. + +```python +import time +timer = uLib.Core.Timer() +timer.Start() +time.sleep(0.5) +elapsed = timer.StopWatch() # returns elapsed seconds as float +print(f"Elapsed: {elapsed:.3f} s") +``` + +### Options + +Wraps Boost.ProgramOptions for INI-style configuration files. + +```python +opt = uLib.Core.Options("My Program") +opt.parse_config_file("config.ini") # load settings +n = opt.count("my_key") # check if key exists +opt.save_config_file("out.ini") +``` + +--- + +## uLib.Math – Linear Algebra + +The math module exposes Eigen3 vectors and matrices as well-typed Python objects with NumPy interoperability. + +### Fixed-size Vectors + +```python +import numpy as np +import uLib + +# Construct from list +v3 = uLib.Math.Vector3f([1.0, 2.0, 3.0]) +print(v3[0], v3[1], v3[2]) # 1.0 2.0 3.0 + +# Construct from NumPy array +arr = np.array([4.0, 5.0, 6.0], dtype=np.float32) +v3b = uLib.Math.Vector3f(arr) + +# Zero-initialise +v4d = uLib.Math.Vector4d() # all zeros + +# Available types +# Vector1f / 2f / 3f / 4f (float32) +# Vector1d / 2d / 3d / 4d (float64) +# Vector1i / 2i / 3i / 4i (int32) +``` + +### Fixed-size Matrices + +```python +# 2-by-2 float matrix +m2f = uLib.Math.Matrix2f() +m2f[0, 0] = 1; m2f[0, 1] = 2 +m2f[1, 0] = 3; m2f[1, 1] = 4 + +# From list (row-major) +m4f = uLib.Math.Matrix4f([1,0,0,0, 0,1,0,0, 0,0,1,0, 0,0,0,1]) + +# From NumPy (2-D array) +mat = np.eye(3, dtype=np.float32) +m3f = uLib.Math.Matrix3f(mat) + +# Dynamic matrices +mXf = uLib.Math.MatrixXf(4, 4) # 4×4 float, zeros +``` + +### Homogeneous Types + +```python +# HPoint3f – a 3-D point in homogeneous coordinates (w = 1) +p = uLib.Math.HPoint3f(1.0, 2.0, 3.0) + +# HVector3f – a free vector (w = 0) +v = uLib.Math.HVector3f(0.0, 1.0, 0.0) + +# HLine3f – a parametric ray +line = uLib.Math.HLine3f() +line.origin = uLib.Math.HPoint3f(0, 0, 0) +line.direction = uLib.Math.HVector3f(0, 0, 1) +``` + +--- + +## uLib.Math – Transforms and Geometry + +### AffineTransform + +A rigid-body / affine transform stored as a 4×4 matrix. + +```python +tf = uLib.Math.AffineTransform() + +tf.SetPosition([1.0, 0.0, 0.0]) # translate +tf.Translate([0.0, 1.0, 0.0]) # cumulative translate +tf.Scale([2.0, 2.0, 2.0]) # uniform scale +tf.Rotate(uLib.Math.Vector3f([0, 0, 3.14159])) # Euler angles (rad) + +mat4 = tf.GetWorldMatrix() # 4×4 matrix +pos = tf.GetPosition() # Vector3f +``` + +### Geometry + +Inherits `AffineTransform`; converts points between world and local frames. + +```python +geo = uLib.Math.Geometry() +geo.SetPosition([1.0, 1.0, 1.0]) + +world_pt = uLib.Math.Vector4f([2.0, 3.0, 2.0, 1.0]) +local_pt = geo.GetLocalPoint(world_pt) +back = geo.GetWorldPoint(local_pt) +# back ≈ [2, 3, 2, 1] +``` + +### ContainerBox + +An axis-aligned bounding box with an associated transform. + +```python +box = uLib.Math.ContainerBox() +box.SetOrigin([-1.0, -1.0, -1.0]) +box.SetSize([2.0, 2.0, 2.0]) +print(box.GetSize()) # [2, 2, 2] +``` + +--- + +## uLib.Math – Structured Grids + +### StructuredGrid (3-D) + +A 3-D voxel grid (origin, spacing, and integer dimensions). + +```python +dims = uLib.Math.Vector3i([10, 10, 10]) +grid = uLib.Math.StructuredGrid(dims) +grid.SetSpacing([1.0, 1.0, 1.0]) +grid.SetOrigin([0.0, 0.0, 0.0]) + +print(grid.GetSpacing()) # [1, 1, 1] +print(grid.IsInsideBounds([5, 5, 5, 1])) # True +idx = grid.Find([2.5, 2.5, 2.5]) # returns grid cell index +``` + +### Structured2DGrid / Structured4DGrid + +```python +grid2d = uLib.Math.Structured2DGrid() +grid2d.SetDims([100, 100]) +grid2d.SetPhysicalSpace([0, 0], [1, 1]) +print(grid2d.GetSpacing()) +``` + +--- + +## uLib.Math – VoxImage + +`VoxImage` is a 3-D voxel volume where each cell stores a `Voxel` ( `.Value` + `.Count`). + +```python +dims = uLib.Math.Vector3i([20, 20, 20]) +img = uLib.Math.VoxImage(dims) +img.SetSpacing([0.5, 0.5, 0.5]) + +# Access by linear index +img.SetValue(0, 42.0) +print(img.GetValue(0)) # 42.0 + +# Access by 3-D index +img.SetValue(uLib.Math.Vector3i([1, 1, 1]), 7.5) +print(img.GetValue(uLib.Math.Vector3i([1, 1, 1]))) # 7.5 + +# Clipping / masking helpers +cropped = img.clipImage(uLib.Math.Vector3i([2, 2, 2]), + uLib.Math.Vector3i([18, 18, 18])) +masked = img.maskImage(0.0, 100.0, 0.0) # mask outside [0, 100] + +# I/O +img.ExportToVti("output.vti") +img.ImportFromVti("output.vti") +``` + +### Voxel (element type) + +```python +vox = uLib.Math.Voxel() +vox.Value = 1.5 +vox.Count = 3 + +data = img.Data() # returns the underlying Vector_Voxel +vox0 = data[0] +print(vox0.Value, vox0.Count) +``` + +--- + +## uLib.Math – VoxRaytracer + +Performs ray-tracing through a `StructuredGrid` and returns per-voxel chord lengths. + +```python +import numpy as np +import uLib + +grid = uLib.Math.StructuredGrid([10, 10, 10]) +grid.SetSpacing([1.0, 1.0, 1.0]) +grid.SetOrigin([0.0, 0.0, 0.0]) + +rt = uLib.Math.VoxRaytracer(grid) + +# Trace a ray between two homogeneous points (x, y, z, w=1) +p1 = np.array([0.5, 0.5, -1.0, 1.0], dtype=np.float32) +p2 = np.array([0.5, 0.5, 11.0, 1.0], dtype=np.float32) +result = rt.TraceBetweenPoints(p1, p2) + +print("Voxels crossed:", result.Count()) +print("Total length :", result.TotalLength()) + +elements = result.Data() +for i in range(result.Count()): + print(f" vox_id={elements[i].vox_id} L={elements[i].L:.4f}") +``` + +--- + +## uLib.Math – Image Filters + +All filters share the same interface: construct with a kernel size, attach a `VoxImage`, optionally set parameters, then call `.Run()`. + +```python +import uLib + +dims = uLib.Math.Vector3i([10, 10, 10]) +img = uLib.Math.VoxImage(dims) +for i in range(10**3): + img.SetValue(i, float(i)) + +kernel_dims = uLib.Math.Vector3i([3, 3, 3]) +``` + +### Linear (Gaussian / Box) Filter + +```python +filt = uLib.Math.VoxFilterAlgorithmLinear(kernel_dims) +filt.SetImage(img) +filt.SetKernelNumericXZY([1.0] * 27) # uniform box kernel, length = product of dims +filt.Run() +``` + +### ABTrim Filter + +Applies alpha-beta trimming to remove outliers before averaging. + +```python +filt = uLib.Math.VoxFilterAlgorithmAbtrim(kernel_dims) +filt.SetImage(img) +filt.SetKernelNumericXZY([1.0] * 27) +filt.SetABTrim(2, 2) # trim 2 low and 2 high values +filt.Run() +``` + +### Bilateral Filter + +Edge-preserving smoothing controlled by a spatial sigma (from the kernel shape) and an intensity sigma. + +```python +filt = uLib.Math.VoxFilterAlgorithmBilateral(kernel_dims) +filt.SetImage(img) +filt.SetKernelNumericXZY([1.0] * 27) +filt.SetIntensitySigma(0.3) +filt.Run() +``` + +### Threshold Filter + +Zeros voxels below a threshold. + +```python +filt = uLib.Math.VoxFilterAlgorithmThreshold(kernel_dims) +filt.SetImage(img) +filt.SetKernelNumericXZY([1.0] * 27) +filt.SetThreshold(0.5) +filt.Run() +``` + +### Median Filter + +```python +filt = uLib.Math.VoxFilterAlgorithmMedian(kernel_dims) +filt.SetImage(img) +filt.SetKernelNumericXZY([1.0] * 27) +filt.Run() +``` + +--- + +## uLib.Math – Accumulators + +Accumulators collect scalar samples and return a summary statistic. + +```python +# Arithmetic mean +acc = uLib.Math.Accumulator_Mean_f() +acc(10.0) +acc(20.0) +mean = acc() # 15.0 + +# Alpha-beta trimmed mean +acc2 = uLib.Math.Accumulator_ABTrim_f() +acc2.SetABTrim(0.1, 0.1) # trim bottom 10 % and top 10 % +acc2 += 1.0 +acc2 += 9999.0 # outlier +acc2 += 5.0 +result = acc2() # trimmed mean ≈ 3.0 +``` + +--- + +## Dynamic Vectors (`uLib.Math.Vector_*`) + +Typed dynamic arrays backed by `uLib::Vector` with optional CUDA memory management. + +```python +# Integer vector +vi = uLib.Math.Vector_i() +vi.append(1); vi.append(2); vi.append(3) +print(len(vi), vi[0]) + +# Float vector with CUDA management +vf = uLib.Math.Vector_f() +vf.append(1.5) +vf.MoveToVRAM() # copy to GPU (no-op when CUDA is absent) +vf.MoveToRAM() # copy back to CPU + +# Other types: Vector_ui, Vector_l, Vector_ul, Vector_d +# Compound element types: Vector_Vector3f, Vector_Vector4f, Vector_Voxel … +``` diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..2681b5b --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,561 @@ +# site_name: uLib Documentation +# site_description: CMT Cosmic Muon Tomography – uLib toolkit +# site_author: Andrea Rigoni Garola +# repo_url: https://github.com/cmt/ulib +# docs_dir: docs + +# +--------------------------------------------------------------------------------------------------------+ +# | | +# | This is the main file used by MkDocs to build the pages. | +# | It contains a lot of information and settings for you to read and use. | +# | Comments may contain "Read More" URLs to more in-depth documentation about the option for you to read. | +# | | +# | You can check out https://www.mkdocs.org/user-guide/configuration/ for a more detailed explanation of | +# | all the options MkDocs offers by default. | +# | | +# +------------------------------------------------- NOTE -------------------------------------------------+ +# | | +# | Some of the options listed here are only available through the usage of Material for MkDocs. | +# | Those options will usually have a link to the docs of this Theme and also mention "Material" as name. | +# | The actual name of the theme is "Material for MkDocs" and "Material" is used for simplicity reasons. | +# | | +# +--------------------------------------------------------------------------------------------------------+ + +# +--------------------------------------------------------------------------------------------------------+ +# | | +# | Main Page Settings for MkDocs. | +# | Those settings are site name, site description, Site author and also Site URL (Canonical URL) | +# | | +# | Read More: | +# | - https://www.mkdocs.org/user-guide/configuration/#site_name | +# | - https://www.mkdocs.org/user-guide/configuration/#site_description | +# | - https://www.mkdocs.org/user-guide/configuration/#site_author | +# | - https://www.mkdocs.org/user-guide/configuration/#site_url | +# | | +# +--------------------------------------------------------------------------------------------------------+ +site_name: OpenCMT uLib Documentation +site_url: https://docs.mildstone.org/uLib/ # <--- project subfolder +use_directory_urls: true +site_description: 'Documentation for OpenCMT uLib' +site_author: 'Andrea Rigoni Garola' + +# +--------------------------------------------------------------------------------------------------------+ +# | | +# | This setting allows you to define your own Copyright notice. | +# | The text is treated as HTML code so you can use things like tags or © to display the | +# | Copyright icon. | +# | | +# | Where or IF the Copyright is displayed depends on the theme you use. | +# | | +# | Read More: | +# | - https://www.mkdocs.org/user-guide/configuration/#copyright | +# | | +# +--------------------------------------------------------------------------------------------------------+ +copyright: | + © Author + +# +--------------------------------------------------------------------------------------------------------+ +# | | +# | The base folder to use. | +# | Any Markdown files you put into this folder will be turned into a static HTML page once you build or | +# | publish your page. | +# | | +# | It is also used as the base directory for other settings like the "extra_css" or "extra_javascript" | +# | option. | +# | | +# +--------------------------------------------------------------------------------------------------------+ +docs_dir: docs/ + + +# +--------------------------------------------------------------------------------------------------------+ +# | | +# | These options allow to define a Repository to link to. | +# | The result will, depending on the theme, be a link somewhere shown on the page that links to the | +# | Repository with the specified repo_name. | +# | | +# | This will also enable a "edit" button on the page itself that allows the direct editing of the page. | +# | You can disable this by setting "edit_uri" to an empty String. | +# | | +# | Read More: | +# | - https://www.mkdocs.org/user-guide/configuration/#repo_name | +# | - https://www.mkdocs.org/user-guide/configuration/#repo_url | +# | - https://www.mkdocs.org/user-guide/configuration/#edit_uri | +# | | +# +--------------------------------------------------------------------------------------------------------+ +repo_name: OpenCMT/uLib +repo_url: https://gitea.mildstone.org/OpenCMT/uLib.git +#edit_uri: tree/master/docs # Uncomment to define a different URI/URL for the "edit" option + +# +--------------------------------------------------------------------------------------------------------+ +# | | +# | The "nav" option is where you define the navigation to show in MkDocs. | +# | | +# | Depending on the theme you use will the resulting Navigation look different. | +# | | +# | You can set different types of navigations. Either just the path, the path with a separate title or | +# | an external URL. | +# | | +# | Read More: | +# | - https://www.mkdocs.org/user-guide/configuration/#documentation-layout | +# | | +# +--------------------------------------------------------------------------------------------------------+ + +nav: + - Home: index.md + - Python: + - Installation: python/installation.md + - API Usage: python/usage.md + - Developer Guide: python/developer_guide.md + - C++ Build: + - Usage & CUDA: usage/usage.md + +# +--------------------------------------------------------------------------------------------------------+ +# | | +# | The "theme" section allows you to define what theme to use. | +# | It is also used for theme-specific options, but also for advanced stuff such as theme-extensions, if | +# | the theme actually supports it. | +# | | +# | Read More: | +# | - https://www.mkdocs.org/user-guide/configuration/#theme | +# | | +# +--------------------------------------------------------------------------------------------------------+ +theme: + + # +------------------------------------------------------------------------------------------------------+ + # | | + # | The "name" option is where you define the theme to use. | + # | | + # | Note that not all themes are included by default and will require you to install them first. | + # | The Material theme is one of them. See the "Read More" link for instructions on how to install it. | + # | | + # | Read More: | + # | - https://squidfunk.github.io/mkdocs-material/getting-started/ | + # | | + # +------------------------------------------------------------------------------------------------------+ + name: 'material' + + + # +------------------------------------------------------------------------------------------------------+ + # | | + # | The Material theme allows "theme-extsnions", meaning that you can override parts of it by either | + # | overriding a particular file, or only parts (blocks) of it. | + # | | + # | If you want to override parts of Material, uncomment the "custom_dir" option below and set the | + # | folder (relative to the mkdocs.yml file) where your theme extensions will be located at. | + # | | + # | Read More: | + # | - https://www.mkdocs.org/user-guide/configuration/#custom_dir | + # | - https://squidfunk.github.io/mkdocs-material/customization/#extending-the-theme | + # | | + # +------------------------------------------------------------------------------------------------------+ + #custom_dir: 'theme' + + # +------------------------------------------------------------------------------------------------------+ + # | | + # | The "favicon" option allows you to set your own image/icon to use in the browser-tab. | + # | | + # | Pretty much all image types are supported, but it's recommended to use a PNG, SVG or ICO image for | + # | the favicon. | + # | | + # | The directory is relative to the "docs_dir". | + # | | + # | Example: Having a favicon.png in docs/assets/images will result in the "favicon" setting showing | + # | 'assets/images/favicon.png' | + # | | + # | Read More: | + # | - https://squidfunk.github.io/mkdocs-material/setup/changing-the-logo-and-icons/#favicon | + # | | + # +------------------------------------------------------------------------------------------------------+ + #favicon: 'assets/images/favicon.png' + + # +------------------------------------------------------------------------------------------------------+ + # | | + # | The "palette" section is a Material option and allows you to define specific style options such as | + # | Color-Scheme, and primary and secondary Color. | + # | | + # | You can also define multiple palettes that can have different Color Schemses and primary and/or | + # | secondary Colors. | + # | | + # | Read More: | + # | - https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/ | + # | - https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/#color-palette-toggle | + # | | + # +------------------------------------------------------------------------------------------------------+ + palette: + + # Palette toggle for light mode + - media: "(prefers-color-scheme: light)" + scheme: default + primary: 'indigo' + accent: 'indigo' + toggle: + icon: material/brightness-7 + name: Switch to dark mode + + # Palette toggle for dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: 'indigo' + accent: 'indigo' + toggle: + icon: material/brightness-4 + name: Switch to light mode + + # +------------------------------------------------------------------------------------------------------+ + # | | + # | With the "font" option can you set a different font to use. | + # | | + # | Material supports all Google fonts, but you can also define your own ones if you choose so. | + # | | + # | The "text" option is used for the regular font while "code" is used for code blocks, inline code and | + # | similar. | + # | | + # | Read More: | + # | - https://squidfunk.github.io/mkdocs-material/setup/changing-the-fonts/ | + # | | + # +------------------------------------------------------------------------------------------------------+ + #font: + # text: 'Roboto' + # code: 'Roboto Mono' + + # +------------------------------------------------------------------------------------------------------+ + # | | + # | Material suppors more than 40 different languages which you can set using the "language" option | + # | below. | + # | | + # | The default language is "en" (English). | + # | | + # | You can also enable/set a "selector" to allow switching between languages. | + # | See the "alternate" option in the "extra" section below for more information on this topic. | + # | | + # | Read More: | + # | - https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/ | + # | | + # +------------------------------------------------------------------------------------------------------+ + #language: 'en' + + # +------------------------------------------------------------------------------------------------------+ + # | | + # | The "direction" option is commonly used together with the "language" option. | + # | | + # | It allows you to change the text direction from the default left-to-right (ltr) to right-to-left | + # | (rtl) which is used in certain languages. | + # | | + # | Read More: | + # | - https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#directionality | + # | | + # +------------------------------------------------------------------------------------------------------+ + #direction: 'ltr' + + # +------------------------------------------------------------------------------------------------------+ + # | | + # | The "features" option allows you to enable specific features of Material, by adding them to the | + # | list. | + # | | + # | Features are in the format .. As an example, the feature to enable tabs is called | + # | navigation.tabs. | + # | | + # | The list below contains all known features of Material. | + # | | + # | Features marked with a * are currently Insiders-only. (Last update: 11th December 2021) | + # | https://squidfunk.github.io/mkdocs-material/insiders/ | + # | | + # | Read More: | + # | - https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/ | + # | | + # +------------------------------------------------------------------------------------------------------+ + features: + # Announce + # + #- announce.dismiss # Adds a "X" button to dismiss a news banner/mark it as read.* + + # Header + # + #- header.autohide # Hide header when user scrolls past a specific point. + + # Navigation: + # + #- navigation.expand # Expand all collapsable sections. + #- navigation.instant # Instant loading pages. + #- navigation.indexes # Attach pages directly to Sections. Incompatible with "toc.integrate" + #- navigation.sections # Render top sections as groups. + - navigation.tabs # Render top sections as tabs at the top. + #- navigation.tabs.sticky # Tabs won't disappear when scrolling down. Requires "navigation.tabs". + #- navigation.top # Adds a "Back to top" that is shown when scrolling up. + #- navigation.tracking # Updates the url with highlighted section anchor. + + # Search + # + #- search.highlight # Search will highlight the searched word(s) on the page.* + #- search.share # Adds an option to share a search query link.* + #- search.suggest # Search will suggest the likeliest completion for a word.* + + # Table of Contents + # + #- toc.integrate # Include the TOC sections in the left navugation. + + # +------------------------------------------------------------------------------------------------------+ + # | | + # | The "icon" section allows you to define a icon to use for the logo and/or repository. | + # | | + # | To use already available icons will you need to set the right path for it, depending on which you | + # | want to use. | + # | | + # | Available icons: | + # | - FontAwesome | + # | - Brands: fontawesome/brands/... (https://fontawesome.com/icons?d=gallery&p=2&s=brands&m=free) | + # | - Regular: fontawesome/regular/... (https://fontawesome.com/icons?d=gallery&p=2&s=regular&m=free) | + # | - Solid: fontawesome/solid/... (https://fontawesome.com/icons?d=gallery&p=2&s=solid&m=free) | + # | | + # | - Material Design Icons: material/... (https://materialdesignicons.com/) | + # | | + # | - Octicons: octicons/... (https://primer.style/octicons/) | + # | | + # | You can also define your own Image for the logo. To do that, remove the "logo" option from "icon" | + # | instead add a "logo" option on the same level as the "icon" one, where you then set the path | + # | (relative to the "docs_dir") to the icon to use. Supported are all images types, including SVG. | + # | | + # | Read More: | + # | - https://squidfunk.github.io/mkdocs-material/setup/changing-the-logo-and-icons/#logo | + # | | + # +------------------------------------------------------------------------------------------------------+ + icon: + logo: 'material/library' + repo: 'material/library' + + # +------------------------------------------------------------------------------------------------------+ + # | | + # | The "admonition" option allows you to set a different icon for each admonition type. | + # | | + # | This is currently a Insiders-only feature. (Last update: 7th October 2021) | + # | https://squidfunk.github.io/mkdocs-material/insiders/ | + # | | + # | Supported are all bundled icons: | + # | - FontAwesome | + # | - Brands: fontawesome/brands/... (https://fontawesome.com/icons?d=gallery&p=2&s=brands&m=free) | + # | - Regular: fontawesome/regular/... (https://fontawesome.com/icons?d=gallery&p=2&s=regular&m=free) | + # | - Solid: fontawesome/solid/... (https://fontawesome.com/icons?d=gallery&p=2&s=solid&m=free) | + # | | + # | - Material Design Icons: material/... (https://materialdesignicons.com/) | + # | | + # | - Octicons: octicons/... (https://primer.style/octicons/) | + # | | + # | You can also create and use your own icons. See the documentation for more information. | + # | | + # | Read More: | + # | - https://squidfunk.github.io/mkdocs-material/reference/admonitions/#changing-the-icons | + # | | + # +------------------------------------------------------------------------------------------------------+ + #admonition: + # note: 'octicons/tag-16' + # abstract: 'octicons/checklist-16' + # info: 'octicons/info-16' + # tip: 'octicons/squirrel-16' + # success: 'octicons/check-16' + # question: 'octicons/question-16' + # warning: 'octicons/alert-16' + # failure: 'octicons/x-circle-16' + # danger: 'octicons/zap-16' + # bug: 'octicons/bug-16' + # example: 'octicons/beaker-16' + # quote: 'octicons/quote-16' + +# +--------------------------------------------------------------------------------------------------------+ +# | | +# | With the "extra_css" option can you add your own (S)CSS files to enhance the documentation. | +# | | +# | The path to the file is relative to the "docs_dir". | +# | | +# | Read More: | +# | - https://www.mkdocs.org/user-guide/configuration/#extra_css | +# | | +# +--------------------------------------------------------------------------------------------------------+ +extra_css: + - assets/css/extra.css + +# +--------------------------------------------------------------------------------------------------------+ +# | | +# | Similar to the "extra_css" option does the "extra_javascript" option allow you to set custom JS files | +# | to add extra featurues. | +# | | +# | The path to the file is relative to the "docs_dir". | +# | | +# | Read More: | +# | - https://www.mkdocs.org/user-guide/configuration/#extra_javascript | +# | | +# +--------------------------------------------------------------------------------------------------------+ +extra_javascript: + - https://polyfill.io/v3/polyfill.min.js?features=es6 + - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js + +# +--------------------------------------------------------------------------------------------------------+ +# | | +# | The "extra" section contains pretty much anything you want, as long as it is a valid key-value pair. | +# | | +# | Material uses this section for different custom settings that wouldn't fit in the theme section. | +# | | +# | Read More: | +# | - https://www.mkdocs.org/user-guide/configuration/#extra | +# | | +# +--------------------------------------------------------------------------------------------------------+ +extra: + # +------------------------------------------------------------------------------------------------------+ + # | | + # | The social section allows you to set a list of entries which would be displayed in the footer of the | + # | page. | + # | | + # | Each entry has the exact same options: | + # | - icon: Path to the SVG icon to use. See "icon" section for available icon sets. | + # | - link: URL to which the icon should link. | + # | - name: Optional Name that would be displayed as title on hover. | + # | | + # | Read More: | + # | - https://squidfunk.github.io/mkdocs-material/setup/setting-up-the-footer/#social-links | + # | | + # +------------------------------------------------------------------------------------------------------+ + social: + - icon: 'fontawesome/brands/github' + link: 'https://github.com/Andre601/mkdocs-template' + + # +------------------------------------------------------------------------------------------------------+ + # | | + # | Allows you to hide the "Made with Material for MkDocs" text in the footer of the pages by setting | + # | this to "true". | + # | | + # | Read More: | + # | - https://squidfunk.github.io/mkdocs-material/setup/setting-up-the-footer/#generator-notice | + # | | + # +------------------------------------------------------------------------------------------------------+ + #generator: true + + # +------------------------------------------------------------------------------------------------------+ + # | | + # | The "manifest" option allows you to define a .manifest file to use. | + # | | + # | A .manifest file makes the doc act like a web-application and tells it how to behave when installed. | + # | | + # | Read More: | + # | - https://squidfunk.github.io/mkdocs-material/reference/meta-tags/#adding-a-web-app-manifest | + # | | + # +------------------------------------------------------------------------------------------------------+ + #manifest: manifest.webmanifest + + # +------------------------------------------------------------------------------------------------------+ + # | | + # | The "alternate" option can be used to create a selector to switch languages. | + # | | + # | Using this requires you to create a specific, more complicated MkDocs setup. | + # | | + # | A Setup Guide for multi-language docs can be found here: | + # | https://github.com/squidfunk/mkdocs-material/discussions/2346 | + # | | + # | Read More: | + # | - https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language-selector | + # | | + # +------------------------------------------------------------------------------------------------------+ + #alternate: + +# +--------------------------------------------------------------------------------------------------------+ +# | | +# | MkDocs allows the usage of Markdown extensions which can do various things. | +# | | +# | Material includes the pymdownx extension which provides a lot of useful features to use. | +# | | +# | Note that some extensions may use specific settings that you need to set. | +# | Please check out the official documentation of PyMdownx for more information: | +# | https://facelessuser.github.io/pymdown-extensions/ | +# | | +# | Material already provides required CSS and JS values for the PyMdownX Extensions, which means you do | +# | not need to set them up yourself. | +# | | +# | Read More: | +# | - https://www.mkdocs.org/user-guide/configuration/#markdown_extensions | +# | | +# +--------------------------------------------------------------------------------------------------------+ +markdown_extensions: + - markdown.extensions.admonition: + - markdown.extensions.codehilite: + guess_lang: false + - markdown.extensions.toc: + permalink: true + - pymdownx.arithmatex: + generic: true + - attr_list + - md_in_html + - pymdownx.blocks.caption + - admonition + - pymdownx.highlight: + anchor_linenums: true + - pymdownx.superfences + - pymdownx.tabbed: + alternate_style: true + - pymdownx.details + - attr_list + - tables + + #- pymdownx.b64: + #- pymdownx.betterem: + #- pymdownx.caret: + #- pymdownx.critic: + #- pymdownx.details: + #- pymdownx.emoji: + #- pymdownx.escapeall: + #- pymdownx.extra: + #- pymdownx.extrarawhtml: + #- pymdownx.highlight: + #- pymdownx.inlinehilite: + #- pymdownx.keys: + #- pymdownx.magiclink: + #- pymdownx.mark: + #- pymdownx.pathconverter: + #- pymdownx.progressbar: + #- pymdownx.smartsymbols: + #- pymdownx.snippets: + #- pymdownx.striphtml: + #- pymdownx.superfences: + #- pymdownx.tabbed: + #- pymdownx.tasklist: + #- pymdownx.tilde: + # - exporter: + # formats: + # pdf: + # enabled: !ENV [MKDOCS_EXPORTER_PDF, true] + # concurrency: 8 + # stylesheets: + # - resources/stylesheets/pdf.scss + # covers: + # front: resources/templates/covers/front.html.j2 + # back: resources/templates/covers/back.html.j2 + # aggregator: + # enabled: true + # output: .well-known/site.pdf + # covers: all + +# theme: +# name: material +# palette: +# - scheme: default +# primary: indigo +# accent: blue +# toggle: +# icon: material/brightness-7 +# name: Switch to dark mode +# - scheme: slate +# primary: indigo +# accent: blue +# toggle: +# icon: material/brightness-4 +# name: Switch to light mode +# features: +# - navigation.tabs +# - navigation.sections +# - navigation.top +# - content.code.copy +# - content.tabs.link + +# plugins: +# - search + +# markdown_extensions: + +