From 3a6d2857f30fbd1ca08f9329843c38c37f581140 Mon Sep 17 00:00:00 2001 From: Luis Alvergue Date: Fri, 22 Nov 2024 17:02:27 +0000 Subject: [PATCH 1/3] feat: create docs container --- .devcontainer/Dockerfile | 3 ++ .devcontainer/devcontainer.json | 4 +- .markdownlint.yaml | 19 ++++++++++ .pre-commit-config.yaml | 5 +++ .vscode/settings.json | 8 +++- compose.yml | 9 +++++ docs/.pages | 2 + docs/README.md | 5 +++ docs/requirements.txt | 6 +++ mkdocs.yml | 65 +++++++++++++++++++++++++++++++++ 10 files changed, 124 insertions(+), 2 deletions(-) create mode 100644 .markdownlint.yaml create mode 100644 docs/.pages create mode 100644 docs/README.md create mode 100644 docs/requirements.txt create mode 100644 mkdocs.yml diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile index 50f8a2a..89defa2 100644 --- a/.devcontainer/Dockerfile +++ b/.devcontainer/Dockerfile @@ -28,6 +28,9 @@ COPY . . # install devcontainer requirements RUN pip install --no-cache-dir -r .devcontainer/requirements.txt +# install docs requirements +RUN pip install --no-cache-dir -r docs/requirements.txt + # install pre-commit environments in throwaway Git repository # https://stackoverflow.com/a/68758943 RUN git init . && \ diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index 4b65b98..5fcfd59 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -2,7 +2,7 @@ "name": "caltrans/pems", "dockerComposeFile": ["../compose.yml"], "service": "dev", - "runServices": ["dev"], + "runServices": ["dev", "docs"], "workspaceFolder": "/home/caltrans/src", "postAttachCommand": ["/bin/bash", ".devcontainer/postAttach.sh"], "customizations": { @@ -18,6 +18,8 @@ }, // Add the IDs of extensions you want installed when the container is created. "extensions": [ + "bpruitt-goddard.mermaid-markdown-syntax-highlighting", + "DavidAnson.vscode-markdownlint", "eamodio.gitlens", "esbenp.prettier-vscode", "mhutchie.git-graph" diff --git a/.markdownlint.yaml b/.markdownlint.yaml new file mode 100644 index 0000000..f4c8d40 --- /dev/null +++ b/.markdownlint.yaml @@ -0,0 +1,19 @@ +# includes/excludes all rules by default +default: true + +# 4-space list indentation works best with MkDocs +MD007: + indent: 4 + +# Remove line length limit - no one wants to hard wrap all their paragraphs +MD013: false + +# Allow inline HTML +MD033: false + +# Allow duplicate headers +MD024: false + +# Allow mixing code block and fenced code regions +# Useful for pages with admonitions and fenced code blocks +MD046: false diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index e0c581c..1db046e 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -13,6 +13,11 @@ repos: - id: conventional-pre-commit stages: [commit-msg] + - repo: https://github.com/igorshubovych/markdownlint-cli + rev: v0.42.0 + hooks: + - id: markdownlint + - repo: https://github.com/pre-commit/pre-commit-hooks rev: v5.0.0 hooks: diff --git a/.vscode/settings.json b/.vscode/settings.json index cfa546a..40881c9 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -1,9 +1,15 @@ { "editor.formatOnSave": true, "editor.defaultFormatter": "esbenp.prettier-vscode", + "files.associations": { + ".pages": "yaml" + }, "files.encoding": "utf8", "files.eol": "\n", "files.insertFinalNewline": true, "files.trimFinalNewlines": true, - "files.trimTrailingWhitespace": true + "files.trimTrailingWhitespace": true, + "[markdown]": { + "editor.defaultFormatter": "esbenp.prettier-vscode" + } } diff --git a/compose.yml b/compose.yml index 1dc42e6..99bf58d 100644 --- a/compose.yml +++ b/compose.yml @@ -8,3 +8,12 @@ services: image: caltrans/pems:main volumes: - ./:/home/caltrans/src + + docs: + image: caltrans/pems:main + entrypoint: mkdocs + command: serve --dev-addr "0.0.0.0:8000" + ports: + - "8000" + volumes: + - ./:/home/caltrans/src diff --git a/docs/.pages b/docs/.pages new file mode 100644 index 0000000..b783fad --- /dev/null +++ b/docs/.pages @@ -0,0 +1,2 @@ +nav: + - Home: README.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..b67f4f1 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,5 @@ +# PeMS + +Caltrans Performance Measurement System + +PeMS is open-source software that is designed, developed, and maintained by [Compiler LLC](https://compiler.la) on behalf of Caltrans Traffic Operations. diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..5d89c29 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,6 @@ +mdx_truly_sane_lists +mkdocs==1.6.1 +mkdocs-awesome-pages-plugin +mkdocs-macros-plugin +mkdocs-material==9.5.44 +mkdocs-redirects diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..94c39f2 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,65 @@ +site_name: "caltrans/pems: Documentation" +repo_url: https://github.com/compilerla/pems +edit_uri: edit/main/docs +site_url: https://compilerla.github.io/pems + +theme: + name: material + features: + - navigation.expand + - navigation.tabs + - toc.integrate + palette: + - media: "(prefers-color-scheme: light)" + scheme: default + primary: blue + accent: green + toggle: + icon: material/toggle-switch-off-outline + name: Switch to dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: blue + accent: green + toggle: + icon: material/toggle-switch + name: Switch to light mode + +extra: + analytics: + provider: google + property: G-xxxxxxxxxx + +plugins: + - search + - awesome-pages + - redirects: + redirect_maps: + +extra_css: + - https://use.fontawesome.com/releases/v6.1.2/css/all.css + +markdown_extensions: + - admonition + - attr_list + - codehilite: + linenums: true + - mdx_truly_sane_lists + - pymdownx.emoji: + emoji_index: !!python/name:materialx.emoji.twemoji + emoji_generator: !!python/name:materialx.emoji.to_svg + - pymdownx.inlinehilite + - pymdownx.tasklist: + custom_checkbox: true + - pymdownx.tabbed + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + - pymdownx.smartsymbols + - meta + - toc: + # insert a blank space before the character + permalink: " ΒΆ" + - smarty From e3749414df5d9f7de717cb2af40aa529b5e7a3ce Mon Sep 17 00:00:00 2001 From: Luis Alvergue Date: Wed, 4 Dec 2024 14:42:34 +0000 Subject: [PATCH 2/3] feat: add GitHub Actions workflow to publish docs --- .github/workflows/mkdocs.yml | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 .github/workflows/mkdocs.yml diff --git a/.github/workflows/mkdocs.yml b/.github/workflows/mkdocs.yml new file mode 100644 index 0000000..b270f76 --- /dev/null +++ b/.github/workflows/mkdocs.yml @@ -0,0 +1,25 @@ +name: Publish docs +on: + workflow_dispatch: + push: + branches: + - main + paths: + - ".github/workflows/mkdocs.yml" + - "docs/**" + - ".markdownlint.yaml" + - "mkdocs.yml" + +jobs: + docs: + name: Publish docs + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Deploy docs + uses: mhausenblas/mkdocs-deploy-gh-pages@master + env: + REQUIREMENTS: docs/requirements.txt + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} From 6dae01c1d480af7cfbc34d66ccdf8fe1a7ddb4e9 Mon Sep 17 00:00:00 2001 From: Luis Alvergue Date: Wed, 4 Dec 2024 20:32:20 +0000 Subject: [PATCH 3/3] feat: link to the docs service in the devcontainer's PORTS tab --- .devcontainer/devcontainer.json | 1 + 1 file changed, 1 insertion(+) diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index 5fcfd59..d3866d7 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -3,6 +3,7 @@ "dockerComposeFile": ["../compose.yml"], "service": "dev", "runServices": ["dev", "docs"], + "forwardPorts": ["docs:8000"], "workspaceFolder": "/home/caltrans/src", "postAttachCommand": ["/bin/bash", ".devcontainer/postAttach.sh"], "customizations": {