diff --git a/.github/styles/config/vocabularies/Codacy/accept.txt b/.github/styles/config/vocabularies/Codacy/accept.txt index 1a712e4dab..3adaadcc70 100644 --- a/.github/styles/config/vocabularies/Codacy/accept.txt +++ b/.github/styles/config/vocabularies/Codacy/accept.txt @@ -46,6 +46,8 @@ Hadolint Hardcoded hostname hotfix +hotfixes +Ionicons Jira jq jscpd @@ -69,6 +71,7 @@ PVC Pylint remark-lint Revive +Roboto Rollout rollout RuboCop @@ -85,6 +88,7 @@ SpotBugs SQLint Staticcheck Stylelint +SVGs SwiftLint Tailor tooltip @@ -94,7 +98,12 @@ TSQLLint unassigns unfollow unignore +Unignoring +unignoring +unignored +unreferenced vacuumdb +vendored Visualforce VSCode webserver diff --git a/.gitignore b/.gitignore index c8d5cc9e04..32d3851084 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,10 @@ # MkDocs build dir site/ +# Python bytecode generated while running MkDocs hooks +__pycache__/ +*.py[cod] + # OS generated files .DS_Store @@ -28,4 +32,3 @@ tools/*.csv #Ignore vscode AI rules .github/instructions/codacy.instructions.md - diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e36cc8569c..31a7cc7516 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,6 +3,7 @@ You're welcome to make fixes and changes to the documentation. Here are a few steps to get you going: - [Authoring documentation pages](#authoring-documentation-pages) +- [Working on the documentation theme](#working-on-the-documentation-theme) - [Releasing a new Codacy Self-hosted documentation version](#releasing-a-new-codacy-self-hosted-documentation-version) - [Updating an existing Codacy Self-hosted documentation version](#updating-an-existing-codacy-self-hosted-documentation-version) - [Applying documentation hotfixes to existing chart releases](#applying-documentation-hotfixes-to-existing-chart-releases) @@ -39,6 +40,75 @@ You're welcome to make fixes and changes to the documentation. Here are a few st mkdocs serve ``` +### Working on the documentation theme + +The documentation uses the installed `mkdocs-material` package with a small, +Codacy-owned theme layer in [`theme/`](theme/). This is +the current theme source of truth. Don't copy, modify, or renew the legacy +`submodules/codacy-mkdocs-material` clone when changing this site's theme. + +The theme is intentionally plain CSS and minimal Jinja overrides: + +- [`theme/stylesheets/tokens.css`](theme/stylesheets/tokens.css) + defines the Codacy color tokens and Material color mappings. +- The visual styling lives in [`theme/stylesheets/`](theme/stylesheets/), + split by concern (`base`, `header`, `navigation`, `content`, `home`, + `footer`, `layout`, `responsive`) and loaded in that order via `extra_css`. + The files are plain, comment-free CSS; keep a rule in the file that matches + its concern, and keep `extra_css` in cascade order (it layers over the + Material package, so order and specificity are what make an override win). +- [`theme/main.html`](theme/main.html) and its + [`partials/`](theme/partials/) retain only the overrides and + integrations that Codacy needs. +- [`mkdocs.yml`](mkdocs.yml) connects this layer through `theme.custom_dir` + and loads the small supporting browser scripts and stylesheets. + +Several partials under [`theme/partials/`](theme/partials/) (for example +`nav-item.html`, `header.html`, `search.html`, and `toc.html`) are derived from +the equivalent templates in the `mkdocs-material` version pinned in +[`requirements.txt`](requirements.txt) and then trimmed to Codacy's needs. They +are coupled to that version's markup, CSS class names, and JavaScript component +contracts, so **bumping `mkdocs-material` requires re-diffing these partials +against the new upstream templates** and re-testing search, the palette toggle, +and navigation. Pin the package to an exact version and treat an upgrade as a +deliberate task, not an incidental dependency bump. + +There is no front-end build step. Edit the CSS, Jinja partials, or supporting +JavaScript directly, then use the normal MkDocs preview: + +```bash +mkdocs serve +``` + +The theme self-hosts the Inter and Roboto Mono font files under +`theme/assets/fonts/`; it doesn't contact a third-party font service. Keep the +font license beside those assets when updating them. + +Icons are provided by Ionicons, also vendored locally under +`theme/assets/vendor/ionicons/` (the runtime loader plus only the SVGs the theme +references) so the docs render fully offline and don't depend on a third-party +CDN—this matters for Self-hosted installations. When you add an +`` or a `sidebar_icons` entry, copy the matching +`svg/.svg` from the Ionicons package into that folder; unreferenced icons +are intentionally not vendored. Keep the Ionicons license beside the assets. + +The `theme/hooks/image_metadata.py` hook adds intrinsic dimensions and safe +loading hints to local documentation images at build time. Authors normally use +standard Markdown image syntax; explicit HTML image attributes are preserved +when a page needs an exception. + +Before opening a pull request that changes the theme, build with warnings +treated as errors and check representative pages in the local preview: + +```bash +mkdocs build --strict +``` + +Check a Cloud page and, when relevant, a Self-hosted page. Also check light and +dark color schemes, desktop and narrow mobile widths, search, the version +picker, and any changed content component. Preserve analytics, feedback, +preview and Self-hosted notices, source metadata, and existing URLs. + ### Markdown conventions Follow these Markdown conventions when editing the documentation: diff --git a/docs/account/emails.md b/docs/account/emails.md index be0bad6bf5..749da99675 100644 --- a/docs/account/emails.md +++ b/docs/account/emails.md @@ -8,7 +8,7 @@ To manage the email addresses associated with your account and your email notifi Codacy automatically links to your Codacy account the email addresses from the Git provider associated with your current session. On the **Emails** page, you can verify which email addresses are linked to your Codacy account. -!!! notes +!!! note - For **GitHub**, if you have [email privacy enabled](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address?platform=mac#about-commit-email-addresses) on the provider, Codacy doesn't show your private emails and uses another available email address when displaying your personal details on lists, search filters, or activity. - Codacy doesn't allow you to have one email associated with more than one GitHub account. You can manage your [associated emails in the provider GitHub](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/adding-an-email-address-to-your-github-account). diff --git a/docs/assets/images/codacy-docs-logo-light.svg b/docs/assets/images/codacy-docs-logo-light.svg new file mode 100644 index 0000000000..2c5cfc0408 --- /dev/null +++ b/docs/assets/images/codacy-docs-logo-light.svg @@ -0,0 +1 @@ + diff --git a/docs/assets/images/codacy-docs-logo.svg b/docs/assets/images/codacy-docs-logo.svg index 12cd5df14e..6728340b6e 100644 --- a/docs/assets/images/codacy-docs-logo.svg +++ b/docs/assets/images/codacy-docs-logo.svg @@ -1 +1 @@ - \ No newline at end of file + diff --git a/docs/assets/includes/nav-multistep-quickstart.md b/docs/assets/includes/nav-multistep-quickstart.md index 4445e94012..bb5ba5788f 100644 --- a/docs/assets/includes/nav-multistep-quickstart.md +++ b/docs/assets/includes/nav-multistep-quickstart.md @@ -1,33 +1,33 @@ -