initial setup for easybuild-docs, ready to start porting of documenta…

…tion from Sphinx/.rst to MkDocs/.md
easybuilders · Oct 22, 2022 · 0469129 · 0469129
1 parent 829166b
commit 0469129
Show file tree

Hide file tree

Showing 14 changed files with 775 additions and 0 deletions.
diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
@@ -0,0 +1,29 @@
+# documentation: https://help.github.com/en/articles/workflow-syntax-for-github-actions
+name: deploy EasyBuild documentation (only on push to main branch)
+on:
+  push:
+    branches: main
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - name: checkout
+      uses: actions/checkout@v3
+      with:
+          fetch-depth: 0
+
+    - name: set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.10'
+
+    - name: install mkdocs
+      run: |
+          pip install -r requirements.txt
+          mkdocs --version
+
+    - name: build tutorial
+      # can't use --strict due to warnings being produced by mkdocs-redirect plugin
+      # because we are re-directing .html pages
+      # run: mkdocs build --strict && mkdocs gh-deploy --force
+      run: mkdocs build && mkdocs gh-deploy --force
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -0,0 +1,30 @@
+# documentation: https://help.github.com/en/articles/workflow-syntax-for-github-actions
+name: test building of EasyBuild documentation
+on: [push, pull_request]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - name: checkout
+      uses: actions/checkout@v3
+
+    - name: set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.10'
+
+    - name: Codespell action
+      uses: codespell-project/actions-codespell@master
+      with:
+        check_filenames: true
+
+    - name: install mkdocs
+      run: |
+          pip install -r requirements.txt
+          mkdocs --version
+
+    - name: build tutorial
+      # can't use --strict due to warnings being produced by mkdocs-redirect plugin
+      # because we are re-directing .html pages
+      # run: mkdocs build --strict
+      run: mkdocs build
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1 @@
+site/
diff --git a/Makefile b/Makefile
@@ -0,0 +1,13 @@
+all: build
+
+build:
+	mkdocs build
+
+deploy:
+	mkdocs gh-deploy --force
+
+check test:
+	mkdocs build --strict
+
+preview:
+	mkdocs serve
diff --git a/README b/README
@@ -0,0 +1,109 @@
+# EasyBuild documentation
+
+This repository contains the *sources* of the EasyBuild documentation, which is hosted at https://docs.easybuild.io.
+
+> **Warning**
+> 
+> The sources of the EasyBuild documentation currently still reside at https://github.com/easybuilders/easybuild/tree/main/docs.
+>
+> We are actively porting the sources from [reStructuredText](https://en.wikipedia.org/wiki/ReStructuredText) format
+> to [MarkDown](https://daringfireball.net/projects/markdown) format.
+
+## Format
+
+The documentation sources are located in the [docs subdirectory](https://github.com/easybuilders/easybuild-docs/tree/main/docs).
+They are written in [MarkDown](https://daringfireball.net/projects/markdown) format, and rendered using [MkDocs](https://www.mkdocs.org),
+more specifically with [Material for MkDocs](https://squidfunk.github.io/mkdocs-material).
+
+Useful links:
+
+- The Markdown Guide: <https://www.markdownguide.org>
+- Reference guide for Material for MkDocs: <https://squidfunk.github.io/mkdocs-material/reference>
+
+## Publishing
+
+The documentation is automatically built and published to https://docs.easybuild.io on every push to the `main` branch of this repository.
+
+This is taken care of by the [`deploy` GitHub Actions workflow](https://github.com/easybuilders/easybuild-docs/tree/main/.github/workflows/deploy.yml).
+
+## Using `mkdocs`
+
+### Installing `mkdocs`
+
+To install all the required `mkdocs` Python packages, use the provided [requirements.txt](https://github.com/easybuilders/easybuild-docs/tree/main/requirements.txt) file:
+
+```
+pip install -r requirements.txt
+```
+
+### Building
+
+To build the documentation, use:
+
+```
+mkdocs build
+```
+
+or use the `Makefile` that is provided in this repository:
+
+```
+make
+```
+
+### Testing
+
+To test whether the documentation is building correctly, and whether all (internal) links are correct, use:
+
+```
+mkdocs build --strict
+```
+
+or
+
+```
+make test
+```
+
+These commands will exit with a non-zero exit code if `mkdocs` produces any errors or warnings.
+
+### Previewing
+
+To see a local preview of the rendered documentation in your browser, use
+
+```
+mkdocs serve
+```
+
+or
+
+```
+make preview
+```
+
+and click the link that is provided, for example:
+
+```
+INFO     -  Documentation built in 0.24 seconds
+INFO     -  [17:52:07] Watching paths for changes: 'docs', 'mkdocs.yml'
+INFO     -  [17:52:07] Serving on http://127.0.0.1:8000/
+```
+
+This preview of the rendered documentation will automatically refresh when the documentation sources are updated!
+
+
+## Contributing
+
+To contribute to the EasyBuild documentation, you should make a pull request to the `main` branch.
+
+For example:
+
+```
+git clone [email protected]:easybuilders/easybuild-docs.git
+cd easybuild-docs
+git remote add example_fork [email protected]:example/easybuild-docs.git
+git checkout -b example_branch
+git add docs/example.md
+git commit -m "this is just an example"
+git push example_fork example_branch
+# then go to https://github.com/easybuilders/easybuild-docs and open the pull request
+```
diff --git a/docs/configuring_easybuild.md b/docs/configuring_easybuild.md
@@ -0,0 +1,14 @@
+# Configuring EasyBuild
+
+!!! warning
+    This page will soon replace <https://docs.easybuild.io/en/latest/Configuration.html>.
+
+    **
+    It still needs to be ported from *reStructuredText* (.rst) to *MarkDown* (.md),  
+    and you can help with that!
+    **
+
+    - source: [`docs/Configuration.rst` in `easybuilders/easybuild` repo](https://raw.githubusercontent.com/easybuilders/easybuild/develop/docs/Configuration.rst)
+    - target: [`docs/configuring_easybuild.md` in `easybuilders/easybuild-docs` repo](https://github.com/easybuilders/easybuild-docs/tree/main/docs/configuring_easybuild.md)
+
+    See <https://github.com/easybuilders/easybuild-docs> for more information.
diff --git a/docs/easybuild_terminology.md b/docs/easybuild_terminology.md
@@ -0,0 +1,14 @@
+# EasyBuild terminology
+
+!!! warning
+    This page will soon replace <https://docs.easybuild.io/en/latest/Concepts_and_Terminology.html>.
+
+    **
+    It still needs to be ported from *reStructuredText* (.rst) to *MarkDown* (.md),  
+    and you can help with that!
+    **
+
+    - source: [`docs/Concepts_and_Terminology.rst` in `easybuilders/easybuild` repo](https://raw.githubusercontent.com/easybuilders/easybuild/develop/docs/Concepts_and_Terminology.rst)
+    - target: [`docs/easybuild_terminology.md` in `easybuilders/easybuild-docs` repo](https://github.com/easybuilders/easybuild-docs/tree/main/docs/easybuild_terminology.md)
+
+    See <https://github.com/easybuilders/easybuild-docs> for more information.
diff --git a/docs/img/easybuild_logo.png b/docs/img/easybuild_logo.png
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,22 @@
+# Welcome to the EasyBuild documentation!
+
+!!! warning
+    This is the new EasyBuild documentation,
+    made with [Material for MkDocs](https://squidfunk.github.io/mkdocs-material)
+    and written in [MarkDown](https://daringfireball.net/projects/markdown).
+
+    We intend to replace the <https://docs.easybuild.io>,
+    which is made with [Sphinx](https://www.sphinx-doc.org)
+    and written in [reStructuredText](https://en.wikipedia.org/wiki/ReStructuredText)
+    with this documentation soon...
+
+    **
+    If you want to help with porting the EasyBuild documentation to MarkDown, you can!  
+    Please see <https://github.com/easybuilders/easybuild-docs>.
+    **
+
+## Getting started
+
+- [What is EasyBuild?](what_is_easybuild.md)
+- [EasyBuild terminology](easybuild_terminology.md)
+- [Installing](installing_easybuild.md) and [configuring](configuring_easybuild.md) EasyBuild
diff --git a/docs/installing_easybuild.md b/docs/installing_easybuild.md
@@ -0,0 +1,14 @@
+# Installing EasyBuild
+
+!!! warning
+    This page will soon replace <https://docs.easybuild.io/en/latest/Installation.html>.
+
+    **
+    It still needs to be ported from *reStructuredText* (.rst) to *MarkDown* (.md),  
+    and you can help with that!
+    **
+
+    - source: [`docs/Concepts_and_Terminology.rst` in `easybuilders/easybuild` repo](https://raw.githubusercontent.com/easybuilders/easybuild/develop/docs/Installation.rst)
+    - target: [`docs/installing_easybuild.md` in `easybuilders/easybuild-docs` repo](https://github.com/easybuilders/easybuild-docs/tree/main/docs/installing_easybuild.md)
+
+    See <https://github.com/easybuilders/easybuild-docs> for more information.
diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css
@@ -0,0 +1,129 @@
+/*
+ * Custom EasyBuild color scheme for Material for MkDocs,
+ * derived from default dark mode color scheme 'slate'.
+*/
+[data-md-color-scheme="easybuild"] {
+  /* hue (in range [0,360]) */
+  --md-hue: 232;
+
+  --md-default-fg-color:             hsla(var(--md-hue), 75%, 95%, 1);
+  --md-default-fg-color--light:      hsla(var(--md-hue), 75%, 90%, 0.62);
+  --md-default-fg-color--lighter:    hsla(var(--md-hue), 75%, 90%, 0.32);
+  --md-default-fg-color--lightest:   hsla(var(--md-hue), 75%, 90%, 0.12);
+
+  --md-default-bg-color:             #2F343F; /*hsla(var(--md-hue), 15%, 21%, 1);*/
+  --md-default-bg-color--light:      hsla(var(--md-hue), 15%, 21%, 0.54);
+  --md-default-bg-color--lighter:    hsla(var(--md-hue), 15%, 21%, 0.26);
+  --md-default-bg-color--lightest:   hsla(var(--md-hue), 15%, 21%, 0.07);
+
+  /* --md-primary-fg-color:        #3E70E4;  /* blue from original EasyBuild logo */
+  --md-primary-fg-color:        #94BDCF;  /* blue from new EasyBuild logo */
+  /* --md-primary-fg-color--light: #44932B;  /* green from original EasyBuild logo */
+  --md-primary-fg-color--light: #A8BD90;  /* green from new EasyBuild logo */
+  /* --md-primary-fg-color--dark:  #A5241E;  /* red from original EasyBuild logo */
+  --md-primary-fg-color--dark:  #B2666C;  /* red from new EasyBuild logo */
+
+  /* Code color shades */
+  --md-code-fg-color:                hsla(var(--md-hue), 18%, 86%, 1);
+  --md-code-bg-color:                hsla(var(--md-hue), 15%, 15%, 1);
+
+  /* Code highlighting color shades */
+  --md-code-hl-color:                hsla(#{hex2hsl($clr-blue-a200)}, 0.15);
+  --md-code-hl-number-color:         hsla(6, 74%, 63%, 1);
+  --md-code-hl-special-color:        hsla(340, 83%, 66%, 1);
+  --md-code-hl-function-color:       hsla(291, 57%, 65%, 1);
+  --md-code-hl-constant-color:       hsla(250, 62%, 70%, 1);
+  --md-code-hl-keyword-color:        hsla(219, 66%, 64%, 1);
+  --md-code-hl-string-color:         hsla(150, 58%, 44%, 1);
+  --md-code-hl-name-color:           var(--md-code-fg-color);
+  --md-code-hl-operator-color:       var(--md-default-fg-color--light);
+  --md-code-hl-punctuation-color:    var(--md-default-fg-color--light);
+  --md-code-hl-comment-color:        var(--md-default-fg-color--light);
+  --md-code-hl-generic-color:        var(--md-default-fg-color--light);
+  --md-code-hl-variable-color:       var(--md-default-fg-color--light);
+
+  /* Typeset color shades */
+  --md-typeset-color:                var(--md-default-fg-color);
+
+  /* Typeset `a` color shades */
+  --md-typeset-a-color:              var(--md-primary-fg-color);
+
+  /* Typeset `mark` color shades */
+  --md-typeset-mark-color:           hsla(#{hex2hsl($clr-blue-a200)}, 0.3);
+
+  /* Typeset `kbd` color shades */
+  --md-typeset-kbd-color:            hsla(var(--md-hue), 15%, 94%, 0.12);
+  --md-typeset-kbd-accent-color:     hsla(var(--md-hue), 15%, 94%, 0.2);
+  --md-typeset-kbd-border-color:     hsla(var(--md-hue), 15%, 14%, 1);
+
+  /* Typeset `table` color shades */
+  --md-typeset-table-color:          hsla(var(--md-hue), 75%, 95%, 0.12);
+
+  /* Admonition color shades */
+  --md-admonition-fg-color:          var(--md-default-fg-color);
+  --md-admonition-bg-color:          var(--md-default-bg-color);
+
+  /* Footer color shades */
+  --md-footer-bg-color:              hsla(var(--md-hue), 15%, 12%, 0.87);
+  --md-footer-bg-color--dark:        hsla(var(--md-hue), 15%, 10%, 1);
+
+  /* Shadow depth 1 */
+  --md-shadow-z1:
+    0 #{px2rem(4px)} #{px2rem(10px)} hsla(0, 0%, 0%, 0.2),
+    0 0              #{px2rem(1px)}  hsla(0, 0%, 0%, 0.1);
+
+  /* Shadow depth 2 */
+  --md-shadow-z2:
+    0 #{px2rem(4px)} #{px2rem(10px)} hsla(0, 0%, 0%, 0.3),
+    0 0              #{px2rem(1px)}  hsla(0, 0%, 0%, 0.25);
+
+  /* Shadow depth 3 */
+  --md-shadow-z3:
+    0 #{px2rem(4px)} #{px2rem(10px)} hsla(0, 0%, 0%, 0.4),
+    0 0              #{px2rem(1px)}  hsla(0, 0%, 0%, 0.35);
+
+  /* Hide images for light mode */
+  img[src$="#only-light"],
+  img[src$="#gh-light-mode-only"] {
+    display: none;
+  }
+
+  /* Show images for dark mode */
+  img[src$="#only-dark"],
+  img[src$="#gh-dark-mode-only"] {
+    display: initial;
+  }
+}
+
+/* -------------------------------------------------------------------------- */
+
+/* Adjust link colors for dark primary colors */
+@each $name, $color in (
+  "pink":                            hsl(340, 81%, 63%),
+  "purple":                          hsl(291, 43%, 63%),
+  "deep-purple":                     hsl(262, 63%, 70%),
+  "indigo":                          hsl(219, 56%, 63%),
+  "teal":                            hsl(174, 100%, 40%),
+  "green":                           hsl(122, 39%, 60%),
+  "deep-orange":                     hsl(14, 100%, 73%),
+  "brown":                           hsl(16, 45%, 60%),
+
+  // Set neutral colors to indigo
+  "grey":                            hsl(219, 56%, 63%),
+  "blue-grey":                       hsl(219, 56%, 63%),
+  "white":                           hsl(219, 56%, 63%),
+  "black":                           hsl(219, 56%, 63%)
+) {
+  [data-md-color-scheme="slate"][data-md-color-primary="#{$name}"] {
+    --md-typeset-a-color: #{$color};
+  }
+}
+
+/* -------------------------------------------------------------------------- */
+
+/* Switching in progress - disable all transitions temporarily */
+[data-md-color-switching] *,
+[data-md-color-switching] *::before,
+[data-md-color-switching] *::after {
+  transition-duration: 0ms !important; // stylelint-disable-line
+}
diff --git a/docs/what_is_easybuild.md b/docs/what_is_easybuild.md
@@ -0,0 +1,14 @@
+# What is EasyBuild?
+
+!!! warning
+    This page will soon replace <https://docs.easybuild.io/en/latest/Introduction.html>.
+
+    **
+    It still needs to be ported from *reStructuredText* (.rst) to *MarkDown* (.md),  
+    and you can help with that!
+    **
+
+    - source: [`docs/Introduction.rst` in `easybuilders/easybuild` repo](https://raw.githubusercontent.com/easybuilders/easybuild/develop/docs/Introduction.rst)
+    - target: [`docs/what_is_easybuild.md` in `easybuilders/easybuild-docs` repo](https://github.com/easybuilders/easybuild-docs/tree/main/docs/what_is_easybuild.md)
+
+    See <https://github.com/easybuilders/easybuild-docs> for more information.