From 5441aa371575a11ae334889aa98819767a373d52 Mon Sep 17 00:00:00 2001 From: Mathias157 Date: Tue, 17 Sep 2024 12:03:28 +0200 Subject: [PATCH] Initiated documentation template from pybalmorel --- .github/workflows/sphinx.yml | 40 ++++++++++++++++++++++++++++++++ docs/about.md | 3 +++ docs/conf.py | 31 +++++++++++++++++++++++++ docs/css/css_options.css | 18 ++++++++++++++ docs/docs_environment.yml | 9 +++++++ docs/get_started.md | 8 +++++++ docs/get_started/examples.md | 2 ++ docs/get_started/installation.md | 2 ++ docs/index.md | 19 +++++++++++++++ 9 files changed, 132 insertions(+) create mode 100644 .github/workflows/sphinx.yml create mode 100644 docs/about.md create mode 100644 docs/conf.py create mode 100644 docs/css/css_options.css create mode 100644 docs/docs_environment.yml create mode 100644 docs/get_started.md create mode 100644 docs/get_started/examples.md create mode 100644 docs/get_started/installation.md create mode 100644 docs/index.md diff --git a/.github/workflows/sphinx.yml b/.github/workflows/sphinx.yml new file mode 100644 index 0000000..8cb3059 --- /dev/null +++ b/.github/workflows/sphinx.yml @@ -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 diff --git a/docs/about.md b/docs/about.md new file mode 100644 index 0000000..1aae90a --- /dev/null +++ b/docs/about.md @@ -0,0 +1,3 @@ +# About this code + +This documentation is under construction diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..df3e546 --- /dev/null +++ b/docs/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/**"] + +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 \ No newline at end of file diff --git a/docs/css/css_options.css b/docs/css/css_options.css new file mode 100644 index 0000000..d111b7f --- /dev/null +++ b/docs/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; +} \ No newline at end of file diff --git a/docs/docs_environment.yml b/docs/docs_environment.yml new file mode 100644 index 0000000..8da439c --- /dev/null +++ b/docs/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 \ No newline at end of file diff --git a/docs/get_started.md b/docs/get_started.md new file mode 100644 index 0000000..63e7a09 --- /dev/null +++ b/docs/get_started.md @@ -0,0 +1,8 @@ +# Get Started + +```{toctree} +:maxdepth: 1 + +get_started/installation.md +get_started/examples.md +``` \ No newline at end of file diff --git a/docs/get_started/examples.md b/docs/get_started/examples.md new file mode 100644 index 0000000..b26193a --- /dev/null +++ b/docs/get_started/examples.md @@ -0,0 +1,2 @@ +## Examples +How to run Balmorel \ No newline at end of file diff --git a/docs/get_started/installation.md b/docs/get_started/installation.md new file mode 100644 index 0000000..a7f1663 --- /dev/null +++ b/docs/get_started/installation.md @@ -0,0 +1,2 @@ +## Installation +Install GAMS diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..fb38853 --- /dev/null +++ b/docs/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 +``` \ No newline at end of file