Merge pull request #122 from boegel/adding_software

prefer `adding_software` over `contributing_sw` in docs URL + fix broken URLs using auto-redirect
EESSI · Nov 9, 2023 · c9705ab · c9705ab
2 parents b0be38d + bc71d96
commit c9705ab
Show file tree

Hide file tree

Showing 13 changed files with 49 additions and 20 deletions.
diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
@@ -22,9 +22,10 @@ jobs:
       with:
         python-version: '3.10'
 
-    - name: install mkdocs
+    - name: install mkdocs + plugins
       run: |
-          pip install mkdocs mkdocs-material mkdocs-git-revision-date-localized-plugin mkdocs-toc-sidebar-plugin
+          pip install -r requirements.txt
+          pip list | grep mkdocs
           mkdocs --version
 
     - name: build tutorial

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -28,9 +28,10 @@ jobs:
           # config: '/lint/config/changelog.yml'
     #     args: '.'
 
-    - name: install mkdocs
+    - name: install mkdocs + plugins
       run: |
-          pip install mkdocs mkdocs-material mkdocs-git-revision-date-localized-plugin mkdocs-toc-sidebar-plugin
+          pip install -r requirements.txt
+          pip list | grep mkdocs
           mkdocs --version
 
     - name: build tutorial

diff --git a/docs/contributing_sw/building_software.md → docs/adding_software/building_software.md b/docs/contributing_sw/building_software.md → docs/adding_software/building_software.md
@@ -1,4 +1,6 @@
-# Building software (maintainers)
+# Building software
+
+*(for maintainers)*
 
 ### Instructing the bot to build :hammer: { #bot_build }
 

diff --git a/docs/contributing_sw/contribution_policy.md → docs/adding_software/contribution_policy.md b/docs/contributing_sw/contribution_policy.md → docs/adding_software/contribution_policy.md
diff --git a/...ontributing_sw/debugging_failed_builds.md → ...dding_software/debugging_failed_builds.md b/...ontributing_sw/debugging_failed_builds.md → ...dding_software/debugging_failed_builds.md
@@ -1,4 +1,6 @@
-# Debugging failed builds (contributors/maintainers)
+# Debugging failed builds
+
+*(for contributors + maintainers)*
 
 Unfortunately, software does not always build successfully. Since EESSI targets novel CPU architectures as well, build failures on such platforms are quite common, as the software and/or the software build systems have not always been adjusted to support these architectures yet.
 

diff --git a/docs/contributing_sw/deploying_software.md → docs/adding_software/deploying_software.md b/docs/contributing_sw/deploying_software.md → docs/adding_software/deploying_software.md
@@ -1,4 +1,6 @@
-# Deploying packages (maintainers)
+# Deploying software
+
+*(for maintainers)*
 
 ### Instructing the bot to deploy :rocket:
 

diff --git a/docs/contributing_sw/opening_pr.md → docs/adding_software/opening_pr.md b/docs/contributing_sw/opening_pr.md → docs/adding_software/opening_pr.md
@@ -1,4 +1,6 @@
-# Opening a pull request (contributors)
+# Opening a pull request
+
+*(for contributors)*
 
 To add software to EESSI, you should go through the semi-automatic software installation procedure by:
 

