Migrate to mkdocs (#851)

Co-authored-by: Sergio <sergio.garcia.de.la.cruz@cern.ch>
alisw · Jun 19, 2024 · 2a473d2 · 2a473d2
1 parent c3c43bc
commit 2a473d2
Show file tree

Hide file tree

Showing 26 changed files with 77 additions and 605 deletions.
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
@@ -0,0 +1,30 @@
+name: Documentation
+on:
+  push:
+    branches:
+      - master 
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: |
+          pip install mkdocs-material 
+          cd docs
+          mkdocs gh-deploy --force # Always keep in sync with master branch
diff --git a/.github/workflows/pr-check.yml b/.github/workflows/pr-check.yml
@@ -123,18 +123,3 @@ jobs:
 
       - name: Run linters
         run: tox -e lint
-
-  documentation:
-    name: documentation
-    runs-on: ubuntu-latest
-    container:
-      image: jekyll/jekyll
-
-    steps:
-      - uses: actions/checkout@v3
-
-      - name: Test documentation
-        run: |
-          chmod -R a+rwX .
-          jekyll build -s docs -d _site --baseurl .
-          script/custom_htmlproofer.rb
diff --git a/docs/README.md b/docs/README.md
@@ -1 +1 @@
-Documentation migrated to <http://alisw.github.io/alibuild/>
+Read the documentation here: <http://alisw.github.io/alibuild/>
diff --git a/docs/_config.yml b/docs/_config.yml
diff --git a/docs/_includes/section_toc.html b/docs/_includes/section_toc.html
diff --git a/docs/_layouts/main.html b/docs/_layouts/main.html
diff --git a/docs/_layouts/redirect.html b/docs/_layouts/redirect.html
diff --git a/docs/css/bootstrap-theme.min.css b/docs/css/bootstrap-theme.min.css
diff --git a/docs/css/bootstrap.min.css b/docs/css/bootstrap.min.css
diff --git a/docs/css/pure-min.css b/docs/css/pure-min.css
diff --git a/docs/deps.png → docs/docs/deps.png b/docs/deps.png → docs/docs/deps.png
diff --git a/docs/index.markdown → docs/docs/index.md b/docs/index.markdown → docs/docs/index.md
@@ -1,5 +1,4 @@
 ---
-title: ALIBUILD
 subtile: About this tool
 layout: main
 ---
@@ -28,44 +27,47 @@ Then, build ALICE's software with:
     aliBuild build O2Physics
 
 For a more verbose documentation of what is happening have a look at
-the [quickstart guide](quick.html). See the [user guide](user.html)
+the [quickstart guide](quick.md). See the [user guide](user.md)
 for more command line options or have a look at the [troubleshooting
-pages](troubleshooting.html) for hints on how to debug build errors.
-Have a look at the [reference guide](reference.html) if you want to
+pages](troubleshooting.md) for hints on how to debug build errors.
+Have a look at the [reference guide](reference.md) if you want to
 package your own software.
 
-<div class="pure-g">
-    <div class="pure-u-1-3"><h3>Simple build recipes</h3>
+<div style="display:grid;
+  grid-template-columns: repeat(3,1fr);  /* 3 columns */
+  grid-template-rows: repeat(2,1fr); /* 2 rows  */
+  grid-gap:50px 30px;
+
+">
+    <div><h2>Simple build recipes</h2>
       Build recipes are simple bash scripts with a YAML header. Whenever
       a dependency or a package changes only what is affected by the
       change is rebuilt.
       <br/><a href="reference.html">Read more</a>
     </div>
-    <div class="pure-u-1-3"><h3>Reuses system tools</h3>
+    <div><h2>Reuses system tools</h2>
       If desired, aliBuild will do its best to reuse what is available
       on the system, if compatible to what is found in the recipe.
       <br/><a href="user.html#controlling-which-system-packages-are-picked-up">Read more</a>
     </div>
-    <div class="pure-u-1-3"><h3>Docker support</h3>
+    <div><h2>Docker support</h2>
       aliBuild allows builds to happen inside a docker container, so
       that you can develop on Mac and build on your production Linux
       platform.
       <br/><a href="user.html#running-in-docker">Read more</a>
     </div>
-</div>
-<div class="pure-g">
-    <div class="pure-u-1-3"><h3>Binary packages</h3>
+    <div><h2>Binary packages</h2>
       aliBuild provides the ability to reuse binary packages which were
       previously centrally built, when they match the one that would be
       built locally.
       <br/><a href="user.html#using-precompiled-packages">Read more</a>
     </div>
-    <div class="pure-u-1-3"><h3>Developer mode</h3>
+    <div><h2>Developer mode</h2>
       Besides building and packaging your dependencies, aliBuild
       provides you the ability to develop those via a simple git clone.
       <br/><a href="user.html#developing-packages-locally">Read more</a>
     </div>
