Implemented tutorial format

.github/workflows/sphinx.yml

@@ -0,0 +1,40 @@
+name: Build documentation
+on:
+  push:
+    branches: [ create_tutorial ]
+  pull_request:
+    branches: [ create_tutorial ]
+
+permissions:
+  contents: write
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+
+    - uses: mamba-org/setup-micromamba@v1
+      with:
+        micromamba-version: '1.5.8-0' # any version from https://github.com/mamba-org/micromamba-releases
+        environment-file: docs/docs_environment.yml
+        init-shell: bash
+        cache-environment: true
+        post-cleanup: 'all'
+        generate-run-shell: false
+
+    - name: Sphinx build
+      run: |
+        sphinx-build docs _build
+      shell: bash -el {0}
+
+    - name: Deploy to GitHub Pages
+      uses: peaceiris/actions-gh-pages@v4
+      if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/create_tutorial' }}
+      with:
+        publish_branch: gh-pages
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: _build/
+        force_orphan: true

.gitignore

@@ -26,4 +26,5 @@ base/data/README.md
 *.log~1
 *.log~2
 *.log~3
+build
 %batfileMERGEWITHBASE%

base/documentation/gh-pages/README.md

@@ -0,0 +1,49 @@
+# GitHub Pages Tutorial: A Quick Start Guide for Balmorel
+
+This folder contain all necessary files for developing the Balmorel GitHub pages.
+
+
+## Purpose
+
+On the short-term: to make it easier getting started with Balmorel. 
+
+On the long-term: interlink development of Balmorel with development of documentation. I.e., by tracking markdown documents within the Balmorel repository, the process of editing documentation becomes identical to the process of editing Balmorel source code.
+
+
+## Requirements
+
+The documentation can be tested on a local machine by running:
+```bash
+sphinx-build base/documentation/gh-pages build
+```
+Then, build/index.html can be opened by, e.g., VS Code's "Go Live" extension and the website can be browsed.
+
+This requires the following python packages:
+```yaml
+name: docs_building
+channels:
+  - conda-forge
+dependencies:
+  - python=3.12
+  - myst-parser
+  - sphinx
+  - sphinx-rtd-theme
+  - sphinx-autoapi
+```
+
+## Installation instructions
+
+For more information on how to manage and install virtual python environments check out [this resource](https://docs.python.org/3/library/venv.html), or if you are a conda user, [this resource](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html).
+
+The correct virtual environment can be installed using the [provided .yaml file](base/documentation/gh-pages/docs_environment.yml) that is equal to the environments above.
+
+## Example
+
+
+## Authors 
+
+Mathias Berg Rosendal
+
+## Contribution guide
+
+Similar to developing Balmorel - create your own branch, remember to commit all small changes and create a pull request to master when a feature or tutorial section is done

base/documentation/gh-pages/about.md

@@ -0,0 +1,3 @@
+# About this code
+
+This documentation is under construction

base/documentation/gh-pages/conf.py

@@ -0,0 +1,31 @@
+project = "Balmorel"
+copyright = "2024, Mathias Berg Rosendal"
+author = "Mathias Berg Rosendal"
+release = "0.3.4"
+
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", ".testenv", ".testenv/**", "README.md"]
+
+conf_py_path = "/base/documentation/gh-pages"  # with leading and trailing slash
+
+html_static_path = ["css"]
+
+# General configurations
+extensions = [
+    "myst_parser",  # in order to use markdown
+    # "autoapi.extension",  # in order to use markdown
+]
+
+# search this directory for Python files
+# autoapi_dirs = ["../src/pybalmorel"]
+
+# ignore this file when generating API documentation
+# autoapi_ignore = ["*/conf.py"]
+
+myst_enable_extensions = [
+    "colon_fence",  # ::: can be used instead of ``` for better rendering
+]
+
+html_theme = "sphinx_rtd_theme"
+
+def setup(app):
+    app.add_css_file('css_options.css')  # may also be an URL

base/documentation/gh-pages/css/css_options.css

@@ -0,0 +1,18 @@
+/* Changing the ugly purple visited colour to remain blue or white for all links */
+/* Cross references turns grayblue */
+a[class="reference internal"]:visited {
+    color: #6a8392;
+}
+a[class="reference external"]:visited {
+    color: #6a8392;
+}
+
+/* Toctree remains white */
+div[class="wy-side-scroll"] li[class='toctree-l1'] a:visited {
+    color: white;
+}
+
+/* Home icon turns grayblue */
+ul[class="wy-breadcrumbs"] a:visited {
+    color: #6a8392;
+}

base/documentation/gh-pages/docs_environment.yml

@@ -0,0 +1,9 @@
+name: docs_building
+channels:
+  - conda-forge
+dependencies:
+  - python=3.12
+  - myst-parser
+  - sphinx
+  - sphinx-rtd-theme
+  - sphinx-autoapi

base/documentation/gh-pages/get_started.md

@@ -0,0 +1,8 @@
+# Get Started
+
+```{toctree}
+:maxdepth: 1
+
+get_started/installation.md
+get_started/examples.md
+```

base/documentation/gh-pages/get_started/examples.md

@@ -0,0 +1,2 @@
+## Examples
+How to run Balmorel

base/documentation/gh-pages/get_started/installation.md

@@ -0,0 +1,2 @@
+## Installation
+Install GAMS

base/documentation/gh-pages/index.md

@@ -0,0 +1,19 @@
+# Balmorel
+Balmorel is an energy system model. Get started [here](get_started.md).
+
+
+```{toctree}
+:maxdepth: 1
+:caption: Balmorel
+:hidden:
+
+get_started
+```
+
+```{toctree}
+:maxdepth: 1
+:caption: Reference
+:hidden:
+
+about
+```