Mkdocs on GitHub Pages (#226)

Depends on #225.

Uses `mkdocs` to build the documentation into a read-the-docs theme, and
copies over the Javadocs (from #224) and REST Endpoint API docs (from
#225) into the static site folder so they can also be served (and are
linked to from the `.nav.yml`).


Detailed why we ended up with mkdocs over other alternatives in ADR 13.

---------

Co-authored-by: plocket <[email protected]>

Author: BryceStevenWilley

.github/workflows/build_and_test.yml

@@ -8,7 +8,7 @@ jobs:
 
     steps:
       - uses: actions/checkout@v3
-      - name: Set up JDK 11
+      - name: Set up JDK 21
         uses: actions/setup-java@v4
         with:
           java-version: '21'

.github/workflows/docs_site.yml

@@ -0,0 +1,54 @@
+# Sample workflow for building and deploying a Jekyll site to GitHub Pages
+name: Deploy Jekyll with GitHub Pages dependencies preinstalled
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["main"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+          cache: 'pip'
+      - name: Build Mkdocs
+        run: |
+            pip install mkdocs mkdocs-awesome-nav
+            mkdocs build
+      - uses: actions/setup-java@v4
+        with:
+          java-version: '21'
+          distribution: 'adopt'
+          cache: 'maven'
+      - name: Build Javadoc and Enunciate Swagger UI
+        run: |
+            mvn --batch-mode -Preproducible compile javadoc:javadoc javadoc:aggregate
+            cp -r target/reports/apidocs site/apidocs
+            cp -r proxyserver/target/enunciate-docs/apidocs site/endpoints
+            # Adds a setting to swagger-ui to turn off the "Try it now" buttons
+            # Not active right now, but keeping around in case we want to change
+            # sed -i 's/url\: url/url\: url\, supportedSubmitMethods\: \[\]/' site/endpoints/ui/swagger-initializer.js
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/

.gitignore

@@ -86,3 +86,6 @@ proxyserver/tyler_efm_codes*
 
 # formatting
 google-java-format_*
+
+# MKDocs Output
+site

docs/.nav.yml

@@ -0,0 +1,8 @@
+nav:
+  - README.md
+  - developing.md
+  - operations_guide/index.md
+  - architecture.md
+  - "REST API Docs 🔗": /endpoints
+  - "Javadocs 🔗": /apidocs
+  - "*"

docs/setup.md docs/README.mddocs/setup.md renamed to docs/README.md

@@ -134,3 +134,8 @@ mvn test
 ## Contents of .env file
 
 See [env.example](../env.example) for the most up to date documentation for this.
+
+
+## Next steps
+
+See [developing.md](developing.md).

docs/adr/013-choice-of-documentation-site.md

@@ -0,0 +1,71 @@
+# Choice of Documetation Site Framework
+
+Author: Bryce Willey
+
+Date: 2025-06-25
+
+Status: Decided, In progress 
+
+While we have various ways of generating and viewing docs locally (manually
+building javadocs, using [enunciate](008-choice-of-rest-docs.md) to view REST
+endpoint docs), there's no easy way to access this information if you don't
+have a local development environment set up (i.e. new developers or folks who
+don't work on this repo much).
+
+We should host this information on a documentation site that is easily findable and
+accessible. The only real choice for where to host it is on GitHub pages, and
+IMO it should be separate from the rest of the [Assembly Line documentation](https://assemblyline.suffolklitlab.org/docs/overview).
+This ADR focuses on how to generate the static HTML that will be hosted on
+GitHub pages.
+
+## Considered Alternatives
+
+* `mvn site` and the maven-site-plugin
+* `docsite`: https://github.com/luiinge/docsite-maven-plugin?tab=readme-ov-file
+* `jekyll`, the default / best supported static site generator for GitHub pages
+* `mkdocs`: https://www.mkdocs.org/
+* `docusaurus`, what we use for the Document Assembly Line documetation
+
+## Decision Outcome
+
+**mkdocs**
+
+* `+` it Just Works. Out of all of the options tried, needed the least
+  customization, and no moving of documetation files.
+* `+` lets us easily add links to other URLs (necessary to include externally
+  generated javadocs and Swagger API docs)
+* `+` built on python, so not too much of a lift compared to other choices
+* `-` is a new documetation generator compared to what's already available
+* `-` not the biggest fan of either of the themes, but they're good enough and
+  there are [alternate themes available](https://github.com/mkdocs/catalog?tab=readme-ov-file#-theming)
+
+## Pros and Cons of the Alternatives <!-- optional -->
+
+### maven-site-plugin
+
+* `+` already built into maven
+* `-` unintuitive layout and navigation, doesn't emphasize the right things
+* `-` would have to move markdown content to `src/site/markdown`, a very
+  confusing place to put documentation when simply browsing the project.
+* `-` cumbersome to use and try to find documentation for (maven has lots of
+  documentation, but little of it is immediately usable, or could serve as a good reference)
+* `-` not aesthetically appealing
+
+### docsite
+
+* `+` a better alternative to maven site, can use a maven plugin
+* `-` had conflicting errors with multi-module projects
+* `-` still some wonky-ness when trying to include a docs folder
+
+### jekyll
+
+* `+` the best support when trying do stuff on GitHub pages (prebuilt actions,
+  etc.)
+* `-` almost all Jekyll themes don't have good navigation
+* `-` still quite a bit of extra setup to get things set up, without adding a
+  lot of extra config and `_layout` dirs, etc.
+
+### Docusaurus
+
+* `+` already used by other Suffolk projects
+* `-` too heavy-weight for this project, still lots of config

docs/architecture.md

@@ -1,4 +1,4 @@
-# E-file Proxy Architecture
+# Architecture
 
 There's a glossary at the end with common e-filing jargon.
 If I refer to specific `*.java` files, I will use just the file name (i.e. `LoginDatabase.java`) if it's unique in the repo, or sub number of

docs/https.md

@@ -19,12 +19,12 @@ We are still working to improve the steps, but current the process is:
    Something like `openssl rand -base64 12` will generate 16 characters securely.
    * You can also set a `MONITORING_EMAIL` which will be used for email renewal reminders from Lets Encrypt.
 2. Start up the docker containers (see [setup.md](setup.md)).
-3. Start a bash shell inside the running container: `docker exec -it efileproxyserver-efspjava-1 /bin/sh`
+3. Start a shell inside the running container: `docker exec -it efileproxyserver-efspjava-1 /bin/sh`
 4. Change directories to the app: `cd /app`.
 5. Run the ACME renewal process: `java -cp efspserver-with-deps.jar edu.suffolk.litlab.efspserver.services.acme.AcmeRenewal renew`.
    If the renewal process succeeded, `acme-domain-chain.crt` and `tls_server_cert.jks`
    should both be present in `/tmp/tls_certs` inside the container and in `src/main/config` outside the container.
-6. Exit the bash shell you started, and rebuild and restart the java docker container.
+6. Exit the shell you started, and rebuild and restart the java docker container.
 
 The newly started container should be able to serve HTTPS correctly!
 

docs/wsdl2java.md

@@ -1,4 +1,4 @@
-# WSDL2Java: Generating the SOAP code
+# Using WSDL2Java
 
 The proxy server uses SOAP to communicate with Tyler's Efiling Manager servers (EFM).
 SOAP describes the procedure calls that can be made to the server using XML. The SOAP library

mkdocs.yml

@@ -0,0 +1,7 @@
+site_name: Suffolk LIT Lab E-file Proxy Server
+
+theme: readthedocs
+
+plugins:
+  - search
+  - awesome-nav