Merge pull request #334 from hpcleuven/pydata

Switch to new design with PyData theme

.readthedocs.yaml

@@ -1,6 +1,25 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
 version: 2
 
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+# Build documentation in the "source/" directory with Sphinx
+sphinx:
+  builder: html
+  configuration: source/conf.py
+  fail_on_warning: true
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
 python:
-     version: 3.8
-     install:
-          - requirements: requirements.txt
+  install:
+  - requirements: requirements.txt

Makefile

@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
+SPHINXOPTS    = -W
 SPHINXBUILD   = sphinx-build
 SPHINXAUTOBUILD   = sphinx-autobuild
 SOURCEDIR     = source

README.md

@@ -1,104 +1,118 @@
 # VscDocumentation
 
-This repository contains user-level documentation for the VSC infrastructure.  It is deployed on [ReadTheDocs](https://vlaams-supercomputing-centrum-vscdocumentation.readthedocs-hosted.com/en/latest/).
+Repository of the [VSC documentation website](https://docs.vscentrum.be).
 
-When a commit is done on the repository's master branch, the documentation is rebuilt automatically on ReadTheDocs, and is immediately live.  Hence you may prefer to work on a branch for major updates.
+## How to contribute?
 
-## Prerequisites
+Improving the documentation is quite simple, all documents can be edited with a
+simple text editor. You standard workflow to contribute changes is:
+
+1. Clone this repository
+2. Make corrections/improvements to any document
+3. Push you changed to a new branch
+4. Open a pull request to the `master` branch of this repo
+
+⚠️ Follow our [style guide](styleguide.md) to edit the VSC documentation.
+
+## What is the status of improvements/fixes?
+
+Feel free to open issues to get fixes or improvements on the agenda.  To get an
+overview of work that is planned or in progress, check out the [project
+overview](https://github.com/hpcleuven/VscDocumentation/projects/1).
+
+## Workflow
+
+### Prerequisites
 
 You will need to clone the repository, i.e.,
 ```bash
 $ git clone [email protected]:hpcleuven/VscDocumentation.git
-$ cd VscDocumentation
-$ git fetch origin development:development
 ```
 
-Your life will be substantially easier if you can preview your changes locally.  A conda environment has be defined to install all the required software
+Your life will be substantially easier if you can preview your changes locally.
+Install the required packages in a self-contained environment such a Python
+virtual environment (*venv*) or Conda.
+
+#### Python venv
 
-Downloads and installation instructions for Miniconda can be found on [conda's website](https://docs.conda.io/en/latest/miniconda.html).
+All required Python modules can be easily installed in a Python virtual
+environment using the `requirements.txt` file in this repo
 
-The YAML environment description file is [``sphinx.yml``](sphinx.yml).  The environment can be created using
 ```bash
-$ conda env create -f environment.yml
+$ python -m venv /path/to/new/venv
+$ source /path/to/new/venv/bin/activate
+$ cd VscDocumentation
+$ python -m pip install -r requirements.txt
 ```
 
-## What is the status of improvements/fixes?
+#### Conda
 
-Feel free to open issues to get fixes or improvements on the agenda.  To get an overview of work that is planned or in progress, check out the [project overview](https://github.com/hpcleuven/VscDocumentation/projects/1).
+A conda environment has be defined to install all the required software
 
+Downloads and installation instructions for Miniconda can be found on [conda's
+website](https://docs.conda.io/en/latest/miniconda.html).
 
-## Workflow
+The YAML environment description file is [``sphinx.yml``](sphinx.yml).  The
+environment can be created using
 
-### Activate the environment
+```bash
+$ conda env create -f environment.yml
+```
+
+The `sphinx` environment can be activated by
 
-The ``sphinx`` environment can be activated by
 ```bash
 $ source activate sphinx
 ```
 
-
 ### Creating a feature branch
 
-Do not make changes in the master or development branch directly, but create feature/bugfix branches as required, e.g.,
+Do not make changes in the `master` or `development` branches directly. Create
+your own feature/bugfix branch as needed.
+
 ```bash
-$ git checkout development
+$ cd VscDocumentation
+$ git checkout master
 $ git checkout -b feature/new_stuff
 ```
 
-Note that at any given time, we should be able to merge the development branch into the master branch, and rebuild the documentation, hence the development branch should always be in a sane state.
-
-Exception on feature/bugfix branches: use common sense, to fix a simple typo, it is likely better to do that directly in the development branch, and merge that immediately into master.
-
-
 ### Running a local sphinx server
 
-The repository contains a make file that has a target to run the sphinx server.  The latter will monitor the ``source`` directory for changes, and serve the documentation to a web browser that is opened automatically.
+The repository contains a make file that has a target to run the sphinx server.
+The latter will monitor the `source` directory for changes, and serve the
+documentation to a web browser that is opened automatically.
+
 ```bash
 $ make web
 ```
 
-
 ### Edit content
 
-You can now edit the content to your heart's content, making commits to your feature branch as you go.  You can push your feature branch to the Github repository whenever you like.
+You can now edit the content to your heart's content, making commits to your
+feature branch as you go. You can push your feature branch to the Github
+repository whenever you like.
+
 ```bash
+$ git add source/some_documentation_file.rst
+$ git commit -m "some new stuff added to VSC docs"
 $ git push origin feature/new_stuff
 ```
 
-
 ### Pull request
 
-When you are done, create a pull request on GitHub.  For consistency, do the pull request to the development branch, not the master branch.
+When you are done, create a pull request to the `master` branch of this
+repository on GitHub.
 
-For major changes, it is good practice to ask others to review your pull request.  Although this policy is encouraged, it is not enforced.
+Changes to the documentation require the positive review from the documentation
+maintainers of your pull request. Pay attention to the review in case there
+would be remarks to address.
+
+Once the pull request has been merged, the branch will be deleted from GitHub.
+At this point, all that is left to do is delete your local feature branch.
 
-Once the pull request has been merged, the branch will be deleted from GitHub.  For your own convenience, it is probably easiest to pull the master and development branches from GitHub,
-and remove the local feature branch, e.g.,
 ```bash
+$ git fetch origin
 $ git checkout master
-$ git pull
-$ git checkout development
-$ git pull origin development
+$ git pull origin master
 $ git branch -d feature/new_stuff
 ```
-
-
-## Repository structure
-
-1. source: directory containing the source to be rendered into HTML (e.g., rST and PNG files).
-1. images: directory containing source documents for images (e.g., ODG files).
-1. Makefile & make.bat: make files to render the documentation, and run a local web server.
-1. sphinx.yml: conda environment definition.
-
-The other files and directories are part of the migration, and may be removed at some
-later stage.
-
-
-## Documentation usage
-
-Note that ReadTheDocs has a very convenient feature.  It lets you copy an URL
-to a (sub)section of the documentation to make it easy to refer via email.  Simply
-copy the link represented by the paragraph icon that appears next to the (sub)section
- title when you hover near it.
-
-![copy documentation link](img/links.png)

requirements.txt

@@ -1,28 +1,39 @@
+accessible-pygments==0.0.3
 alabaster==0.7.12
-Babel==2.9.1
-certifi==2022.12.7
-charset-normalizer==2.0.7
-colorama==0.4.4
-docutils==0.17.1
-idna==3.3
-imagesize==1.3.0
-Jinja2==3.0.3
+Babel==2.11.0
+beautifulsoup4==4.11.1
+certifi==2023.7.22
+charset-normalizer==2.1.1
+colorama==0.4.6
+docutils==0.19
+idna==3.4
+imagesize==1.4.1
+importlib-metadata==5.0.0
+Jinja2==3.1.2
 livereload==2.6.3
-MarkupSafe==2.0.1
-packaging==21.2
-Pygments==2.10.0
-pyparsing==2.4.7
-pytz==2021.3
-requests==2.31.0
+MarkupSafe==2.1.1
+myst-parser==1.0.0
+packaging==21.3
+pydata-sphinx-theme==0.13.3
+Pygments==2.15.0
+pyparsing==3.0.9
+pytz==2022.6
+requests==2.28.1
 six==1.16.0
 snowballstemmer==2.2.0
-Sphinx==4.3.0
+soupsieve==2.3.2.post1
+Sphinx==5.3.0
 sphinx-autobuild==2021.3.14
+sphinx-notfound-page==0.8.3
+sphinx-reredirects==0.1.2
+sphinx_design==0.3.0
 sphinxcontrib-applehelp==1.0.2
 sphinxcontrib-devhelp==1.0.2
 sphinxcontrib-htmlhelp==2.0.0
 sphinxcontrib-jsmath==1.0.1
 sphinxcontrib-qthelp==1.0.3
 sphinxcontrib-serializinghtml==1.1.5
 tornado==6.3.2
-urllib3==1.26.7
+typing_extensions==4.5.0
+urllib3==1.26.12
+zipp==3.10.0

source/_static/css/vsc.css

@@ -0,0 +1,76 @@
+html[data-theme="light"] {
+    --pst-color-primary: #d96c31;  /* VSC orange */
+    --pst-color-link: #40807D;  /* dark teal (complementary) */
+    --pst-color-link-hover: #f28e24;  /* VSC secondary orange */
+    --pst-color-background: #ffffff;  /* actual white */
+    --pst-color-on-background: #f9f9f9;  /* lighter VSC white */
+    --pst-color-surface: #f5f5f5;  /* cards background */
+    --pst-color-border: #dbdbdb;
+    --sd-color-card-border-hover: var(--pst-color-link-hover);
+}
+
+html[data-theme="dark"] {
+    --pst-color-primary: #f28e24;  /* VSC secondary orange */
+    --pst-color-link: #90f2f2;  /* light teal (complementary) */
+    --pst-color-link-hover: #f9bf19;
+    --pst-color-background: #282828;  /* darker VSC black */
+    --pst-color-on-background: #383839;  /* VSC black */
+    --pst-color-surface: #303030;  /* cards background */
+    --pst-color-border: #4e4e4e;
+    --sd-color-card-border-hover: var(--pst-color-link-hover);
+}
+
+/* background gradients */
+html[data-theme="light"] .bd-sidebar-primary {
+    background-color: #fcf1dd;  /* very light VSC yellow */
+}
+html[data-theme="light"] .bd-content {
+    background-color: var(--pst-color-background);
+}
+@media (min-width: 960px) {
+    html[data-theme="light"] .bd-container {
+        background: var(--pst-color-background);
+        /* light VSC yellow: #f8e2bb */
+        background: linear-gradient(90deg, rgb(255, 255, 255) 0%, rgb(248, 226, 187) 50%, rgb(255, 255, 255) 80%, rgb(255, 255, 255) 100%)
+    }
+    html[data-theme="light"] .bd-sidebar-primary {
+        background-color: transparent;
+    }
+}
+
+html[data-theme="dark"] .bd-sidebar-primary {
+    background-color: #3c2c28;  /* very dark VSC brick */
+}
+html[data-theme="dark"] .bd-content {
+    background-color: var(--pst-color-background);
+}
+@media (min-width: 960px) {
+    html[data-theme="dark"] .bd-container {
+        background: var(--pst-color-background);
+        /* dark VSC brick: #673527 */
+        background: linear-gradient(90deg, rgb(40, 40, 40) 0%, rgb(76, 39, 29) 50%, rgb(40, 40, 40) 80%, rgb(40, 40, 40) 100%)
+    }
+    html[data-theme="dark"] .bd-sidebar-primary {
+        background-color: transparent;
+    }
+}
+
+/* toctree format */
+.toctree-wrapper .toctree-l1 {
+    font-size: 1.2rem;
+    font-weight: bold;
+}
+.toctree-wrapper .toctree-l2 {
+    font-size: 1.0rem;
+    font-weight: normal;
+}
+
+/* make sphinx-design cards slightly non-transparent */
+.sd-card {
+    background-color: var(--pst-color-surface);
+}
+
+/* line numbers in codeblocks on transparent column */
+html[data-theme="light"] .highlight span.linenos { background-color: transparent; }
+html[data-theme="dark"] .highlight span.linenos { background-color: transparent; }
+

source/_templates/404.html

@@ -0,0 +1,35 @@
+<!-- Template for custom 404 error landing page -->
+<!-- author: Alex Domingo (Vrije Universiteit Brussel) -->
+{%- extends "layout.html" %}
+
+{% block body %}
+
+<h1><i class="fas fa-exclamation-triangle"></i> Page not found</h1>
+<p>The requested page does not exist. Please check the site map below or use the search tool in the left sidebar.</p>
+
+<nav id="notfound-nav" aria-label="{{ _('Main navigation') }}">
+  <div class="notfound-map">
+    <h2><i class="fas fa-map"></i> Site Map</h2>
+    {{ generate_toctree_html(
+        "raw",
+        startdepth=0,
+        maxdepth=3,
+        collapse=False,
+        includehidden=True,
+        titles_only=True
+    ) }}
+  </div>
+</nav>
+
+<script type="text/javascript">
+    function linktoplogo() {
+        // fix link in top logo, the notfound.extension does not cover it
+        // because it is specific of the pydata theme
+        var toplogo = document.getElementById("navbar-start");
+        var toplink = toplogo.getElementsByTagName("A")[0];
+        toplink.href = '/';
+    }
+    document.addEventListener("DOMContentLoaded", linktoplogo);
+</script>
+
+{% endblock %}

source/_templates/sidebar-links.html

@@ -0,0 +1,19 @@
+<!-- Sidebar panel with links to other institutions/services that are related to us -->
+<div style="padding:2em">
+<!--
+    <p>
+        <a href="https://www.vscentrum.be/"><img src="{{ pathto('_static/vsc-logo-2.png', 1) }}" /></a>
+    </p>
+-->
+    <h3>Need Help?</h3>
+    <p>
+       <a href="https://www.vscentrum.be/getintouch"><i class="fas fa-comments"></i> Get in touch with our team</a>
+    </p>
+<!--
+    <h3>Supported by</h3>
+    <p>
+        <a href="https://www.fwo.be" style="margin:1em"><img src="{{ pathto('_static/fwo-logo.jpg', 1) }}" style="width:40%"/></a>
+        <a href="https://prace-ri.eu/" style="margin:1em"><img src="{{ pathto('_static/prace-logo.png', 1) }}" style="width:40%"/></a>
+    </p>
+-->
+</div>