Doc creation

.github/workflows/python-app.yml

@@ -29,6 +29,18 @@ jobs:
         run: |
             uv sync --all-extras
             uvx ty check
+
+  doc-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+      - name: Build Doc
+        run: |
+          uv sync --all-extras --group doc
+          uv run mkdocs build
+
 
   testing:
     strategy:
@@ -37,7 +49,7 @@ jobs:
         os: [ubuntu-latest, windows-latest]
 
     runs-on: ${{ matrix.os }}
-    needs: [check-format]
+    needs: [check-format, doc-test]
 
     steps:
     - uses: actions/checkout@v6

.gitignore

@@ -11,3 +11,4 @@ wheels/
 .env
 tmp
 pytest.log
+site/

docs/cli-ref.md

@@ -0,0 +1,2 @@
+::: cyclopts
+    module: pyxems.run:app

docs/index.md

@@ -0,0 +1,4 @@
+# pyXEMS
+
+This project aims to create a pure python generator for [OpenEMS](openems.de).
+This package ease the creation of the XML file used by openEMS to configure its simulation.

mkdocs.yml

@@ -0,0 +1,18 @@
+site_name: Pyxems Documentation
+
+nav:
+  - Home: index.md
+  - CLI Ref: cli-ref.md
+
+theme:
+  name: material
+  features:
+    - navigation.indexes
+
+plugins:
+- search
+- cyclopts
+- mkdocstrings:
+    docstring_style: google
+- api-autonav:
+    modules: ['src/pyxems']

pyproject.toml

@@ -40,3 +40,10 @@ dev = [
     "poethepoet>=0.40.0",
     "pytest>=9.0.2",
 ]
+doc = [
+    "cyclopts[mkdocs]>=4.5.1",
+    "mkdocs>=1.6.1",
+    "mkdocs-api-autonav>=0.4.0",
+    "mkdocs-material>=9.7.2",
+    "mkdocstrings[python]>=1.0.3",
+]

src/pyxems/run.py

@@ -19,6 +19,11 @@
 
 
 def find_openems_executable() -> Optional[Path]:
+    """
+    Find the OpenEMS executable by checking the system PATH and the OPENEMS_PATH environment variable.
+    Returns:
+        Optional[Path]: The path to the OpenEMS executable if found, otherwise None.
+    """
     if which("openEMS") is not None:
         logging.info(f"Found OpenEMS executable in PATH: {which('openEMS')}")
         return Path(which("openEMS"))  # type: ignore
@@ -40,12 +45,21 @@ def find_openems_executable() -> Optional[Path]:
 
 
 def check_config() -> bool:
+    """
+    Check if the OpenEMS executable is available.
+
+    Returns:
+        bool: True if the OpenEMS executable is found, False otherwise.
+    """
     openems_executable = find_openems_executable()
     return openems_executable is not None
 
 
 @app.command()
 def simulate(config_path: Path, run_dir: Optional[Path]) -> CompletedProcess:
+    """
+    Run an OpenEMS simulation using the specified configuration file and optional run directory.
+    """
     openems_path = find_openems_executable()
     if openems_path is None:
         raise FileNotFoundError(