## MkDocs - https://www.mkdocs.org/ - https://github.com/mkdocs/mkdocs - https://github.com/mkdocs/catalog - https://repology.org/badge/vertical-allrepos/python:mkdocs.svg - https://repology.org/badge/vertical-allrepos/mkdocs.svg - Used by [substrate-interface](https://polkascan.github.io/py-substrate-interface/), [Textual](https://textual.textualize.io/), [Pipx](https://pypa.github.io/pipx/), and [Ruff](https://docs.astral.sh/ruff/) - Allows to build markdown docs from the repository - Very simple static framework website written in Python ## Tasks ### MkDocs initial set-up - [x] Read the User Guide - [x] `pyproject.toml`: Introduce `mkdocs` dependencies in `doc` group - [x] Set-up initial project `mkdocs.yml` - [x] Move `md` files to default `docs` directory - [x] Set symlinks for changelog, contributing(, readme) - [x] Choose theme: [material](https://squidfunk.github.io/mkdocs-material/) - [x] Set favicon - [x] Night/day switch - [x] Set-up navigation with current content ### Deployment ```yaml poetry install --only docs poetry run mkdocs build -d public ``` - [x] Support website/documentation per releases and development one with [Mike](https://github.com/jimporter/mike): - Drop-down support to switch between ie `v0.12` and `main` - [x] Mike git commits changes to `pages` branch. Add `.gitlab-ci.yml` on this branch to publish the website and its’s multiple versions (no need schedule) - [x] On `pages` branch: basic `.gitlab-ci.yml` to copy the content into a `public` directory and publish to GitLab Pages via a `pages` job - [GitLab Pages implementation](https://gitlab.com/groups/gitlab-org/-/epics/10914), will come later in the Community edition - https://pypi.org/project/lightweight-versioned-gitlab-pages/ - https://stackoverflow.com/questions/55596789/deploying-gitlab-pages-for-different-branches/58915486#58915486 - [x] Version path `/0.12` issue with GitLab/Nginx deployment for hard-coded links - We should always use a relative link as stated in: [GH issue](https://github.com/jimporter/mike/issues/115), [MkDocs doc](https://www.mkdocs.org/user-guide/writing-your-docs/#linking-to-pages) - not `[](/path.md)` (absolute breaks version). `[](path.md)` if in the same directory otherwise `[](./path.md)` - only on `main` branch and `tag`? Set `RELEASE` variable to `0.12` or to `0.20-dev`. - how to handle the coverage and website deployments? - [`mkdocs-coverage`](https://github.com/pawamoy/mkdocs-coverage) - `website` job [`needs:`](https://docs.gitlab.com/ee/ci/yaml/#needs) `tests:3.12:cov` job artifact - https://stackoverflow.com/a/64008569 - handle coverage display on `main` branch, don’t display `Coverage` tab when on release branch? Always display. - [x] Protect `pages` branch - [x] Update coverage badge link to website coverage path - [x] Adapt GitLab Pages deployment: Ansible role, now from Silkaj repository - NixOS configuration works with three paths `clients/python/silkaj` ### Document contribution - [x] How to install `mkdocs`, serve the docs, build locally - Link mkdocs, material, mike, coverage, gitlab … docs ### Set up structure and use existing content - [x] Fix `mkdocs serve` warnings - [x] Update links in release notes, contributing(, readme) - [x] `README.md` `CONTRIBUTING.md`: update links to the URL of this website - [x] Create index/main page inspired from [Textual one](https://github.com/Textualize/textual/blob/d958f5bf778a3807ba75884fe15134c6dc294460/docs/index.md) - [x] Clean and proofread current documentation - move container usage (and poetry installation) to install section? Advanced installation, somehow contributing stuff. Nope? - [x] enable syntax highlight, fix code block where we don’t want it - [x] enable code block copy where needed - [x] Id anchors in changelog - [x] Move `CHANGELOG.md` to `docs/changelog.md`, with the `{ id=0.11.0 }` it might get ugly looking at it on GitLab. Same for `CONTRIBUTING.md`, Drop them from GitLab "syntax", not sure for the logos - [x] create `CHANGELOG.md` and `CONTRIBUTING.md` referring to those pages on the website - [x] structure `docs` folder: `usage`, `contributing` - [x] Introduce [`mdformat-mkdocs`](https://github.com/KyleKing/mdformat-mkdocs) to format with four spaces bullet points - [x] Keep `mike` `prefix_path` to `public`, serving to http://localhost:8000/pages (needs doc precision) or select `version.json`, `latest`, and `0.12` items in the artifact - [x] Integrate generated coverage with [`mkdocs-coverage`](https://github.com/pawamoy/mkdocs-coverage) - [x] Changelog with [`mkdocs-gitlab-plugin`](https://pypi.org/project/mkdocs-gitlab-plugin/): - #494+ - [x] Blog tab containing releases notes: - [x] Move `releases_notes` directory in `docs/blog` directory - [x] Set up built-in `mkdocs-material` blog (not [`mkdocs-blogging-plugin`](https://github.com/liang2kl/mkdocs-blogging-plugin)) - Yaml frontmatter kept: [`mdformat-frontmatter`](https://github.com/butler54/mdformat-frontmatter) - [x] Add [excerpts](https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#adding-an-excerpt) - [x] Add [authors](https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#adding-authors) - [x] Local author profile picture not available from archive, category slug, set up url formats - [ ] Issue to display local avatar: relative not working between `mkdocs-material` and `mike` - Found a "dirty" hack which works with `mike`, but not when serving with `mkdocs`, to be investigated further later - [x] Set up categories/tags for the releases and RC testing to separated them - [x] [Add badge](https://squidfunk.github.io/mkdocs-material/blog/2023/11/30/adding-a-badge-to-your-project/) to readme and GitLab repo badges - [x] [disable fonts coming from Google gstatic](https://github.com/squidfunk/mkdocs-material/issues/739#issuecomment-377978270) - [x] Retrieve valuable content from current and Vue websites (no real value left: intro text maybe?) - [x] Activate [search engine](https://squidfunk.github.io/mkdocs-material/plugins/search/) ### Archive current websites - [x] Archive [two other websites repositories](https://git.duniter.org/websites) - https://git.duniter.org/websites/silkaj_website - https://git.duniter.org/websites/doc_silkaj Set them as archives. Visible in [the archived tab](https://git.duniter.org/groups/websites/-/archived). Redirect, saying that the website is now in Silkaj repository Thank Manutopik for the Vue website solution which wasn’t retained. I prefer MkDocs: it’s written in Python, it’s simple, (no JS), I have full control over it ### Finalization - [x] Clean local history - [x] push changes - [x] protect `pages` branch - [x] Check the CI manages to publish on `pages` branch - a commit is added to `pages` branch once a `.py` or `docs/**.md` file changes. When there is no changes, the changelog has its date updated. - schedule pipeline won’t have the requirements to trigger `website` job, since no `.py` nor `.md` file was changed. Let’s see how it goes. There is no `website` job, and `pages` branch does not get a new "empty" commit. Let’s not create lot’s of useless commits on `pages` branch. - [x] Remove commented line in CI, so it only pushed from `main` branch - [x] Review changes - [x] Push clean `pages` branch - [x] Switch Infra config of https://silkaj.duniter.org to this website: admins/duniter-infra!101