Skip to content

Commit

Permalink
docs: several docs improvements
Browse files Browse the repository at this point in the history
  • Loading branch information
kvanzuijlen committed Apr 9, 2024
1 parent efc0734 commit f93b6c2
Show file tree
Hide file tree
Showing 12 changed files with 82 additions and 26 deletions.
3 changes: 3 additions & 0 deletions .github/workflows/ci.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -122,6 +122,8 @@ jobs:
run: poetry run mike deploy --push main
env:
GOOGLE_ANALYTICS_KEY: ${{ secrets.GOOGLE_ANALYTICS_KEY }}
MKDOCS_GIT_COMMITTERS_APIKEY: ${{ github.token }}
EXCLUDE_SHIELDS_IO_PRIVACY: true
- name: Deploy release docs
if: ${{ github.event_name == 'workflow_dispatch' && needs.release.result == 'success' }}
run: |-
Expand All @@ -130,3 +132,4 @@ jobs:
poetry run mike deploy --push --update-aliases ${{ needs.release.outputs.tag_name }} latest
env:
GOOGLE_ANALYTICS_KEY: ${{ secrets.GOOGLE_ANALYTICS_KEY }}
MKDOCS_GIT_COMMITTERS_APIKEY: ${{ github.token }}
5 changes: 3 additions & 2 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
.idea/
/.idea/

dist/
/dist/

# Ignore version binaries in root project-folder
/version*
/.cache/
/site/
1 change: 1 addition & 0 deletions .prettierignore
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
/docs/includes/abbreviations.md
1 change: 0 additions & 1 deletion CNAME

This file was deleted.

14 changes: 6 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,17 +1,15 @@
<div style="text-align: center">
<!-- # --8<-- [start:description] -->
<!--suppress HtmlDeprecatedAttribute -->
<div align="center">
<div>
<img alt="logo" src="./docs/assets/images/logo.svg"/>
<img alt="logo" data-is-relative="true" src="./docs/assets/images/logo.svg"/>
</div>
</div>

<!-- # --8<-- [start:description] -->
<div style="text-align: center">
<h1>Version</h1>
<img alt="GitHub Tag" src="https://img.shields.io/github/v/tag/version-cli/version?style=for-the-badge&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGVuYWJsZS1iYWNrZ3JvdW5kPSJuZXcgMCAwIDI0IDI0IiBoZWlnaHQ9IjI0cHgiIHZpZXdCb3g9IjAgMCAyNCAyNCIgd2lkdGg9IjI0cHgiIGZpbGw9IiNGRkZGRkYiPjxnPjxwYXRoIGQ9Ik0wLDBoMjR2MjRIMFYweiIgZmlsbD0ibm9uZSIvPjwvZz48Zz48Zz48cGF0aCBkPSJNMjEuNDEsMTEuNDFsLTguODMtOC44M0MxMi4yMSwyLjIxLDExLjcsMiwxMS4xNywySDRDMi45LDIsMiwyLjksMiw0djcuMTdjMCwwLjUzLDAuMjEsMS4wNCwwLjU5LDEuNDFsOC44Myw4LjgzIGMwLjc4LDAuNzgsMi4wNSwwLjc4LDIuODMsMGw3LjE3LTcuMTdDMjIuMiwxMy40NiwyMi4yLDEyLjIsMjEuNDEsMTEuNDF6IE0xMi44MywyMEw0LDExLjE3VjRoNy4xN0wyMCwxMi44M0wxMi44MywyMHoiLz48Y2lyY2xlIGN4PSI2LjUiIGN5PSI2LjUiIHI9IjEuNSIvPjwvZz48L2c%2BPC9zdmc%2B">
<img alt="GitHub go.mod Go version" src="https://img.shields.io/github/go-mod/go-version/version-cli/version?style=for-the-badge&logo=go&color=00ADD8">
<img alt="GitHub Actions Workflow Status" src="https://img.shields.io/github/actions/workflow/status/version-cli/version/release.yaml?logo=github&style=for-the-badge"/>
<img alt="GitHub Actions Workflow Status" src="https://img.shields.io/github/actions/workflow/status/version-cli/version/ci.yaml?logo=github&style=for-the-badge"/>
<a href="https://sonarcloud.io/summary/new_code?id=version-cli_version"><img alt="Sonar Quality Gate" src="https://img.shields.io/sonar/quality_gate/version-cli_version?server=https%3A%2F%2Fsonarcloud.io&logo=sonarcloud&style=for-the-badge&color=F3702A"/></a>
<a href="https://snyk.io/test/github/version-cli/version"><img alt="Snyk Security" src="https://img.shields.io/badge/monitored-%23914dc2?style=for-the-badge&logo=snyk&label=snyk%20security&color=4C4A73"></a>
<a href="https://snyk.io/test/github/version-cli/version"><img alt="Snyk Security" src="https://img.shields.io/badge/Snyk%20Security-Monitored-4C4A73?style=for-the-badge&logo=snyk"></a>
</div>

