docs: initialize mkdocs config and workflow for github pages (#315)

* docs: initialize mkdocs site with placeholder content * ci: add workflow to publish mkdocs content to github pages * fix: pin actions using commit hashes not version tags * fix: resolve lint issues in yaml Signed-off-by: George Vauter <[email protected]> --------- Signed-off-by: George Vauter <[email protected]>
RedHatProductSecurity · Aug 7, 2024 · 05cfce1 · 05cfce1
1 parent ee86f5c
commit 05cfce1
Show file tree

Hide file tree

Showing 5 changed files with 494 additions and 1 deletion.
diff --git a/.github/workflows/mkdocs.yml b/.github/workflows/mkdocs.yml
@@ -0,0 +1,26 @@
+name: publish-docs
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'mkdocs.yml'
+      - 'docs/**'
+
+permissions:
+  contents: write
+
+jobs:
+  gh-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332  # pin@v4
+      - uses: actions/setup-python@39cd14951b08e74b54015e9e001cdefcf80e669f  # pin@v5
+        with:
+          python-version: '3.11'
+      - uses: actions/cache@0c45773b623bea8c8e75f6c82b208c3cf94ea4f9  # pin@v4
+        with:
+          key: ${{ github.ref }}
+          path: .cache
+      - run: pip install mkdocs-material
+      - run: mkdocs gh-deploy --force
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,75 @@
+# trestle-bot
+
+[![Pre commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
+[![License](https://img.shields.io/badge/license-apache-blue.svg)](http://www.apache.org/licenses/LICENSE-2.0.html)
+[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=rh-psce_trestle-bot&metric=coverage)](https://sonarcloud.io/summary/new_code?id=rh-psce_trestle-bot)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=rh-psce_trestle-bot&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=rh-psce_trestle-bot)
+
+
+
+trestle-bot assists users in leveraging [Compliance-Trestle](https://github.com/oscal-compass/compliance-trestle) in CI/CD workflows for [OSCAL](https://github.com/usnistgov/OSCAL) formatted compliance content management.
+
+> WARNING: This project is currently under initial development. APIs may be changed incompatibly from one commit to another.
+
+## Getting Started
+
+### Available Commands
+
+The `autosync` command will sync trestle-generated Markdown files to OSCAL JSON files in a trestle workspace. All content under the provided markdown directory when the action is run will be transformed. This action supports all top-level models [supported by compliance-trestle for authoring](https://oscal-compass.github.io/compliance-trestle/tutorials/ssp_profile_catalog_authoring/ssp_profile_catalog_authoring/).
+
+The `rules-transform` command can be used when managing [OSCAL Component Definitions](https://pages.nist.gov/OSCAL-Reference/models/v1.1.1/component-definition/json-outline/) in a trestle workspace. The action will transform rules defined in the rules YAML view to an OSCAL Component Definition JSON file.
+
+The `create-cd` command can be used to create a new [OSCAL Component Definition](https://pages.nist.gov/OSCAL-Reference/models/v1.1.1/component-definition/json-outline/) in a trestle workspace. The action will create a new Component Definition JSON file and corresponding directories that contain rules YAML files and trestle-generated Markdown files. This action prepares the workspace for use with the `rules-transform` and `autosync` actions.
+
+The `sync-upstreams` command can be used to sync and validate upstream OSCAL content stored in a git repository to a local trestle workspace. Which content is synced is determined by the `include_model_names` and `exclude_model_names` inputs.
+
+The `create-ssp` command can be used to create a new [OSCAL System Security Plans](https://pages.nist.gov/OSCAL-Reference/models/v1.1.1/system-security-plan/json-outline/) (SSP) in a trestle workspace. The action will create a new SSP JSON file and corresponding directories that contain trestle-generated Markdown files. This action prepares the workspace for use with the `autosync` action by creating or updating the `ssp-index.json` file. The `ssp-index.json` file is used to track the relationships between the SSP and the other OSCAL content in the workspace for the `autosync` action.
+
+Below is a table of the available commands and their current availability as a GitHub Action:
+
+| Command            | Available as a GitHub Action |
+|--------------------|------------------------------|
+| `autosync`         | &#10003;                     |
+| `rules-transform`  | &#10003;                     |                   
+| `create-cd`        | &#10003;                     |
+| `sync-upstreams`   | &#10003;                     |
+| `create-ssp`       |                              |
+
+For detailed documentation on how to use each action, see the README.md in each folder under [actions](./actions/).
+
+### Supported Git Providers
+
+> Note: Only applicable if using `trestle-bot` to create pull requests. Automatically detecting the git
+provider information is supported for GitHub Actions (GitHub) and GitLab CI (GitLab).
+
+- GitHub
+- GitLab
+
+### Run as a Container
+
+> Note: When running the commands in a container, all are prefixed with `trestlebot` (e.g. `trestlebot-autosync`). The default entrypoint for the container is the autosync command.
+
+Build and run the container locally:
+
+```bash
+podman build -f Dockerfile -t trestle-bot .
+podman run -v $(pwd):/data -w /data trestle-bot
+```
+
+Container images are available in `quay.io`:
+
+```bash
+podman run -v $(pwd):/data -w /data quay.io/continuouscompliance/trestle-bot:<tag>
+```
+
+## Contributing
+
+For information about contributing to trestle-bot, see the [CONTRIBUTING.md](./CONTRIBUTING.md) file.
+
+## License
+
+This project is licensed under the Apache 2.0 License - see the [LICENSE.md](LICENSE) file for details.
+
+## Troubleshooting
+
+See [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) for troubleshooting tips.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -0,0 +1,36 @@
+site_name: trestle-bot
+
+theme:
+  name: material
+  language: en
+  features:
+    - content.code.annotation
+    - content.code.copy
+    - content.tabs.link
+    - navigation.sections
+    - navigation.tabs
+    - navigation.top
+    - search.highlight
+    - search.suggest
+    - toc.integrate
+  palette:
+    - scheme: default
+      toggle:
+        icon: material/toggle-switch-off-outline 
+        name: Switch to dark mode
+    - scheme: slate 
+      toggle:
+        icon: material/toggle-switch
+        name: Switch to light mode    
+
+markdown_extensions:
+  - toc:
+      toc_depth: 2
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+
+copyright: |
+  &copy; Copyright 2023 Red Hat, Inc.</a>