Merge pull request #1 from DHI/mkdocs

Use mkdocs for documentation

.github/workflows/docs.yml

@@ -21,13 +21,12 @@ jobs:
       run: |
         pip install .[dev]
     
-    - name: Sphinx Build
+    - name: Build documentstion
       run: |
-        cd docs
-        make html
+        mkdocs build
     
     - name: Publish to GitHub Pages
       uses: peaceiris/[email protected]
       with:
         github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: docs/_build/html
+        publish_dir: site

docs/index.md

@@ -0,0 +1,5 @@
+# Welcome to my_library
+
+See more in [Getting started](getting_started.md)
+
+A complete reference is available [here](reference.md)

docs/reference.md

@@ -0,0 +1,3 @@
+# Reference
+
+::: my_library.simulation

mkdocs.yml

@@ -0,0 +1,12 @@
+site_name: my_library
+
+theme: "material"
+
+plugins:
+- mkdocstrings:
+    handlers:
+      python:
+        options:
+          show_source: false # change this if you prefer to be able to show the source code inside the docs
+          heading_level: 2
+          docstring_style: "numpy" # default is google

my_library/simulation.py

@@ -0,0 +1,38 @@
+"""The simulation module"""
+import numpy as np
+
+
+class Simulator:
+    def __init__(self, name: str, low: float = 0.0, high: float = 1.0) -> None:
+        """Create a new simulator
+
+        Parameters
+        ----------
+        name: str
+            name of simulation
+        low: float, optional
+            lower bound
+        high: float, optional
+            upper bound
+
+        Examples
+        --------
+        >>> sim = Simulator(name="Scenario1", low=2.0, high=10.0)
+        """
+        self._name = name
+        self._low = low
+        self._high = high
+
+    def simulate(self, n_samples: int = 1) -> np.ndarray:
+        """Sample random numbers
+
+        Parameters
+        ----------
+        n_samples: int
+            number of samples
+
+        Returns
+        -------
+        np.ndarray
+        """
+        return np.random.uniform(low=self._low, high=self._high, size=n_samples)

pyproject.toml

@@ -24,7 +24,7 @@ classifiers = [
 ]
 
 [project.optional-dependencies]
-dev = ["pytest","flake8","black","sphinx", "myst-parser","sphinx-book-theme"]
+dev = ["pytest","flake8","black","mkdocs","mkdocstrings[python]", "mkdocs-material"]
 test= ["pytest"]
 
 [project.urls]