Fix and improve documentation and generation (#72)

- Treat mkdocs warnings as errors
- Fix broken docs cross-references
- Adjust docs text to 88 columns
- Fix and sort project tags
- Add instructions to initialize the docs site
- Add advanced usage section pointing to the API
- Add link to Frequenz website
- Reestructure README headers
- Move most of the README to docs/index.md
- Add links to build status, PyPI package and docs website
- Shorten the README and home title
- Update RELEASE_NOTES
- Speed up integration tests

Author: llucax

README.md

@@ -1,135 +1,64 @@
-# Frequenz repository common configuration for Python
+# Frequenz Repository Configuration
 
-This is very opinionated set of tools and configurations to setup a Python
-repository for Frequenz projects.
+[![Build Status](https://github.com/frequenz-floss/frequenz-repo-config-python/actions/workflows/ci.yaml/badge.svg)](https://github.com/frequenz-floss/frequenz-repo-config-python/actions/workflows/ci.yaml)
+[![PyPI Package](https://img.shields.io/pypi/v/frequenz-repo-config)](https://pypi.org/project/frequenz-repo-config/)
+[![Docs](https://img.shields.io/badge/docs-latest-informational)](https://frequenz-floss.github.io/frequenz-repo-config-python/)
 
-If offers:
+## Introduction
 
-* [Cookiecutter] templates for scaffolding new projects
-* Trivial build of `noxfile.py` with some predefined sessions with all common
-  checks.
-* Tools to build protobuf/grpc files as Python, including type information.
+This is a highly opinionated set of tools and configurations to set up a Python
+repository for [Frequenz](https://frequenz.com) projects.
 
+It offers:
 
-[Cookiecutter]: https://cookiecutter.readthedocs.io/en/stable
+* [Cookiecutter] templates for scaffolding new projects
+* Trivial build of `noxfile.py` with some predefined sessions that include all
+  common checks.
+* Tools to build protobuf/grpc files as Python, including type information.
 
-## Start a new project
+## Quick Example
 
-To start a new project you should first [install
+To start a new project, you should first [install
 Cookiecutter](https://cookiecutter.readthedocs.io/en/stable/installation.html).
 It is normally available in any Linux distribution, but some have a very old
-version (for example, Ubuntu/Debian).  You can [check which version your distro
-has in Repology](https://repology.org/project/cookiecutter/versions). You need
-**at least version 2.1.0**.  To make sure to get an up to date version you can
-always uses `pip` and install in a `venv`:
+version (for example, Ubuntu/Debian). You can [check which version your distro
+has on Repology](https://repology.org/project/cookiecutter/versions). You need
+**at least version 2.1.0**. To ensure you get an up-to-date version, you can
+always use `pip` and install it in a `venv`:
 
 ```console
 $ python -m venv cookiecutter
 $ cd cookiecutter
 $ . bin/activate
-[cookiecutter] $ pip install cookiecutter
+(venv) $ pip install cookiecutter
 Collecting cookiecutter
 ...
 ```
 
-Then just run cookiecutter where you want to create the new project. A new
+Then simply run [Cookiecutter] where you want to create the new project. A new
 directory will be created with the generated project name. For example:
 
 ```sh
 cd ~/devel
 cookiecutter gh:frequenz-floss/frequenz-repo-config-python --directory=cookiecutter
 ```
 
-This will prompt for the project type, name and other configuration and
-generate the whole project for you.
-
-After completing it and fixing the TODOs
-you can amend the previous commit using `git commit --amend`
-or create a new commit for the changes using `git commit`.
-You can make sure linting and tests pass by creating a virtual
-environment, installing the development dependencies and running `nox`:
-```sh
-# requires at least python version 3.11
-python3 -m venv .venv
-. .venv/bin/activate
-pip install .[dev-noxfile]
-nox
-```
-
-## Migrating an existing project
-
-The easiest way to migrate an existing project is to just generate a new one
-basing all the inputs in the current project metadata and then overwritting the
-existing files.
-
-It is recommended to commit all changes before doing this, so you can then use
-`git` to look at the changes.
-
-If you generate the new repo in a temporary directory, you can easily overwrite
-the files in your existing project by using `rsync` or similar tools:
-
-```sh
-cd /tmp
-cookiecutter gh:frequenz-floss/frequenz-repo-config-python --directory=cookiecutter
-rsync -vr --exclude=.git/ new-project/ /path/to/existing/project
-cd /path/to/existing/project
-git diff
-# Fix all the `TODO`s and cleanup the generated files
-git commit -a
-```
+This command will prompt you for the project type, name, and other
+configuration options, and it will generate the entire project for you.
 
-!!! warning
+After completing the project and fixing the `TODO`s, you can either amend the
+previous commit using `git commit --amend` or create a new commit for the
+changes using `git commit`.
 
-    The trailing slash in `new-project/` and the lack of it in
-    `/path/to/existing/project` are meaningful to `rsync`.
+## Documentation
 
-    Also make sure to **exclude** the `.git/` directory to avoid messing up
-    with your local git repository.
-
-## Update an existing project
-
-To update an existing project you can use the [Cookiecutter *replay
-file*](https://cookiecutter.readthedocs.io/en/stable/advanced/replay.html) that
-was saved during the project generation.  The file is saved in
-`.cookiecutter-replay.json`.  Using this file you can re-run Cookiecutter
-without having to enter all the inputs again.
-
-!!! warning
-
-    Don't forget to commit all changes in your repository before doing this!
-    Files will be overwritten!
-
-```sh
-git commit -a  # commit all changes
-cd ..
-cookiecutter gh:frequenz-floss/frequenz-repo-config-python \
-    --directory=cookiecutter \
-    --force \
-    --replay \
-    --replay-file project-directory/.cookiecutter-replay.json
-```
-
-This will create a new commit with all the changes to the overwritten files.
-Bear in mind that all the `TODO`s will come back, so there will be quite a bit
-of cleanup to do.  You can easily check what was changed using `git show`, and
-you can use `git commit --amend` to amend the previous commit with the template
-updates, or create a new commit with the fixes.  You can also use `git citool`
-or `git gui` to easily add, remove or even discard (revert) changes in the
-templates update commit.
-
-!!! note
-
-    The `project-directory` is the directory of your previously generated
-    project. If you renamed it, then the files will be generated in a new
-    directory with the original name.  You can update the target directory in
-    the replay file.
-
-!!! note
-
-    Please remember to keep your replay file up to date if you change any
-    metadata in the project.
+For more detailed documentation, please check the [project's
+website](https://frequenz-floss.github.io/frequenz-repo-config-python/).
 
 ## Contributing
 
 If you want to know how to build this project and contribute to it, please
-check out the [Contributing Guide](CONTRIBUTING.md).
+refer to the [Contributing Guide](CONTRIBUTING.md).
+
+
+[Cookiecutter]: https://cookiecutter.readthedocs.io/en/stable

RELEASE_NOTES.md

@@ -2,16 +2,39 @@
 
 ## Summary
 
-<!-- Here goes a general summary of what this release is about -->
+This release is a major step and adds many features and breaking changes.
 
 ## Upgrading
 
-<!-- Here goes notes on how to upgrade from previous versions, including deprecations and what they should be replaced with --> 
+Since this project is still in heavy development, the easiest way to upgrade is
+to regenerate the templates. Please follow the instructions in the new
+documentation website about [updating
+projects](https://frequenz-floss.github.io/frequenz-repo-config-python/next/#update-an-existing-project).
 
 ## New Features
 
-<!-- Here goes the main new features and examples or instructions on how to use them -->
+This is just a quick (non-comprehensive) summary of the new features:
+
+* Add `--diff` as a default argument for `isort`
+* Improve `README`
+* Don't import modules into packages
+* Support migrating and updating existing projects with Cookiecutter
+* Cookiecutter template
+
+  * Add `dependabot` configuration
+  * Add issue templates, keyword labeler, and PR labeler
+  * Add `CODEOWNERS` file
+  * Add `direnv`-related files to `.gitignore`
+  * Add GitHub CI workflow to `cookiecutter`
+  * Add `CONTRIBUTING` guide to `cookiecutter`
+  * Add `RELEASE_NOTES` to `cookiecutter`
+  * Add support to generate documentation using `mkdocs`
+
+* Apply all the Cookiecutter template improvements to this project
 
 ## Bug Fixes
 
-<!-- Here goes notable bug fixes that are worth a special mention or explanation -->
+This is just a quick (non-comprehensive) summary of bug fixes:
+
+* Fix some comments about creating labels
+* Fix tests

cookiecutter/hooks/post_gen_project.py

@@ -66,12 +66,28 @@ def main() -> None:
     print(". .venv/bin/activate")
     print("pip install .[dev-noxfile]")
     print("nox")
-    print("# To generate and serve the documentation:")
+    print()
+    print("To generate and serve the documentation:")
     print("pip install .[dev-mkdocs]")
     if cookiecutter.type == "api":
         print("# Requires docker")
     print("mkdocs serve")
     print()
+    print("To initialize the GitHub pages website:")
+    print("mike deploy --update-aliases next latest")
+    print("mike set-default latest")
+    print("git push upstream gh-pages  # or origin if you haven't forked the repo")
+    print()
+    print("Make sure that GitHub pages is enabled in your repository settings:")
+    print(
+        f"https://github.com/{cookiecutter.github_org}/{cookiecutter.github_repo_name}"
+        "/settings/pages"
+    )
+    print("If all went well, your new website should be available soon at:")
+    print(
+        f"https://{cookiecutter.github_org}.github.io/{cookiecutter.github_repo_name}/"
+    )
+    print()
     if warnings := do_sanity_checks():
         for warning in warnings:
             warn(warning)
@@ -80,7 +96,9 @@ def main() -> None:
         "If you had any issues or find any errors in the generated files, "
         "please report them!"
     )
-    note("https://github.com/frequenz-floss/frequenz-repo-config-python/issues/new")
+    note(
+        "https://github.com/frequenz-floss/frequenz-repo-config-python/issues/new/choose"
+    )
     print()
 
 

cookiecutter/{{cookiecutter.github_repo_name}}/README.md

@@ -1,5 +1,11 @@
 # {{cookiecutter.title}}
 
+[![Build Status](https://github.com/{{cookiecutter.github_org}}/{{cookiecutter.github_repo_name}}/actions/workflows/ci.yaml/badge.svg)](https://github.com/{{cookiecutter.github_org}}/{{cookiecutter.github_repo_name}}/actions/workflows/ci.yaml)
+[![PyPI Package](https://img.shields.io/pypi/v/{{cookiecutter.pypi_package_name}})](https://pypi.org/project/{{cookiecutter.pypi_package_name}}/)
+[![Docs](https://img.shields.io/badge/docs-latest-informational)](https://{{cookiecutter.github_org}}.github.io/{{cookiecutter.github_repo_name}}/)
+
+## Introduction
+
 {{cookiecutter.description}}
 
 TODO(cookiecutter): Improve the README file

cookiecutter/{{cookiecutter.github_repo_name}}/mkdocs.yml

@@ -11,6 +11,7 @@ repo_url: "https://github.com/{{cookiecutter.github_org}}/{{cookiecutter.github_
 # TODO(cookiecutter): "main" is the GitHub repo default branch, you might want to update it
 # if the project uses a different default branch.
 edit_uri: "edit/main/docs/"
+strict: true  # Treat warnings as errors
 
 # Build directories
 theme: