Set up documentation using mkdocs

CONTRIBUTING.md

@@ -1,5 +1,21 @@
 # Contributing guidelines
 
+## Development
+
+### Building the documentation
+
+The documentation is written in [markdown](https://www.markdownguide.org/basic-syntax/), and uses [mkdocs](https://www.mkdocs.org/) to generate the pages.
+
+To build the documentation for yourself:
+
+```console
+pip install -e .[docs]
+mkdocs serve
+```
+
+You can find the documentation source in the [docs](https://github.com/FormingWorlds/JANUS/tree/main/docs) directory.
+If you are adding new pages, make sure to update the listing in the [`mkdocs.yml`](https://github.com/FormingWorlds/JANUS/blob/main/mkdocs.yml) under the `nav` entry.
+
 ### Running tests
 
 JANUS uses [pytest](https://docs.pytest.org/en/latest/) to run the tests. You can run the tests for yourself using:

docs/CODE_OF_CONDUCT.md

@@ -0,0 +1 @@
+{!../CODE_OF_CONDUCT.md!}

docs/CONTRIBUTING.md

@@ -0,0 +1 @@
+{!../CONTRIBUTING.md!}

docs/getting_started.md

@@ -0,0 +1,8 @@
+This page shows you how to get started using JANUS.
+
+Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
+tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
+quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
+consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
+cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
+proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

docs/index.md

@@ -0,0 +1 @@
+{!../README.md!}

mkdocs.yml

@@ -0,0 +1,67 @@
+site_name: JANUS
+site_url: https://fwljanus.readthedocs.io
+repo_url: https://github.com/FormingWorlds/JANUS
+repo_name: GitHub
+
+nav:
+  - Home: index.md
+  - Getting started: getting_started.md
+  - Contributing: CONTRIBUTING.md
+  - Code of Conduct: CODE_OF_CONDUCT.md
+  - 🔗 Source code: https://github.com/FormingWorlds/JANUS
+  - 🔗 Issues: https://github.com/FormingWorlds/JANUS/issues
+
+theme:
+  name: material
+  palette:
+    primary: black
+    accent: deep orange
+
+extra_css:
+  - stylesheets/extra.css
+
+markdown_extensions:
+  - admonition
+  - attr_list
+  - markdown_include.include:
+      base_path: docs
+  - pymdownx.extra
+  - pymdownx.arithmatex:
+      generic: true
+
+extra_javascript:
+  - https://polyfill.io/v3/polyfill.min.js?features=es6
+  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
+
+plugins:
+- search
+- mkdocstrings:
+    # https://mkdocstrings.github.io/usage/
+    handlers:
+      python:
+        paths: [src]
+        import:
+        - https://installer.readthedocs.io/en/stable/objects.inv
+        - https://numpy.org/doc/stable/objects.inv
+        - https://docs.scipy.org/doc/scipy/objects.inv
+        - https://pandas.pydata.org/docs/objects.inv
+        - https://matplotlib.org/stable/objects.inv
+        options:
+          docstring_style: numpy
+          docstring_options:
+            ignore_init_summary: yes
+          show_submodules: no
+          show_source: true
+          show_root_heading: false
+          show_root_full_path: false
+          docstring_section_style: list
+          members_order: alphabetical
+          merge_init_into_class: yes
+          filters: ["!^_"]
+
+watch:
+  - src/
+  - docs/
+  - README.md
+  - CONTRIBUTING.md
+  - CODE_OF_CONDUCT.md

pyproject.toml

@@ -50,6 +50,12 @@ develop = [
   "coverage[toml]",
   "pytest"
 ]
+docs = [
+    "markdown-include",
+    "mkdocs",
+    "mkdocs-material",
+    "mkdocstrings[python]",
+]
 publishing = [
   "twine",
   "wheel",