-    <div class="pure-u-1-3"><h3>Integrates with modules</h3>
+    <div><h2>Integrates with modules</h2>
       Easily setup your work environment using `alienv`, which is based on
       standard <a href="http://modules.sourceforge.net">modulefiles</a>.
       <br/><a href="quick.html#loading-the-package-environment">Read more</a>

diff --git a/docs/o2-tutorial.markdown → docs/docs/o2-tutorial.md b/docs/o2-tutorial.markdown → docs/docs/o2-tutorial.md
@@ -1,5 +1,4 @@
 ---
-title: ALIBUILD
 subtitle: O2 build tutorial
 dest_url: https://alice-doc.github.io/alice-analysis-tutorial/building/
 layout: redirect

diff --git a/docs/quick.markdown → docs/docs/quick.md b/docs/quick.markdown → docs/docs/quick.md
@@ -1,13 +1,12 @@
 ---
-title: ALIBUILD
 subtitle: Quick Start
 layout: main
 ---
 
 aliBuild is a tool to simplify building and installing ALICE / ALFA
 software. This is a quickstart Guide which will show you how to build
 and use a package, for extended documentation please have a look at the
-[user guide](user.html).
+[user guide](user.md).
 
 ## Setting up
 
@@ -71,7 +70,6 @@ For example, on Centos7:
     sw/slc7_x86-64/AliRoot/v6-16-01-1
 
 ## Using the built package
-{: #loading-the-package-environment}
 
 Environment for packages built using aliBuild is managed by [Environment
 Modules](http://modules.sourceforge.net) and a wrapper script called alienv.
@@ -88,4 +86,4 @@ to list the available packages, and:
     alienv enter VO_ALICE@PackageA::VersionA[,VO_ALICE@PackageB::VersionB...]
 
 to enter a shell with the appropriate environment set. To learn more about alienv you
-can also look at the [user guide](user.html#using-the-packages-you-have-built).
+can also look at the [user guide](user.md#using-the-packages-you-have-built).
diff --git a/docs/reference.markdown → docs/docs/reference.md b/docs/reference.markdown → docs/docs/reference.md
@@ -1,5 +1,4 @@
 ---
-title: ALIBUILD
 subtitle: Recipe reference manual
 layout: main
 ---

diff --git a/docs/troubleshooting.markdown → docs/docs/troubleshooting.md b/docs/troubleshooting.markdown → docs/docs/troubleshooting.md
@@ -1,5 +1,4 @@
 ---
-title: ALIBUILD
 subtitle: Troubleshooting
 layout: main
 ---
@@ -223,7 +222,7 @@ or as a matter of fact any packages you have two options:
   and add the options there.
 
 Finally, for certain common options, e.g. debug flags, we provide a
-precooked configuration using so called [defaults](user.html#defaults).
+precooked configuration using so called [defaults](user.md#defaults).
 Simply add `--defaults debug` to your aliBuild flags and it will add
 debug flags to all your packages.
 

diff --git a/docs/tutorial.markdown → docs/docs/tutorial.md b/docs/tutorial.markdown → docs/docs/tutorial.md
@@ -1,5 +1,4 @@
 ---
-title: ALIBUILD
 subtitle: Basic tutorial
 dest_url: https://alice-doc.github.io/alice-analysis-tutorial/building/
 layout: redirect

diff --git a/docs/user.markdown → docs/docs/user.md b/docs/user.markdown → docs/docs/user.md
@@ -1,12 +1,11 @@
 ---
-title: ALIBUILD
 subtitle: User command line reference manual
 layout: main
 ---
 
 ## SYNOPSIS
 
-For a quick start introduction, please look [here](./quick.html).
+For a quick start introduction, please look [here](quick.md).
 
 ```
 aliBuild build [-h] [--defaults DEFAULT]
@@ -243,7 +242,7 @@ validated for datataking and the choice will not change until the end of
 RUN2 of LHC. In order to change that and use, for example, a more recent
 version of ROOT you can use the `--default root6` option which will
 enable ROOT6 based builds. For a more complete description of how defaults
-works please look at [the reference manual](reference.html#defaults).
+works please look at [the reference manual](reference.md#defaults).
 
 ## Disabling packages
 

diff --git a/docs/js/highlight.pack.js b/docs/js/highlight.pack.js
diff --git a/docs/main.css b/docs/main.css
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
@@ -0,0 +1,26 @@
+site_name: "aliBuild: ALICE software builder"
+repo_name: View source code
+repo_url: https://github.com/alisw/alibuild
+
+theme:
+  name: material
+
+use_directory_urls: false
+
+nav:
+  - Home: index.md
+  - Quickstart: quick.md
+  - User manual: user.md
+  - Reference: reference.md
+  - ALICE/O2 tutorial: "https://alice-doc.github.io/alice-analysis-tutorial/building/"
+
+markdown_extensions:
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences
+  - toc:
+      permalink: "#"
diff --git a/docs/o2-dataflow-tutorial.markdown b/docs/o2-dataflow-tutorial.markdown