`version` is a small cli tool that bumps your version number for you and retrieves the latest version of a specified
Expand Down
4 changes: 2 additions & 2 deletions docs/includes/abbreviations.md
Original file line number Diff line number Diff line change
@@ -1,2 +1,2 @@
_[CLI]: Command Line Interface
_[cli]: Command Line Interface
*[CLI]: Command Line Interface
*[cli]: Command Line Interface
3 changes: 0 additions & 3 deletions docs/index.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,3 @@
<br>
<div style="text-align: center">
<img alt="logo" src="assets/images/logo.svg"/>
</div>

--8<-- "README.md:description"
2 changes: 1 addition & 1 deletion docs/mkdocs-hooks/custom-edit-url.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,4 +3,4 @@
def on_page_context(context, page, **_):
if 'edit_url' in page.meta:
page.edit_url = page.meta['edit_url']
return context
return context
48 changes: 48 additions & 0 deletions docs/mkdocs-hooks/privacy-exclude-shields-io.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
import logging
import os
import re
from urllib.parse import urlparse

import material.plugins.privacy.plugin as privacy
from unittest.mock import patch

from urllib.parse import ParseResult as URL
from mkdocs.structure.files import File
from colorama import Fore, Style

# Set up logging
log = logging.getLogger("mkdocs.material.privacy")


def _is_excluded(self, url: URL, initiator: File | None = None):
if not self._is_external(url):
return True

# Skip if external assets must not be processed
if not self.config.assets:
return True

# If initiator is given, format for printing
via = ""
if initiator:
via = "".join([
Fore.WHITE, Style.DIM,
f"in '{initiator.src_uri}' ",
Style.RESET_ALL
])

# Print warning if fetching is not enabled
if not self.config.assets_fetch:
log.warning(f"External file: {url.geturl()} {via}")
return True

if "img.shields.io" in url.geturl():
return True

# File is not excluded
return False


if os.getenv("EXCLUDE_SHIELDS_IO_PRIVACY") == "true":
# Only exclude shields.io from the privacy plugin if desired (i.e. for the "main" version of docs)
privacy.PrivacyPlugin._is_excluded = _is_excluded
2 changes: 0 additions & 2 deletions docs/mkdocs-hooks/relative-links.py

This file was deleted.

7 changes: 7 additions & 0 deletions docs/mkdocs-hooks/relative-src.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
import re


def on_page_content(html: str, *, page, **_):
if page.file.src_uri == "index.md":
html = html.replace('data-is-relative="true" src="./docs/', 'data-is-relative="true" src="')
return html
18 changes: 11 additions & 7 deletions mkdocs.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ copyright: >
Copyright &copy; 2024 version-cli -
<a href="#__consent">Change cookie settings</a>
strict: true
strict: false

repo_name: version-cli/version
repo_url: https://github.com/version-cli/version/
Expand All @@ -26,6 +26,8 @@ remote_branch: gh-pages

hooks:
- docs/mkdocs-hooks/custom-edit-url.py
- docs/mkdocs-hooks/relative-src.py
- docs/mkdocs-hooks/privacy-exclude-shields-io.py

nav:
- Home: index.md
Expand Down Expand Up @@ -86,16 +88,18 @@ theme:

plugins:
- search
- privacy
- privacy:
assets_expr_map:
".md": "[\"'](https://(?!img\\.shields\\.io)[^\"']+)[\"']"
- social:
cards_layout_options:
background_color: "#D4AA01"
color: "#ffffff"
# - git-revision-date-localized:
# enable_creation_date: true
# - git-committers:
# repository: version-cli/docs
# branch: main
- git-revision-date-localized:
enable_creation_date: true
- git-committers:
repository: version-cli/version
branch: main

extra:
analytics:
Expand Down

0 comments on commit f93b6c2

Please sign in to comment.