From 549cecd3ffccf13206fe5b45551aa69497ce6e17 Mon Sep 17 00:00:00 2001 From: Stef Smeets Date: Wed, 24 Jul 2024 17:14:16 +0200 Subject: [PATCH] Add boilerplate for documentation with mkdocs (#35) --- CONTRIBUTING.md | 16 +++++++++ docs/CODE_OF_CONDUCT.md | 1 + docs/CONTRIBUTING.md | 1 + docs/getting_started.md | 8 +++++ docs/index.md | 1 + docs/stylesheets/extra.css | 0 mkdocs.yml | 67 ++++++++++++++++++++++++++++++++++++++ pyproject.toml | 6 ++++ 8 files changed, 100 insertions(+) create mode 100644 docs/CODE_OF_CONDUCT.md create mode 100644 docs/CONTRIBUTING.md create mode 100644 docs/getting_started.md create mode 100644 docs/index.md create mode 100644 docs/stylesheets/extra.css create mode 100644 mkdocs.yml diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ca294ed..9846153 100644 --- a/CONTRIBUTING.md +++ b/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: diff --git a/docs/CODE_OF_CONDUCT.md b/docs/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..14a6a4a --- /dev/null +++ b/docs/CODE_OF_CONDUCT.md @@ -0,0 +1 @@ +{!../CODE_OF_CONDUCT.md!} diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 0000000..568877b --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1 @@ +{!../CONTRIBUTING.md!} diff --git a/docs/getting_started.md b/docs/getting_started.md new file mode 100644 index 0000000..c5091b1 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..7d211af --- /dev/null +++ b/docs/index.md @@ -0,0 +1 @@ +{!../README.md!} diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css new file mode 100644 index 0000000..e69de29 diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..6936764 --- /dev/null +++ b/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 diff --git a/pyproject.toml b/pyproject.toml index 016f8b4..2c03e79 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -50,6 +50,12 @@ develop = [ "coverage[toml]", "pytest" ] +docs = [ + "markdown-include", + "mkdocs", + "mkdocs-material", + "mkdocstrings[python]", +] publishing = [ "twine", "wheel",