Automate the update of docs/index.md

.github/workflows/check-update-index.yml

@@ -0,0 +1,32 @@
+name: check-update-index
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - '**'
+
+jobs:
+  check-index:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out the repo
+        uses: actions/checkout@v3
+
+      - name: Execute the script
+        run: ./scripts/update-index.sh
+
+      - name: Check the diff
+        run: echo diff_output="$(git diff --name-only "$PWD/docs/index.md")" >> "$GITHUB_ENV"
+
+      - name: Warning
+        # if diff_output not null and master branch
+        if: env.diff_output != '' && github.ref_name == 'master'
+        run: "echo ::warning:: 'docs/index.md' outdated, please run 'scripts/update-index.sh'."
+
+      - name: Error
+        # if diff_output not null and not master branch
+        if: env.diff_output != '' && github.ref_name != 'master'
+        run: "echo ::error:: 'docs/index.md' outdated, please run 'scripts/update-index.sh' and commit.; exit 1"

README.md

@@ -21,6 +21,7 @@ Howtos
 * [How to deploy an instance of Learn OCaml?](https://github.com/ocaml-sf/learn-ocaml/blob/master/docs/howto-deploy-a-learn-ocaml-instance.md)
 * [How to deploy Learn-OCaml statically?](https://github.com/ocaml-sf/learn-ocaml/blob/master/docs/howto-deploy-learn-ocaml-statically.md)
 * [How to practice OCaml with Learn-OCaml?](https://github.com/ocaml-sf/learn-ocaml/blob/master/docs/howto-practice-ocaml.md)
+* [How to classify students answers?](https://github.com/ocaml-sf/learn-ocaml/blob/master/docs/howto-classify-students-answers.md)
 
 Contacts
 --------
@@ -46,39 +47,39 @@ permitted, alteration requires prior written authorization by
 OCamlPro.
 
 The OCaml / ocaml.org logo is released under the very liberal UNLICENSE.
-See (https://github.com/ocaml/ocaml.org/blob/master/LICENSE.md).
+See [https://github.com/ocaml/ocaml.org/blob/master/LICENSE.md](https://github.com/ocaml/ocaml.org/blob/master/LICENSE.md).
 
 The Inconsolata font is released under the Open Font License.
-See (http://www.levien.com/type/myfonts/inconsolata.html).
+See [http://www.levien.com/type/myfonts/inconsolata.html](http://www.levien.com/type/myfonts/inconsolata.html).
 
 The Biolinum font is licensed under the GNU General Public License with
 a the 'Font-Exception'.
-See (http://www.linuxlibertine.org).
+See [http://www.linuxlibertine.org](http://www.linuxlibertine.org).
 
 The public instance of Learn OCaml uses the Fontin font instead of
 Biolinum. This font is licensed under the exljbris Font Foundry Free
 Font License Agreement, which, to our understanding, does not allow us
-to redistribute it. See (http://www.exljbris.com/eula.html). You will
+to redistribute it. See [http://www.exljbris.com/eula.html](http://www.exljbris.com/eula.html). You will
 optionally have to procure the files by yourself while building the
 app. If not, the CSS provides a reasonable fallback font.
 
 Contributions to this repository are placed under the MIT
 license. This means that we can merge them with the same license as
 the rest of the codebase, while you keep all the rights on your code.
 And we will not have to bother you with any future license update.
-See (https://opensource.org/licenses/MIT).
+See [https://opensource.org/licenses/MIT](https://opensource.org/licenses/MIT).
 
 Authors and Acknowledgements
 ----------------------------
 
 Learn-OCaml is a free software by the [OCaml Software Foundation](https://ocaml-sf.org).
 
- * The main authors are Benjamin Canou, Çağdaş Bozman and Grégoire Henry.
+* The main authors are Benjamin Canou, Çağdaş Bozman and Grégoire Henry.
 
- * It builds on the previous experience of Try OCaml by Çağdaş Bozman.
+* It builds on the previous experience of Try OCaml by Çağdaş Bozman.
 
- * We heavily use js_of_ocaml, so thanks to the Ocsigen team.
+* We heavily use js_of_ocaml, so thanks to the Ocsigen team.
 
- * The text editing component is a customized version of ACE.
+* The text editing component is a customized version of ACE.
 
- * We also include a derivative of ppx_metaquot by Alain Frisch.
+* We also include a derivative of ppx_metaquot by Alain Frisch.

docs/index.md

@@ -20,6 +20,7 @@ Howtos
 * [How to submit an exercise to the global corpus?](./howto-submit-an-exercise.md)
 * [How to deploy an instance of Learn OCaml?](./howto-deploy-a-learn-ocaml-instance.md)
 * [How to deploy Learn-OCaml statically?](./howto-deploy-learn-ocaml-statically.md)
+* [How to practice OCaml with Learn-OCaml?](./howto-practice-ocaml.md)
 * [How to classify students answers?](./howto-classify-students-answers.md)
 
 Contacts
@@ -62,23 +63,23 @@ to redistribute it. See [http://www.exljbris.com/eula.html](http://www.exljbris.
 optionally have to procure the files by yourself while building the
 app. If not, the CSS provides a reasonable fallback font.
 
-Contributions to this repository are placed under the BSD
+Contributions to this repository are placed under the MIT
 license. This means that we can merge them with the same license as
 the rest of the codebase, while you keep all the rights on your code.
 And we will not have to bother you with any future license update.
-See [https://opensource.org/licenses/BSD-3-Clause](https://opensource.org/licenses/BSD-3-Clause).
+See [https://opensource.org/licenses/MIT](https://opensource.org/licenses/MIT).
 
 Authors and Acknowledgements
 ----------------------------
 
 Learn-OCaml is a free software by the [OCaml Software Foundation](https://ocaml-sf.org).
 
- * The main authors are Benjamin Canou, Çağdaş Bozman and Grégoire Henry.
+* The main authors are Benjamin Canou, Çağdaş Bozman and Grégoire Henry.
 
- * It builds on the previous experience of Try OCaml by Çağdaş Bozman.
+* It builds on the previous experience of Try OCaml by Çağdaş Bozman.
 
- * We heavily use js_of_ocaml, so thanks to the Ocsigen team.
+* We heavily use js_of_ocaml, so thanks to the Ocsigen team.
 
- * The text editing component is a customized version of ACE.
+* The text editing component is a customized version of ACE.
 
- * We also include a derivative of ppx_metaquot by Alain Frisch.
+* We also include a derivative of ppx_metaquot by Alain Frisch.

scripts/update-index.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+
+# This script updates 'docs/index.md' from 'README.md',
+# and changes github.com/…/learn-ocaml/…/docs URLs to relative paths,
+# so that github.io pages work independently of github.com src files.
+
+srcdir=$(cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null && pwd)
+
+readme=$(readlink -f "$srcdir/../README.md")
+index=$(readlink -f "$srcdir/../docs/index.md")
+
+if [[ ! -r "$readme" ]]
+then
+  echo "Error: '$readme': file does not exist or is unreadable"
+  exit 1 
+fi
+
+if [[ ! -w "$index" ]]
+then
+  echo "Error: '$index': file does not exist or is not writable"
+  exit 1 
+fi
+
+url="https://github.com/ocaml-sf/learn-ocaml/blob/master/docs"
+
+sed -e "s;$url;.;g" "$readme" > "$index"