Skip to content

Commit

Permalink
Initiated documentation template from pybalmorel
Browse files Browse the repository at this point in the history
  • Loading branch information
Mathias157 committed Sep 17, 2024
1 parent d16fe27 commit 5441aa3
Show file tree
Hide file tree
Showing 9 changed files with 132 additions and 0 deletions.
40 changes: 40 additions & 0 deletions .github/workflows/sphinx.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
name: Build documentation
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]

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/main' }}
with:
publish_branch: gh-pages
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: _build/
force_orphan: true
3 changes: 3 additions & 0 deletions docs/about.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# About this code

This documentation is under construction
31 changes: 31 additions & 0 deletions docs/conf.py
Original file line number Diff line number Diff line change
@@ -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/**"]

conf_py_path = "/docs/" # 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
18 changes: 18 additions & 0 deletions docs/css/css_options.css
Original file line number Diff line number Diff line change
@@ -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;
}
9 changes: 9 additions & 0 deletions docs/docs_environment.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
name: docs_building
channels:
- conda-forge
dependencies:
- python=3.12
- myst-parser
- sphinx
- sphinx-rtd-theme
- sphinx-autoapi
8 changes: 8 additions & 0 deletions docs/get_started.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
# Get Started

```{toctree}
:maxdepth: 1
get_started/installation.md
get_started/examples.md
```
2 changes: 2 additions & 0 deletions docs/get_started/examples.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
## Examples
How to run Balmorel
2 changes: 2 additions & 0 deletions docs/get_started/installation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
## Installation
Install GAMS
19 changes: 19 additions & 0 deletions docs/index.md
Original file line number Diff line number Diff line change
@@ -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
```

0 comments on commit 5441aa3

Please sign in to comment.