diff --git a/docs/adding_software/overview.md b/docs/adding_software/overview.md
@@ -0,0 +1,7 @@
+# Adding software to EESSI
+
+* [Contribution policy](contribution_policy.md)
+* [Opening a pull request *(for contributors)*](opening_pr.md)
+* [Building software *(for maintainers)*](building_software.md)
+* [Debugging failed builds *(for contributors + maintainers)*](debugging_failed_builds.md)
+* [Deploying software *(for maintainers)*](deploying_software.md)
diff --git a/docs/bot.md b/docs/bot.md
@@ -6,7 +6,7 @@ Building, testing, and deploying software is done by one or more *bot instances*
 The EESSI build-test-deploy bot :robot: is implemented as a [GitHub App](https://docs.github.com/en/apps/overview)
 in the [`eessi-bot-software-layer` repository](https://github.com/EESSI/eessi-bot-software-layer).
 
-It operates in the context of [pull requests](contributing_sw/opening_pr.md#software_layer_pull_request) to
+It operates in the context of [pull requests](adding_software/opening_pr.md#software_layer_pull_request) to
 the [`compatibility-layer` repository](https://github.com/EESSI/compatibility-layer) or the
 [`software-layer` repository](https://github.com/EESSI/software-layer),
 and follows the instructions supplied by humans,
@@ -61,7 +61,7 @@ to trigger building of software, and to deploy software installations in to the
 ## Building { #building }
 
 To instruct the bot :robot: to build software, one or more `build` instructions
-should be issued by posting a comment in the pull request (see also [here](contributing_sw/building_software.md#bot_build)).
+should be issued by posting a comment in the pull request (see also [here](adding_software/building_software.md#bot_build)).
 
 The most basic build instruction that can be sent to the bot is:
 

diff --git a/docs/contributing_sw/overview.md b/docs/contributing_sw/overview.md
diff --git a/docs/support.md b/docs/support.md
@@ -38,7 +38,7 @@ Note that we can only help with problems related to the software *installations*
 
 We are open to software requests for software that is not included in EESSI yet.
 
-The quickest way to add additional software to EESSI is by contributing it yourself as a community contribution, please see the [documentation on adding software](contributing_sw/overview.md).
+The quickest way to add additional software to EESSI is by contributing it yourself as a community contribution, please see the [documentation on adding software](adding_software/overview.md).
 
 Alternatively, you can send in a request to our support team. Please try to provide as much information on the software as possible: preferably use the [issue template](https://gitlab.com/eessi/support/-/issues/new?issuable_template=Software_request) (which requires you to log in to GitLab), or make sure to cover the items listed [here](https://gitlab.com/eessi/support/-/blob/main/.gitlab/issue_templates/Software_request.md).
 

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -43,13 +43,13 @@ nav:
     - using_eessi/eessi_demos.md
   - Adding software to EESSI:
     # Todo: insert an overview page with a flowchart showing the high level process
-    - contributing_sw/overview.md
+    - (overview): adding_software/overview.md
     # - Contribution policy, requires #108
-    - contributing_sw/contribution_policy.md
-    - contributing_sw/opening_pr.md
-    - contributing_sw/building_software.md
-    - contributing_sw/debugging_failed_builds.md
-    - contributing_sw/deploying_software.md
+    - adding_software/contribution_policy.md
+    - adding_software/opening_pr.md
+    - adding_software/building_software.md
+    - adding_software/debugging_failed_builds.md
+    - adding_software/deploying_software.md
   # Todo: write on how to contribute to the EESSI test suite
   # - Contributing software tests to the EESSI test suite:
   - Getting support: support.md
@@ -63,6 +63,16 @@ plugins:
   - git-revision-date-localized
   # necessary for search to work
   - search
+  - redirects:
+      redirect_maps:
+        adding_software.md: adding_software/overview.md
+        contributing_sw/building_software.md: adding_software/building_software.md
+        contributing_sw/contribution_policy.md: adding_software/contribution_policy.md
+        contributing_sw/debugging_failed_builds.md: adding_software/debugging_failed_builds.md
+        contributing_sw/deploying_software.md: adding_software/deploying_software.md
+        contributing_sw/opening_pr.md: adding_software/opening_pr.md
+        contributing_sw/overview.md: adding_software/overview.md
+        software_layer/adding_software.md: adding_software/overview.md
 markdown_extensions:
   # enable adding HTML attributes and CSS classes
   - attr_list

diff --git a/requirements.txt b/requirements.txt
@@ -0,0 +1,5 @@
+mkdocs
+mkdocs-material
+mkdocs-redirects
+mkdocs-git-revision-date-localized-plugin
+mkdocs-toc-sidebar-plugin