setup website tooling (#315)

* docs: initial website integration
* ci: fix conflicting names for prebuilt tlspuffin artifact
* ci: auto-update website content on PR merged
* docs: fix rustdoc warnings
* docs: update broken README.md links
* build: fix macos nix packages

.github/workflows/on-pr-changed.yml

@@ -118,19 +118,18 @@ jobs:
     defaults:
       run:
         shell: bash
+    env:
+      RUSTDOCFLAGS: -Dwarnings
     steps:
       - uses: actions/checkout@v4
       - name: setup
         uses: ./.github/actions/setup
 
-      - name: build tlspuffin book
-        run: just _docs-book
-
       - name: build API documentation
-        run: just _docs-api
+        run: just api-docs
 
-      - name: build index page
-        run: just docs
+      - name: build website
+        run: just website-pkg
 
   benchmark:
     needs: [configure]

.github/workflows/on-pr-merged.yml

@@ -6,7 +6,7 @@ on:
       - main
 
 permissions:
-  contents: write # needed for gh-pages deployment jobs
+  contents: read
 
 # NOTE: we prevent parallel runs of this workflow
 #
@@ -36,42 +36,56 @@ jobs:
   benchmark:
     uses: ./.github/workflows/run-benchmarks.yml
 
-  docs:
-    name: Build dev Documentation
+  website:
+    name: Package Website
     runs-on: ubuntu-22.04
+    defaults:
+      run:
+        shell: bash
+    env:
+      RUSTDOCFLAGS: -Dwarnings
     steps:
       - uses: actions/checkout@v4
       - name: setup
         uses: ./.github/actions/setup
 
       - name: build website
-        shell: bash
-        run: just docs
+        run: just website-pkg
 
-      - name: upload dev documentation artifact
+      - name: upload website artifact
         uses: actions/upload-artifact@v4
         with:
-          name: docs-dev
-          path: target/docs
-          if-no-files-found: error
+          name: website
+          path: target/package/build/website
 
   deploy:
-    needs: [validation, docs]
-    name: Deploy dev Documentation
+    needs: [website]
+    name: Update Website Repository
     runs-on: ubuntu-22.04
+    environment: github-pages
     steps:
-      - uses: actions/checkout@v4
+      - name: checkout website repository
+        uses: actions/checkout@v4
+        with:
+          repository: 'tlspuffin/tlspuffin.github.io'
+          ref: 'main'
+          ssh-key: ${{ secrets.WEBSITE_REPO_KEY }}
+
+      - name: remove previous website folder
+        run: |
+          git rm -rf website/
+          rm -rf website
 
-      - name: download dev documentation artifact
+      - name: add updated website
         uses: actions/download-artifact@v4
         with:
-          name: docs-dev
-          path: docs-dev
+          name: website
+          path: website
 
-      - name: deploy dev documentation
-        uses: JamesIves/github-pages-deploy-action@v4.6.0
-        with:
-          folder: docs-dev
-          branch: gh-pages
-          clean: true
-          force: true
+      - name: push the changes
+        run: |
+          git config --global user.email tlspuffin@tlspuffin
+          git config --global user.name tlspuffin
+          git add website
+          git commit -m "deploy from ${{ github.repository }}/${{ github.ref}}@${{ github.sha }}"
+          git push

.github/workflows/run-prebuild.yml

@@ -72,11 +72,11 @@ jobs:
       - name: upload build timings
         uses: actions/upload-artifact@v4
         with:
-          name: cargo-timings-${{ steps.compute-lib-shortname.outputs.shortname }}
+          name: cargo-timings-${{ matrix.name }}
           path: target/cargo-timings/cargo-timing.html
 
       - name: upload build
         uses: actions/upload-artifact@v4
         with:
-          name: tlspuffin-${{ steps.compute-lib-shortname.outputs.shortname }}
+          name: tlspuffin-${{ matrix.name }}
           path: target/x86_64-unknown-linux-gnu/release/tlspuffin

.gitignore

@@ -40,6 +40,7 @@ stats.json.should-be-empty.log
 
 *.html
 *.css
-!docs/**/*.template.html
+!docs/**/*.css
+!docs/**/*.html
 
 super-linter.log

README.md

@@ -1,45 +1,8 @@
-<h1 align="center">tlspuffin</h1>
-<p align="center">
-  <img width=200px alt="Logo with Penguin" src="https://raw.githubusercontent.com/tlspuffin/tlspuffin/main/docs/assets/logo.jpg">
-</p>
-<div align="center">
-  <strong>TLS Protocol Under FuzzINg</strong>
-</div>
-<div align="center">
-  A Dolev-Yao guided fuzzer for TLS
-</div>
-
-<div align="center">
-  <img src="https://img.shields.io/badge/stability-experimental-orange.svg?style=flat-square"
-      alt="Stability" />
-  <a href="https://github.com/tlspuffin/tlspuffin/actions/workflows/rust.yml">
-    <img src="https://github.com/tlspuffin/tlspuffin/actions/workflows/on_main_push.yml/badge.svg"
-        alt="Build status" />
-  </a>
-</div>
-
-<div align="center">
-  Developed at LORIA, Inria, France and Trail of Bits, USA
-</div>
-
-
-<div align="center">
-  <h3>
-    <a href="https://raw.githubusercontent.com/tlspuffin/tlspuffin/main/docs/assets/masterarbeit.pdf">
-      Master Thesis
-    </a>
-    <span> | </span>
-    <a href="https://docs.google.com/presentation/d/e/2PACX-1vS-AogsZAAWBAL19kf2b8f5gbOexg9DWmXAQp4Y8zL8K6RDQbTxgKa4b6vNRMq59IezIBVgwMw7KQq6/pub?start=false&loop=false&delayms=3000">
-      Thesis Presentation
-    </a>
-    <span> | </span>
-    <a href="https://tlspuffin.github.io/tlspuffin/tlspuffin">
-      Documentation
-    </a>
-  </h3>
-</div>
-
-_Disclaimer: The term "symbolic-model-guided" should not be confused with symbolic execution or concolic fuzzing._
+## TLS Protocol Under FuzzINg: A Dolev-Yao guided fuzzer for TLS
+
+![Stability Experimental](https://img.shields.io/badge/stability-experimental-orange.svg?style=flat-square)
+[![CI Status](https://img.shields.io/github/actions/workflow/status/tlspuffin/tlspuffin/on-pr-merged.yml?branch=main&style=flat-square&label=CI)](https://github.com/tlspuffin/tlspuffin/actions/workflows/on-pr-merged.yml)
+
 
 ## Description
 

THIRD_PARTY

@@ -1154,3 +1154,27 @@ DEALINGS IN THE SOFTWARE.
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
+
+# docs/ are built using [Docusaurus](https://docusaurus.io)
+
+MIT License
+
+Copyright (c) Facebook, Inc. and its affiliates.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

docs/.gitignore

@@ -0,0 +1,23 @@
+# Rust API files generated by `cargo doc`
+/static/api
+
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docs/README.md

@@ -0,0 +1,18 @@
+This directory contains the documentation source files and the tooling for building the tlspuffin website.
+
+## Quickstart
+
+Serve a dev version locally:
+```sh
+cd docs/
+nix-shell
+npm install
+npm start
+```
+
+Build the production version:
+```sh
+cd docs/
+npm run build
+```
+