Merge pull request #8 from febus982/docs-improvements

Docs improvements

Author: febus982

README.md

@@ -29,7 +29,7 @@ It is configured with all the following features:
 
 This project doesn't currently use [tox](https://tox.wiki/en/4.11.4/index.html) or other matrix
 testing utilities. I prefer to run the tests only against the latest python locally, and run 
-previous python versions directly in the CI pipeline to catch these bugs.
+previous python versions directly in the CI pipeline.
 
 ## How to use this repository template to create a new package
 
@@ -41,8 +41,8 @@ previous python versions directly in the CI pipeline to catch these bugs.
     * Owner: The github repository owner (in this case `febus982`)
     * Repository name: The github repository name (in this case `bootstrap-python-package`)
     * Workflow name: `release.yml`
-* Create a GitHub Actions secret named `CODECLIMATE_REPORTER_ID` (at URL https://github.com/GITHUB_NAME_OR_ORGANIZATION/GITHUB_REPOSITORY/settings/secrets/actions) 
-  containing the codeclimate reporter id (you can find it at https://codeclimate.com/repos/YOUR_REPO_ID/settings/test_reporter).
+* Create a GitHub Actions secret named `CODECLIMATE_REPORTER_ID` (at URL `https://github.com/GITHUB_NAME_OR_ORGANIZATION/GITHUB_REPOSITORY/settings/secrets/actions`) 
+  containing the codeclimate reporter id (you can find it at `https://codeclimate.com/repos/YOUR_REPO_ID/settings/test_reporter`).
   If you don't want to use CodeClimate just delete `workflows/python-quality.yml`.
 * Update the badges in `README.md`! (check [shields.io](https://shields.io/) for extra badges)
 * Setup local development:
@@ -51,7 +51,7 @@ previous python versions directly in the CI pipeline to catch these bugs.
     * Install dev dependencies with `make dev-dependencies`
 * Setup GitHub pages (this need local development setup):
     * Initialise documentation branch `poetry run mike deploy dev latest --update-aliases --push`
-    * Enable GitHub Actions for GitHub Pages (at URL https://github.com/GITHUB_NAME_OR_ORGANIZATION/GITHUB_REPOSITORY/settings/pages) 
+    * Configure GitHub Pages to deploy from the `gh-pages` branch (at URL `https://github.com/GITHUB_NAME_OR_ORGANIZATION/GITHUB_REPOSITORY/settings/pages`) 
 
 **IMPORTANT:** The repository is configured to deploy on the [test PyPI repository](https://test.pypi.org/).
 It's strongly recommended to create the project in the [test PyPI repository](https://test.pypi.org/) and test
@@ -64,8 +64,10 @@ This setup uses [poetry-dynamic-versioning](https://github.com/mtkennerly/poetry
 This means it's not necessary to commit the version in the code but the CI pipeline
 will infer it from the git tag.
 
-To release a new version, just create a new release in the github repository. It will
-create a new tag and do all the magic.
+To release a new version, just create a new release and tag in the GitHub repository, to:
+
+* Build and deploy the python package to PyPI
+* Build and deploy a new version of the documentation to GitHub pages
 
 **IMPORTANT:** The default configuration requires the release name and the tag to follow
 the convention `vX.X.X` (semantic versioning preceded by lowercase `v`). It will publish

docs/index.md

@@ -15,7 +15,7 @@ It is configured with all the following features:
 
 This project doesn't currently use [tox](https://tox.wiki/en/4.11.4/index.html) or other matrix
 testing utilities. I prefer to run the tests only against the latest python locally, and run 
-previous python versions directly in the CI pipeline to catch these bugs.
+previous python versions directly in the CI pipeline.
 
 ## How to use this repository template to create a new package
 
@@ -27,17 +27,17 @@ previous python versions directly in the CI pipeline to catch these bugs.
     * Owner: The github repository owner (in this case `febus982`)
     * Repository name: The github repository name (in this case `bootstrap-python-package`)
     * Workflow name: `release.yml`
-* Create a GitHub Actions secret named `CODECLIMATE_REPORTER_ID` (at URL https://github.com/GITHUB_NAME_OR_ORGANIZATION/GITHUB_REPOSITORY/settings/secrets/actions) 
-  containing the codeclimate reporter id (you can find it at https://codeclimate.com/repos/YOUR_REPO_ID/settings/test_reporter).
-  If you don't want to use CodeClimate just delete `workflows/python-quality.yml`.
-* Update the badges in `README.md`! (check [shields.io](https://shields.io/) for extra badges)
 * Setup local development:
     * Clone the repository
     * Install poetry `pip install poetry`
     * Install dev dependencies with `make dev-dependencies`
 * Setup GitHub pages (this need local development setup):
     * Initialise documentation branch `poetry run mike deploy dev latest --update-aliases --push`
-    * Enable GitHub Actions for GitHub Pages (at URL https://github.com/GITHUB_NAME_OR_ORGANIZATION/GITHUB_REPOSITORY/settings/pages) 
+    * Configure GitHub Pages to deploy from the `gh-pages` branch (at URL `https://github.com/GITHUB_NAME_OR_ORGANIZATION/GITHUB_REPOSITORY/settings/pages`) 
+* Create a GitHub Actions secret named `CODECLIMATE_REPORTER_ID` (at URL `https://github.com/GITHUB_NAME_OR_ORGANIZATION/GITHUB_REPOSITORY/settings/secrets/actions`) 
+  containing the codeclimate reporter id (you can find it at `https://codeclimate.com/repos/YOUR_REPO_ID/settings/test_reporter`).
+  If you don't want to use CodeClimate just delete `workflows/python-quality.yml`.
+* Update the badges in `README.md`! (check [shields.io](https://shields.io/) for extra badges)
 
 **IMPORTANT:** The repository is configured to deploy on the [test PyPI repository](https://test.pypi.org/).
 It's strongly recommended to create the project in the [test PyPI repository](https://test.pypi.org/) and test
@@ -50,8 +50,10 @@ This setup uses [poetry-dynamic-versioning](https://github.com/mtkennerly/poetry
 This means it's not necessary to commit the version in the code but the CI pipeline
 will infer it from the git tag.
 
-To release a new version, just create a new release in the github repository. It will
-create a new tag and do all the magic.
+To release a new version, just create a new release and tag in the GitHub repository, to:
+
+* Build and deploy the python package to PyPI
+* Build and deploy a new version of the documentation to GitHub pages
 
 **IMPORTANT:** The default configuration requires the release name and the tag to follow
 the convention `vX.X.X` (semantic versioning preceded by lowercase `v`). It will publish

mkdocs-overrides/main.html

@@ -0,0 +1,8 @@
+{% extends "base.html" %}
+
+{% block outdated %}
+  You're not viewing the latest version.
+  <a href="{{ '../' ~ base_url }}">
+    <strong>Click here to go to latest.</strong>
+  </a>
+{% endblock %}

mkdocs.yml

@@ -13,6 +13,7 @@ plugins:
 
 theme:
   name: material
+  custom_dir: mkdocs-overrides
   features:
     - navigation.expand
     - navigation.top
@@ -21,13 +22,15 @@ theme:
   palette:
     # Palette toggle for light mode
     - scheme: default
+      media: "(prefers-color-scheme: light)"
       primary: teal
       toggle:
         icon: material/brightness-7
         name: Switch to dark mode
 
     # Palette toggle for dark mode
     - scheme: slate
+      media: "(prefers-color-scheme: dark)"
       primary: teal
       toggle:
         icon: material/brightness-4
@@ -39,6 +42,7 @@ extra:
       link: https://www.linkedin.com/in/federico-b-a0b78232
   version:
     provider: mike
+    default: stable
 
 nav:
   - Home: index.md