Merge pull request #184 from OpenEnergyPlatform/feature-118-mkdocs

Add basic documentation with MKdocs

.github/workflows/gh-pages.yml

@@ -0,0 +1,21 @@
+name: gh-pages
+on:
+  push:
+    branches:
+      - feature-120-repo
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+      - uses: actions/cache@v2
+        with:
+          key: ${{ github.ref }}
+          path: .cache
+      - run: pip install --upgrade -r requirements.txt
+      - run: mkdocs gh-deploy --force

CHANGELOG.md

@@ -49,6 +49,7 @@ Here is a template for new release sections
 - Add key topics to general [(#170)](https://github.com/OpenEnergyPlatform/oemetadata/pull/170)
 - Add badge labels to documentation [(#175)](https://github.com/OpenEnergyPlatform/oemetadata/pull/175)
 - Implement schema build system v1: Enhance the resolve and generation module [(#180)](https://github.com/OpenEnergyPlatform/oemetadata/pull/180)
+- Add basic documentation with MKdocs [(#184)](https://github.com/OpenEnergyPlatform/oemetadata/pull/184)
 
 ### Changed
 - Remove comment field as it holds information on how to fill out the metadata and therefore should not be part of the actual oemetadata but the documentation. [#105](https://github.com/OpenEnergyPlatform/oemetadata/pull/105)

docs/code/index.md

@@ -0,0 +1,7 @@
+# Functions
+
+!!! note "mkdocstrings"
+    This software uses [mkdocstings](https://github.com/mkdocstrings/mkdocstrings) to render docstrings from files.
+
+The code documentation is implemented by writing docstrings. <br>
+See the [mkdocstrings documentation](https://mkdocstrings.github.io/).

docs/code/install/index.md

@@ -0,0 +1,7 @@
+# Install
+
+- requirements.txt
+- requirements_dev.txt
+- environment.yml
+- setup.py
+- pyproject.toml

docs/code/style/index.md

@@ -0,0 +1,6 @@
+# Code Style 
+!!! note "Common python styles"
+    - Pep8
+    - https://google.github.io/styleguide/pyguide.html
+
+TBD

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; */
+  }

docs/development/collaboration/citation.md

@@ -0,0 +1,3 @@
+# Citation
+
+See the *Cite this repository* function or [CITATION.cff](https://github.com/OpenEnergyPlatform/oemetadata/blob/develop/CITATION.cff) for citation of this repository.

docs/development/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/OpenEnergyPlatform/oemetadata/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.

docs/development/collaboration/contributing.md

@@ -0,0 +1,7 @@
+# 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/OpenEnergyPlatform/oemetadata/blob/master/CONTRIBUTING.md).
+

docs/development/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.

docs/development/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/OpenEnergyPlatform/oemetadata/blob/production/LICENSE).

docs/development/collaboration/users.md

@@ -0,0 +1,3 @@
+# Users
+
+Known user of this software can be added to [USERS.cff](https://github.com/OpenEnergyPlatform/oemetadata/blob/production/USERS.cff) for reference.

docs/development/documentation/index.md

@@ -0,0 +1,36 @@
+# Documentation
+
+- README.rst
+- CHANGELOG.md
+- docs/
+- MkDocs
+- mkdocstrings
+
+
+## MkDocs
+[MkDocs](https://www.mkdocs.org/) is a fast and simple static site generator that is used for documentation. <br>
+The source files are written in Markdown, and configured with a single YAML configuration file `mkdocs.yml`. <br>
+[Material theme](https://squidfunk.github.io/mkdocs-material/) enables 
+additional features and an elegant design.
+
+### Install
+Install the required packages in a python environment. <br>
+`pip install mkdocs` install MkDocs <br>
+`pip install mkdocs-material` install the material theme
+
+### Build
+Generate the documentation. <br>
+`mkdocs serve` start the local live version of the documentation <br>
+`mkdocs build` create a folder `site` with the documentation
+
+### Publish
+
+#### Manually
+Publish documentation on **GitHub Pages**. <br>
+`mkdocs gh-deploy` manually deploys the documentation files
+
+#### GitHub Action
+Deploy the documentation with **GitHub Actions**. <br>
+The file `.github\workflows\gh-pages.yml` creates an automated GitHub workflow. <br>
+It is configured to be pushed to the branch `gh-page` and then deployed online. <br>
+A commit on the `production` branch triggers the workflow. 

docs/development/git/gitignore.md

@@ -0,0 +1,4 @@
+# Gitignore
+
+Copied from [A collection of useful .gitignore templates](https://github.com/github/gitignore). <br>
+For more information about `.gitignore` files, see the [Ignoring Files chapter](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring) of the Pro Git book.

docs/development/git/index.md

@@ -0,0 +1,10 @@
+# Git
+
+- .gitignore
+
+Copied from (A collection of useful .gitignore templates)[https://github.com/github/gitignore]. <br>
+For more information about how `.gitignore` files work, and how to use them, see (Ignoring Files chapter)[https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring] of the Pro Git book.
+
+- issue_template
+- pull_request_template
+- workflows (testing)

docs/development/release/index.md

@@ -0,0 +1,6 @@
+# Release
+
+- RELEASE_PROCEDURE.md
+- VERSION
+- MANIFEST.in
+- .bumpversion.cfg

docs/index.md

@@ -0,0 +1,18 @@
+---
+hide:
+  - footer
+  - toc
+---
+
+# Welcome to the Documentation of the Open Energy Metadata 
+
+## Open Energy Metadata 
+
+Open Energy Metadata (OEMetadata) is an energy metadata standard including a template, examples and a metadata schema. <br>
+It is an extensive set of metadata based on the tabular data package specifications and the FAIR principles. <br>
+The metadata contains multiple fields (keys) in a nested JSON structure.
+
+## Documentation Structure
+
+The documentation is separated into two main sections: 
+`Development` and `Metadata Documentation`. <br>

docs/metadata/index.md

@@ -0,0 +1,7 @@
+# Metadata Documentation
+
+The OEMetadata contains the following files:
+
+- `metadata_key_description.md` contains a full description of each metadata key.
+- `template.json` contains an empty metadata string with all fields.
+- `example.json` contains a basic metadata example.