From b55edb93d0dd7e419d9c70a9363f6812b55c56c8 Mon Sep 17 00:00:00 2001 From: Xander Harris Date: Mon, 22 Jul 2024 07:45:49 -0700 Subject: [PATCH] Update commentary Closes #4 --- .github/workflows/pages.yml | 2 +- .gitignore | 3 + .markdownlint-cli2.yaml | 58 +++++++ .markdownlint.yaml | 331 ++++++++++++++++++++++++++++++++++++ Pipfile | 2 +- Pipfile.lock | 43 ++++- cicd.md | 1 + conf.py | 7 +- index.md | 12 +- license.md | 1 + readme.md | 20 +-- roles/kcp/index.md | 1 + security.md | 1 + 13 files changed, 445 insertions(+), 37 deletions(-) create mode 100644 .markdownlint-cli2.yaml create mode 100644 .markdownlint.yaml diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index 714aedb..c876472 100644 --- a/.github/workflows/pages.yml +++ b/.github/workflows/pages.yml @@ -65,7 +65,7 @@ jobs: - name: Install the checker run: npm i -g markdownlint-cli2 markdownlint-cli2-formatter-junit --save-dev - name: Lint the Markdown - run: markdownlint-cli2 **/*.md + run: markdownlint-cli2 "*.md" "**/*.md" - name: Publish Test Results uses: EnricoMi/publish-unit-test-result-action@v2 if: always() diff --git a/.gitignore b/.gitignore index 599d156..06c09ed 100644 --- a/.gitignore +++ b/.gitignore @@ -5,3 +5,6 @@ _build/ *.xcf .gnupg roles/reset/files/*.reset.md +package-lock.json +package.json +node_modules diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml new file mode 100644 index 0000000..06fd3c5 --- /dev/null +++ b/.markdownlint-cli2.yaml @@ -0,0 +1,58 @@ +### +# ```{rubric} MarkdownLint Configuration +# ``` +# --- +# An example .markdownlint-cli2.yaml file +# +# Disable some built-in rules +config: + no-multiple-blanks: true + no-trailing-spaces: true + +# Include a custom rule package +# customRules: +# - markdownlint-rule-titlecase + +# Fix any fixable errors +fix: true +### +# Define a custom front matter pattern +# frontMatter: "[^]*<\/head>" +# +# Ignore files referenced by .gitignore (only valid at root) +gitignore: true +### +# Define glob expressions to use (only valid at root) +globs: + - "#.venv" +### +# Define glob expressions to ignore +ignores: + - "ignore*.md" +### +# Use a plugin to recognize math +# markdownItPlugins: +# - +# - "@iktakahiro/markdown-it-katex" +# +# Additional paths to resolve module locations from +modulePaths: + - "./modules" +### +# Disable banner message on stdout (only valid at root) +noBanner: false +### +# Disable inline config comments +noInlineConfig: false +### +# Disable progress on stdout (only valid at root) +noProgress: false +### +# Use a specific formatter (only valid at root) +outputFormatters: + - + - markdownlint-cli2-formatter-default + - markdownlint-cli2-formatter-junit +### +# Show found files on stdout (only valid at root) +showFound: true diff --git a/.markdownlint.yaml b/.markdownlint.yaml new file mode 100644 index 0000000..f2261dc --- /dev/null +++ b/.markdownlint.yaml @@ -0,0 +1,331 @@ +### +# ```{rubric} Markdown Lint Rules +# ``` +# Example markdownlint configuration with all properties set to their default value +# +# Default state for all rules +default: true +### +# Path to configuration file to extend +extends: null +### +# MD001/heading-increment : Heading levels should only increment by one level at a time : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md001.md +MD001: true +### +# MD003/heading-style : Heading style : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md003.md +MD003: + ### + # Heading style + style: "consistent" +### +# MD004/ul-style : Unordered list style : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md004.md +MD004: + ### + # List style + style: "consistent" +### +# MD005/list-indent : Inconsistent indentation for list items at the same level : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md005.md +MD005: true +### +# MD007/ul-indent : Unordered list indentation : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md007.md +MD007: + ### + # Spaces for indent + indent: 2 + ### + # Spaces for first level indent (when start_indented is set) + start_indent: 2 + ### + # Whether to indent the first level of the list + start_indented: false +### +# MD009/no-trailing-spaces : Trailing spaces : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md009.md +MD009: + ### + # Spaces for line break + br_spaces: 2 + ### + # Allow spaces for empty lines in list items + list_item_empty_lines: false + ### + # Include unnecessary breaks + strict: false +### +# MD010/no-hard-tabs : Hard tabs : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md010.md +MD010: + ### + # Include code blocks + code_blocks: true + ### + # Fenced code languages to ignore + ignore_code_languages: [] + ### + # Number of spaces for each hard tab + spaces_per_tab: 2 +### +# MD011/no-reversed-links : Reversed link syntax : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md011.md +MD011: true +### +# MD012/no-multiple-blanks : Multiple consecutive blank lines : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md012.md +MD012: + ### + # Consecutive blank lines + maximum: 1 +### +# MD013/line-length : Line length : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md013.md +MD013: + ### + # Number of characters for code blocks + code_block_line_length: 80 + ### + # Include code blocks + code_blocks: true + ### + # Number of characters for headings + heading_line_length: 80 + ### + # Include headings + headings: true + ### + # Number of characters + line_length: 80 + ### + # Stern length checking + stern: false + ### + # Strict length checking + strict: false + ### + # Include tables + tables: true +### +# MD014/commands-show-output : Dollar signs used before commands without showing output : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md014.md +MD014: true +### +# MD018/no-missing-space-atx : No space after hash on atx style heading : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md018.md +MD018: true +### +# MD019/no-multiple-space-atx : Multiple spaces after hash on atx style heading : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md019.md +MD019: true +### +# MD020/no-missing-space-closed-atx : No space inside hashes on closed atx style heading : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md020.md +MD020: true +### +# MD021/no-multiple-space-closed-atx : Multiple spaces inside hashes on closed atx style heading : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md021.md +MD021: true +### +# MD022/blanks-around-headings : Headings should be surrounded by blank lines : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md022.md +MD022: + ### + # Blank lines above heading + lines_above: 1 + ### + # Blank lines below heading + lines_below: 1 +### +# MD023/heading-start-left : Headings must start at the beginning of the line : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md023.md +MD023: true +### +# MD024/no-duplicate-heading : Multiple headings with the same content : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md024.md +MD024: + ### + # Only check sibling headings + siblings_only: false +### +# MD025/single-title/single-h1 : Multiple top-level headings in the same document : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md025.md +MD025: + ### + # RegExp for matching title in front matter + front_matter_title: "^\\s*title\\s*[:=]" + ### + # Heading level + level: 1 +### +# MD026/no-trailing-punctuation : Trailing punctuation in heading : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md026.md +MD026: + ### + # Punctuation characters + punctuation: ".,;:!。，；：！" +### +# MD027/no-multiple-space-blockquote : Multiple spaces after blockquote symbol : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md027.md +MD027: true +### +# MD028/no-blanks-blockquote : Blank line inside blockquote : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md028.md +MD028: true +### +# MD029/ol-prefix : Ordered list item prefix : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md029.md +MD029: + ### + # List style + style: "one_or_ordered" +### +# MD030/list-marker-space : Spaces after list markers : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md030.md +MD030: + ### + # Spaces for multi-line ordered list items + ol_multi: 1 + ### + # Spaces for single-line ordered list items + ol_single: 1 + ### + # Spaces for multi-line unordered list items + ul_multi: 1 + ### + # Spaces for single-line unordered list items + ul_single: 1 +### +# MD031/blanks-around-fences : Fenced code blocks should be surrounded by blank lines : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md031.md +MD031: + ### + # Include list items + list_items: true +### +# MD032/blanks-around-lists : Lists should be surrounded by blank lines : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md032.md +MD032: true +### +# MD033/no-inline-html : Inline HTML : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md033.md +MD033: + ### + # Allowed elements + allowed_elements: [] +### +# MD034/no-bare-urls : Bare URL used : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md034.md +MD034: true +### +# MD035/hr-style : Horizontal rule style : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md035.md +MD035: + ### + # Horizontal rule style + style: "consistent" +### +# MD036/no-emphasis-as-heading : Emphasis used instead of a heading : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md036.md +MD036: + ### + # Punctuation characters + punctuation: ".,;:!?。，；：！？" +### +# MD037/no-space-in-emphasis : Spaces inside emphasis markers : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md037.md +MD037: true +### +# MD038/no-space-in-code : Spaces inside code span elements : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md038.md +MD038: true +### +# MD039/no-space-in-links : Spaces inside link text : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md039.md +MD039: true +### +# MD040/fenced-code-language : Fenced code blocks should have a language specified : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md040.md +MD040: + ### + # List of languages + allowed_languages: [] + ### + # Require language only + language_only: false +### +# MD041/first-line-heading/first-line-h1 : First line in a file should be a top-level heading : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md041.md +MD041: + ### + # RegExp for matching title in front matter + front_matter_title: "^\\s*title\\s*[:=]" + ### + # Heading level + level: 1 +### +# MD042/no-empty-links : No empty links : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md042.md +MD042: true +### +# MD043/required-headings : Required heading structure : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md043.md +MD043: + ### + # List of headings + headings: ["*"] + ### + # Match case of headings + match_case: false +### +# MD044/proper-names : Proper names should have the correct capitalization : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md044.md +MD044: + ### + # Include code blocks + code_blocks: true + ### + # Include HTML elements + html_elements: true + ### + # List of proper names + names: [] +### +# MD045/no-alt-text : Images should have alternate text (alt text) : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md045.md +MD045: true +### +# MD046/code-block-style : Code block style : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md046.md +MD046: + ### + # Block style + style: "consistent" +### +# MD047/single-trailing-newline : Files should end with a single newline character : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md047.md +MD047: true +### +# MD048/code-fence-style : Code fence style : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md048.md +MD048: + # Code fence style + style: "consistent" +### +# MD049/emphasis-style : Emphasis style : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md049.md +MD049: + ### + # Emphasis style + style: "consistent" +### +# MD050/strong-style : Strong style : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md050.md +MD050: + ### + # Strong style + style: "consistent" +### +# MD051/link-fragments : Link fragments should be valid : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md051.md +MD051: true +### +# MD052/reference-links-images : Reference links and images should use a label that is defined : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md052.md +MD052: + ### + # Include shortcut syntax + shortcut_syntax: false +### +# MD053/link-image-reference-definitions : Link and image reference definitions should be needed : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md053.md +MD053: + ### + # Ignored definitions + ignored_definitions: + - "//" +### +# MD054/link-image-style : Link and image style : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md054.md +MD054: + ### + # Allow autolinks + autolink: true + ### + # Allow collapsed reference links and images + collapsed: true + ### + # Allow full reference links and images + full: true + ### + # Allow inline links and images + inline: true + ### + # Allow shortcut reference links and images + shortcut: true + ### + # Allow URLs as inline links + url_inline: true +### +# MD055/table-pipe-style : Table pipe style : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md055.md +MD055: + ### + # Table pipe style + style: "consistent" +### +# MD056/table-column-count : Table column count : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md056.md +MD056: true diff --git a/Pipfile b/Pipfile index 1df1052..165c18b 100644 --- a/Pipfile +++ b/Pipfile @@ -23,10 +23,10 @@ myst-parser = {extras = ["linkify"], version = "*"} sphinx = "*" sphinx-ansible = "*" sphinx-autobuild = "*" +sphinx-book-theme = "*" sphinx-copybutton = "*" sphinx-design = "*" sphinx-favicon = "*" -sphinx-nefertiti = "*" sphinx-pyscript = "*" sphinx-tippy = "*" sphinx-togglebutton = "*" diff --git a/Pipfile.lock b/Pipfile.lock index a5b5fea..f32722e 100644 --- a/Pipfile.lock +++ b/Pipfile.lock @@ -1,7 +1,7 @@ { "_meta": { "hash": { - "sha256": "9a5b6eca15206d59ac5bc65dd22ede63cf54006403977e1498f483f03e5a6a72" + "sha256": "67b0b8edeb783272a33ef8a9dd095aea3e9c424d9efe3a0a0aa1a737a409482d" }, "pipfile-spec": 6, "requires": {}, @@ -1434,6 +1434,14 @@ } }, "docs": { + "accessible-pygments": { + "hashes": [ + "sha256:40918d3e6a2b619ad424cb91e556bd3bd8865443d9f22f1dcdf79e33c8046872", + "sha256:88ae3211e68a1d0b011504b2ffc1691feafce124b845bd072ab6f9f66f34d4b7" + ], + "markers": "python_version >= '3.9'", + "version": "==0.0.5" + }, "alabaster": { "hashes": [ "sha256:75a8b99c28a5dad50dd7f8ccdd447a121ddb3892da9e53d1ca5cca3106d58d65", @@ -1771,6 +1779,14 @@ ], "version": "==0.7.0" }, + "pydata-sphinx-theme": { + "hashes": [ + "sha256:2136ad0e9500d0949f96167e63f3e298620040aea8f9c74621959eda5d4cf8e6", + "sha256:7762ec0ac59df3acecf49fd2f889e1b4565dbce8b88b2e29ee06fdd90645a06d" + ], + "markers": "python_version >= '3.9'", + "version": "==0.15.4" + }, "pygments": { "hashes": [ "sha256:786ff802f32e91311bff3889f6e9a86e81505fe99f2735bb6d60ae0c5004f199", @@ -1917,6 +1933,15 @@ "markers": "python_version >= '3.9'", "version": "==2024.4.16" }, + "sphinx-book-theme": { + "hashes": [ + "sha256:1f25483b1846cb3d353a6bc61b3b45b031f4acf845665d7da90e01ae0aef5b4d", + "sha256:a554a9a7ac3881979a87a2b10f633aa2a5706e72218a10f71be38b3c9e831ae9" + ], + "index": "pypi", + "markers": "python_version >= '3.9'", + "version": "==1.1.3" + }, "sphinx-copybutton": { "hashes": [ "sha256:4cf17c82fb9646d1bc9ca92ac280813a3b605d8c421225fd9913154103ee1fbd", @@ -1944,14 +1969,6 @@ "markers": "python_version >= '3.7'", "version": "==1.0.1" }, - "sphinx-nefertiti": { - "hashes": [ - "sha256:d66395c81add1606850d2d1189d189da88c6793423c213a035469360913700ee", - "sha256:eedfe079288678f53e0a564360e89bd8077d4325ac279ebb4c06e9adbb80e9f4" - ], - "index": "pypi", - "version": "==0.3.4" - }, "sphinx-notfound-page": { "hashes": [ "sha256:7b2759ca79cbaa44422325f540b91542b1ce411cd31217c20cd6ba1e6cffb5ec", @@ -2079,6 +2096,14 @@ "markers": "python_version >= '3.8'", "version": "==0.38.0" }, + "typing-extensions": { + "hashes": [ + "sha256:04e5ca0351e0f3f85c6853954072df659d0d13fac324d0072316b67d7794700d", + "sha256:1a7ead55c7e559dd4dee8856e3a88b41225abfe1ce8df57b7c13915fe121ffb8" + ], + "markers": "python_version >= '3.8'", + "version": "==4.12.2" + }, "uc-micro-py": { "hashes": [ "sha256:d321b92cff673ec58027c04015fcaa8bb1e005478643ff4a500882eaab88c48a", diff --git a/cicd.md b/cicd.md index b954d34..197a6e8 100644 --- a/cicd.md +++ b/cicd.md @@ -1,4 +1,5 @@ --- + abstract: Basic information about the CI/CD processes in this repo. authors: Xander Harris date: 2024-02-19 diff --git a/conf.py b/conf.py index 1b71358..fbe2c81 100644 --- a/conf.py +++ b/conf.py @@ -66,12 +66,11 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output html_static_path = ['_static'] -html_theme = 'sphinx_nefertiti' +html_theme = 'sphinx_book_theme' html_theme_options = { 'logo': 'img/ansible.png', - 'repository_url': 'https://github.com/edwardtheharris/ansible-k8s-ca', - 'repository_name': 'ansible k8s ca', - "style": "blue", + "repository_url": "https://github.com/edwardtheharris/ansible-kcp", + "use_repository_button": True, } myst_dmath_double_inline = True myst_enable_extensions = [ diff --git a/index.md b/index.md index 29dbafd..c95a3fa 100644 --- a/index.md +++ b/index.md @@ -1,15 +1,17 @@ --- abstract: This is a collection of Ansible playbooks that will create a CA usable for Kubernetes and etcd clusters. -authors: Xander Harris +authors: + - name: Xander Harris + email: xandertheharris@gmail.com date: 2024-03-08 title: Ansible CA --- -![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/edwardtheharris/ansible-k8s-ca/ansible.yml?branch=main&style=flat-square&logo=ansible&label=Ansible%20Lint) -![GitHub CodeQL](https://img.shields.io/github/actions/workflow/status/edwardtheharris/ansible-k8s-ca/codeql.yml?branch=main&style=flat-square&logo=githubactions&label=CodeQL) -[![GitHub Pages Status](https://img.shields.io/github/actions/workflow/status/edwardtheharris/ansible-k8s-ca/pages.yml?branch=main&style=flat-square&logo=githubpages&label=GitHub%20Pages)](https://edwardtheharris.github.io/ansible-k8s-ca/) -![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/edwardtheharris/ansible-k8s-ca/shell.yml?branch=main&style=flat-square&logo=gnubash&label=ShellCheck) +![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/edwardtheharris/ansible-kcp/ansible.yml?branch=main&style=flat-square&logo=ansible&label=Ansible%20Lint) +![GitHub CodeQL](https://img.shields.io/github/actions/workflow/status/edwardtheharris/ansible-kcp/codeql.yml?branch=main&style=flat-square&logo=githubactions&label=CodeQL) +[![GitHub Pages Status](https://img.shields.io/github/actions/workflow/status/edwardtheharris/ansible-kcp/pages.yml?branch=main&style=flat-square&logo=githubpages&label=GitHub%20Pages)](https://edwardtheharris.github.io/ansible-kcp/) +![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/edwardtheharris/ansible-kcp/shell.yml?branch=main&style=flat-square&logo=gnubash&label=ShellCheck) ## Playbooks diff --git a/license.md b/license.md index bfde78d..4518e56 100644 --- a/license.md +++ b/license.md @@ -1,4 +1,5 @@ --- + abstract: The license, or lack thereof. date: 2024-03-08 title: Unlicensed diff --git a/readme.md b/readme.md index d00c5e4..8563f39 100644 --- a/readme.md +++ b/readme.md @@ -1,4 +1,5 @@ --- + abstract: The readme for some Ansible playbooks that have the goal of deploying a Root Certificate Authority to a Linux host. authors: Xander Harris @@ -27,27 +28,12 @@ is responsible for authentication, file, and routing services. ```{code-block} yaml :caption: /etc/ansible/hosts.yaml -dc: - hosts: - dc01.example.com: - ansible_user: user - dc02.example.com: - ansible_user: user -np: - hosts: - napalm.example.com: - ansible_user: user kcp: hosts: kcp01.example.com: - ansible_user: user + ansible_user: 1.2.3.4 kcp02.example.com: - ansible_user: user -ca: - hosts: - ca.example.com: - ansible_user: user - secret_ca_passphrase: secret-ca-passphrase + ansible_user: 1.2.3.4 ``` ```{toctree} diff --git a/roles/kcp/index.md b/roles/kcp/index.md index 00ead21..079a9be 100644 --- a/roles/kcp/index.md +++ b/roles/kcp/index.md @@ -1,4 +1,5 @@ --- + abstract: This roles installs a Kubernetes Control Plane Node. authors: Xander Harris date: 2024-03-01 diff --git a/security.md b/security.md index 6d47f5a..134ac58 100644 --- a/security.md +++ b/security.md @@ -1,4 +1,5 @@ --- + abstract: This is the security policy for these playbooks, such as they are. authors: Xander Harris date: 2024-03-08