docs/manual: new manual!

Co-authored-by: Attie Grande <attie@attie.co.uk> Co-authored-by: Piotr Esden-Tempski <piotr@esden.net> Co-authored-by: Charlotte <charlotte@lottia.net>
GlasgowEmbedded · Oct 2, 2023 · 6362f90 · 6362f90
1 parent cd46b60
commit 6362f90
Show file tree

Hide file tree

Showing 38 changed files with 1,464 additions and 373 deletions.
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -1,14 +1,14 @@
 on:
   push:
-    branches: main
   pull_request:
   merge_group:
 
 name: CI
 jobs:
 
   test-software:
-    runs-on: ubuntu-22.04
+    if: (github.event.ref == 'refs/heads/main' || github.event_name == 'pull_request') || github.repository != 'GlasgowEmbedded/glasgow'
+    runs-on: ubuntu-latest
     strategy:
       matrix:
         python-version:
@@ -54,7 +54,8 @@ jobs:
         run: pdm run test
 
   build-firmware:
-    runs-on: ubuntu-22.04
+    if: (github.event.ref == 'refs/heads/main' || github.event_name == 'pull_request') || github.repository != 'GlasgowEmbedded/glasgow'
+    runs-on: ubuntu-latest
     steps:
       - name: Check out source code
         uses: actions/checkout@v3
@@ -71,11 +72,86 @@ jobs:
         working-directory: ./firmware
         run: make
 
-  required: # group all `test (*)` workflows into one for the required status check
+  build-manual:
+    if: (github.event.ref == 'refs/heads/main' || github.event_name == 'pull_request') || github.repository != 'GlasgowEmbedded/glasgow'
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docs/manual
+    steps:
+      - name: Check out source code
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - name: Set up PDM
+        uses: pdm-project/setup-pdm@v3
+      - name: Install dependencies
+        run: |
+          pdm install
+      - name: Build documentation
+        run: |
+          pdm run build
+      - name: Upload documentation archive
+        uses: actions/upload-artifact@v3
+        with:
+          name: docs
+          path: docs/manual/out
+
+  required: # group all required workflows into one to avoid reconfiguring this in Actions settings
+    if: (github.event.ref == 'refs/heads/main' || github.event_name == 'pull_request') || github.repository != 'GlasgowEmbedded/glasgow'
     needs:
       - test-software
       - build-firmware
+      - build-manual
     runs-on: ubuntu-latest
     steps:
       - run: |
           true
+
+  publish-manual:
+    needs: build-manual
+    if: (github.repository == 'GlasgowEmbedded/glasgow' && github.event.ref == 'refs/heads/main') || github.repository != 'GlasgowEmbedded/glasgow'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Check out source code
+        uses: actions/checkout@v3
+      - if: github.repository == 'GlasgowEmbedded/glasgow' && github.event.ref == 'refs/heads/main'
+        name: Inject documentation from artifact under latest/
+        uses: actions/download-artifact@v3
+        with:
+          name: docs
+          path: pages/latest/
+      - if: github.repository == 'GlasgowEmbedded/glasgow' && github.event.ref == 'refs/heads/main'
+        name: Add CNAME and redirect from the root to latest/
+        run: |
+          echo >pages/CNAME 'glasgow-embedded.org'
+          cat >pages/index.html <<END
+          <!DOCTYPE html>
+          <html lang="en-US">
+            <meta charset="utf-8">
+            <title>Redirecting&hellip;</title>
+            <link rel="canonical" href="latest/">
+            <script>location="latest/"</script>
+            <meta http-equiv="refresh" content="0; url=latest/">
+            <meta name="robots" content="noindex">
+            <h1>Redirecting&hellip;</h1>
+            <a href="latest/">Click here if you are not redirected.</a>
+          </html>
+          END
+      - if: github.repository != 'GlasgowEmbedded/glasgow'
+        name: Inject documentation from artifact under {branch}/
+        uses: actions/download-artifact@v3
+        with:
+          name: docs
+          path: pages/${{ github.ref_name }}/
+      - name: Disable Jekyll
+        run: |
+          touch pages/.nojekyll
+      - name: Publish documentation for a branch
+        uses: JamesIves/github-pages-deploy-action@releases/v4
+        with:
+          folder: pages/
+          clean: true
+          single-commit: true
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,46 +1 @@
-# Contributing to Glasgow
-
-## Contributing bug reports
-
-Bug reports are always welcome! When reporting a bug, please include the following:
-
-  * The operating system;
-  * The version of Glasgow (use `glasgow --version`);
-  * The complete debug log (use `glasgow -vvv [command...]`).
-
-## Contributing code
-
-Glasgow does not strictly adhere to any specific Python or C coding standards. If your code is structured and formatted similarly to existing code, it is good enough.
-
-### Vendor documentation
-
-If you have used vendor documentation while writing the code you're contributing, it is necessary to:
-
-  * upload the documentation to the [Glasgow Archive][archive]; and
-  * reference the documentation at the top of the file in the following format:
-
-    ```
-    Ref: <insert vendor documentation title or, if absent, URL here>
-    Document Number: <insert vendor document number here, or omit the field if absent>
-    Accession: <insert Glasgow Archive accession number here>
-    ```
-
-If you cannot upload the documentation to the archive because it is under NDA and/or watermarked, contact the maintainers for assistance. Often, it is possible to achieve sufficient coverage using techniques such as using existing leaked documents or parallel construction.
-
-[archive]: https://github.com/GlasgowEmbedded/Glasgow-Archive
-
-### Writing commit messages
-
-When modifying Python code, the first line of a commit message should, if possible, start with the name of the module that is being modified, such that `git log --grep` can be easily used for filtering. E.g.:
-
-    protocol.jtag_svf: accept and ignore whitespace in scan data.
-
-When modifying firmware, the first line of a commit message should start with `firmware`. E.g.:
-
-    firmware: fix an operator precedence issue.
-
-When modifying schematics or layout, the first line of a commit message should start with the revision. E.g.:
-
-    revC: swap U2/U3, fix DRC issue.
-
-If none of the cases above are a good fit, any descriptive message is sufficient.
+For information on contribution, please refer to the [official documentation](https://glasgow-embedded.org/latest/contribute.html).
diff --git a/LICENSE-0BSD.txt b/LICENSE-0BSD.txt
@@ -1,4 +1,4 @@
-Copyright (C) 2018 whitequark@whitequark.org
+Copyright (C)  Glasgow Interface Explorer contributors
 
 Permission to use, copy, modify, and/or distribute this software for
 any purpose with or without fee is hereby granted.