Merge pull request #14 from rl-institut/feature-4-mkdocs

Add MkDocs documentation #4
rl-institut · Feb 2, 2023 · 4315a5f · 4315a5f
2 parents 3f36ce1 + 8494706
commit 4315a5f
Show file tree

Hide file tree

Showing 16 changed files with 157 additions and 1 deletion.
diff --git a/.gitignore b/.gitignore
@@ -118,7 +118,7 @@ venv.bak/
 .ropeproject
 
 # mkdocs documentation
-/site
+/super-docs/site
 
 # mypy
 .mypy_cache/

diff --git a/docs/collaboration/citation.md b/docs/collaboration/citation.md
@@ -0,0 +1,3 @@
+# Citation
+
+See the *Cite this repository* function or [CITATION.cff](https://github.com/rl-institut/super-repo/blob/develop/CITATION.cff) for citation of this repository.
diff --git a/docs/collaboration/code_of_conduct.md b/docs/collaboration/code_of_conduct.md
@@ -0,0 +1,4 @@
+# Code of Conduct
+
+This repository is following the [Contributor Covenant Code of Conduct](https://github.com/rl-institut/super-repo/blob/production/CODE_OF_CONDUCT.md). <br>
+Everyone is asked to be self-reflective and always maintain a good culture of discussion and active participation.
diff --git a/docs/collaboration/contributing.md b/docs/collaboration/contributing.md
@@ -0,0 +1,6 @@
+# Contributing
+
+This software is licensed under an open-source license and can be downloaded, 
+executed and modified. <br>
+To contribute to the collaborative development follow the workflow described in 
+[CONTRIBUTING.md](https://github.com/rl-institut/super-repo/blob/develop/CONTRIBUTING.md). 
diff --git a/docs/collaboration/index.md b/docs/collaboration/index.md
@@ -0,0 +1,4 @@
+# Collaboration
+
+This open-source software is a collaborative effort. <br>
+The repository has several elements to provide necessary functions.
diff --git a/docs/collaboration/license.md b/docs/collaboration/license.md
@@ -0,0 +1,4 @@
+# License
+
+This software is developed under an [open-source license](https://en.wikipedia.org/wiki/Open-source_license). <br>
+The selected license can be read in the [LICENSE.txt](https://github.com/rl-institut/super-repo/blob/develop/LICENSE.txt).
diff --git a/docs/collaboration/users.md b/docs/collaboration/users.md
@@ -0,0 +1,3 @@
+# Users
+
+Known user of this software can be added to [USERS.cff](https://github.com/rl-institut/super-repo/blob/develop/USERS.cff) for reference.
diff --git a/docs/css/extra.css b/docs/css/extra.css
@@ -0,0 +1,7 @@
+:root > * {
+    --md-primary-fg-color:        #0f3b64;
+    --md-primary-fg-color--dark: #5d6cc0;
+    --md-typeset-a-color: #5ba6ec;
+    /* --md-text-font-color:         #ffffff;  */
+    /* --md-primary-fg-color--light: #ECB7B7; */
+  }
diff --git a/docs/documentation/index.md b/docs/documentation/index.md
@@ -0,0 +1,19 @@
+# Documentation
+
+- README.rst
+- CHANGELOG.md
+- docs/
+- MkDocs
+- mkdocstrings
+
+
+## MkDocs
+
+`pip install mkdocs` install MkDocs <br>
+`pip install mkdocs-material` install the material theme <br>
+`mkdocs serve` start the local live version of the documentation
+
+`mkdocs build` build the documentation
+
+Publish MkDocs project on github pages (requires permissions on repository) <br>
+`mkdocs gh-deploy` manually deploy the local docs files to github pages
diff --git a/docs/git/index.md b/docs/git/index.md
@@ -0,0 +1,7 @@
+# Git
+
+- .gitignore
+- .github
+- issue_template
+- pull_request_template
+- workflows (testing)
diff --git a/docs/img/logo_oefamily_small.png b/docs/img/logo_oefamily_small.png
diff --git a/docs/img/logo_rli_small.png b/docs/img/logo_rli_small.png
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,22 @@
+---
+hide:
+  - footer
+  - toc
+---
+
+# Welcome to the Super-Repo Documentation
+
+A template repo to test and document elements and features for research software. <br>
+It implements the collection of repository elements and files. <br>
+The goal is to simplify and standardise the creation of software in GitHub repositories.
+
+## Fields for development:
+
+- COLLABORATION
+- GIT
+- DOCUMENTATION
+- INSTALL
+- CODE-STYLE
+- TESTS
+- LOGGING
+- RELEASE
diff --git a/docs/install/index.md b/docs/install/index.md
@@ -0,0 +1,7 @@
+# Install
+
+- requirements.txt
+- requirements_dev.txt
+- environment.yml
+- setup.py
+- pyproject.toml
diff --git a/docs/release/index.md b/docs/release/index.md
@@ -0,0 +1,6 @@
+# Release
+
+- RELEASE_PROCEDURE.md
+- VERSION
+- MANIFEST.in
+- .bumpversion.cfg
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -0,0 +1,64 @@
+# Project
+site_name: Super-Repo Documentation
+site_url: 
+site_description: Write your documentation in Markdown and create a static page for your developer and user community
+
+# Repository
+repo_name: rl-institut/super-repo
+repo_url: https://github.com/rl-institut/super-repo
+docs_dir: docs
+
+# Configuration
+theme:
+  name: material
+  logo: img/logo_rli_small.png
+  palette:
+    # Palette toggle for dark mode
+    - scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+    # Palette toggle for light mode
+    - scheme: default
+      toggle:
+        icon: material/brightness-7 
+        name: Switch to dark mode
+  icon:
+    repo: fontawesome/brands/github
+  features:
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.sections
+    - navigation.indexes
+    - navigation.path
+    - navigation.tracking
+    - navigation.top
+    - toc.follow
+
+# Customization
+extra:
+  generator: false
+
+extra_css:
+  - css/extra.css
+
+# Navigation
+nav:
+  - Home: index.md
+  - Development:
+    - Collaboration:
+      - collaboration/index.md
+      - License: collaboration/license.md
+      - Citation: collaboration/citation.md
+      - Contributing: collaboration/contributing.md
+      - Users: collaboration/users.md
+      - Code of Conduct: collaboration/code_of_conduct.md
+    - Git:
+      - git/index.md
+    - Documentation:
+      - documentation/index.md
+    - Release:
+      - release/index.md
+  - Code Documentation:
+    - Install:
+      - install/index.md