From 7dc80771145673b1fc7edd991d5755b33e1db812 Mon Sep 17 00:00:00 2001
From: DuncDennis <90915296+DuncDennis@users.noreply.github.com>
Date: Sun, 12 Mar 2023 16:41:08 +0100
Subject: [PATCH] Added simple documentation with mkdocs.

---
 docs/index.md               | 12 ++++++++++
 docs/reference.md           |  8 +++++++
 mkdocs.yml                  |  7 ++++++
 pyproject.toml              |  3 +++
 src/lorenzpy/simulations.py | 48 +++++++++++++++++++++++++++++++++----
 5 files changed, 74 insertions(+), 4 deletions(-)
 create mode 100644 docs/index.md
 create mode 100644 docs/reference.md
 create mode 100644 mkdocs.yml

diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..a3cb61c
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,12 @@
+# Welcome to LorenzPy
+
+This site contains the documentation for the `LorenzPy` Python package 
+that can be used to simulate and measure discrete and continuous chaotic dynamical 
+systems.
+
+## Contents: 
+
+1. [Reference](reference.md) The API reference. 
+
+## Project Overview: 
+::: lorenzpy
diff --git a/docs/reference.md b/docs/reference.md
new file mode 100644
index 0000000..a5fef88
--- /dev/null
+++ b/docs/reference.md
@@ -0,0 +1,8 @@
+### LorenzPy package:
+::: lorenzpy
+
+### simulations module: 
+::: lorenzpy.simulations
+
+### measures module: 
+::: lorenzpy.measures
diff --git a/mkdocs.yml b/mkdocs.yml
new file mode 100644
index 0000000..d74c374
--- /dev/null
+++ b/mkdocs.yml
@@ -0,0 +1,7 @@
+site_name: LorenzPy Docs
+
+theme:
+  name: "material"
+
+plugins:
+  - mkdocstrings
diff --git a/pyproject.toml b/pyproject.toml
index 66c343e..72d5cf1 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -17,6 +17,9 @@ dev = [
     "black==22.12.0",
     "mypy==1.1.1",
     "ruff==0.0.254",
+    "mkdocs",
+    "mkdocstrings[python]",
+    "mkdocs-material"
 ]
 plot = [
     "plotly==5.13.1",
diff --git a/src/lorenzpy/simulations.py b/src/lorenzpy/simulations.py
index 8ea4222..33aaf7a 100644
--- a/src/lorenzpy/simulations.py
+++ b/src/lorenzpy/simulations.py
@@ -1,9 +1,32 @@
-"""Simulate various chaotic system to generate artificial data.
+"""Simulate various continuous and discrete chaotic dynamical system.
 
 Every dynamical system is represented as a class.
-The general syntax for simulating the trajectory is:
-trajectory = SystemClass(parameters=<default>).simulate(time_steps,
-starting_point=<default>)
+
+The available classes are:
+- Lorenz63
+
+The system's parameters are introduced in the class's constructor.
+
+For example when creating a system object of the Lorenz63, the Lorenz parameters,
+sigma, rho, beta, and the timestep dt are parsed as:
+
+sys_obj = Lorenz63(sigma=10, rho=10, beta=5, dt=1)
+
+Each sys_obj contains a "simulate" function.
+To simulate 1000 time-steps of the Lorenz63 system call:
+
+sys_obj.simulate(1000).
+
+The general syntax to create a trajectory of a System is given as:
+
+trajectory = <SystemClass>(<parameters>=<default>).
+simulate(time_steps, starting_point=<default>)
+
+Examples:
+    >>> import lorenzpy.simulations as sims
+    >>> data = sims.Lorenz63().simulate(1000)
+    >>> data.shape
+    (1000, 3)
 """
 
 from __future__ import annotations
@@ -171,3 +194,20 @@ def flow(self, x: np.ndarray) -> np.ndarray:
                 x[0] * x[1] - self.beta * x[2],
             ]
         )
+
+
+def double_num(x: float) -> float:
+    """Double a number.
+
+    Examples:
+        >>> double_num(3)
+        6
+
+
+    Args:
+        x: Input number to be doubled.
+
+    Returns:
+        Double of x.
+    """
+    return 2 * x