From 32bafcdc460d2c64972114509983306040b70a8e Mon Sep 17 00:00:00 2001 From: HBBisenieks Date: Tue, 15 Mar 2022 14:45:38 -0700 Subject: [PATCH] documentation about documentation --- docs/README.md | 1 + docs/contributing.md | 56 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 57 insertions(+) create mode 100644 docs/contributing.md diff --git a/docs/README.md b/docs/README.md index 8dae7e5..36b1918 100644 --- a/docs/README.md +++ b/docs/README.md @@ -12,6 +12,7 @@ - [Keycodes](keycodes.md): List of all available keycodes - [Officially supported microcontrollers](Officially_Supported_Microcontrollers.md) - [Support](support.md) +- [Contributing](contributing.md) ## Advanced diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 0000000..9b7970a --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,56 @@ +# Contributing +KMK is a community effort and welcomes contributions of code and documentation from people +of all backgrounds and levels of technical skill. As such, these guidelines should serve +to make contributing as easy as possible for everyone while maintaining a consistent style. + +## Contributing Code +The following guidelines should ensure that any code contributed can be merged in as +painlessly as possible. If you're unsure how to set up your development environment, +feel free to join the chat, [#kmkfw:klar.sh on Matrix](https://matrix.to/#/#kmkfw:klar.sh). +This channel is bridged to Discord [here](https://discord.gg/QBHUUpeGUd) for convenience. + +### Code Style + +KMK uses [Black](https://github.com/psf/black) with a Python 3.6 target and, +[(controversially?)](https://github.com/psf/black/issues/594) single quotes. +Further code styling is enforced with isort and flake8 with several plugins. +`make fix-isort fix-formatting` before a commit is a good idea, and CI will fail +if inbound code does not adhere to these formatting rules. Some exceptions are +found in `setup.cfg` loosening the rules in isolated cases, notably +`user_keymaps` (which is *also* not subject to Black formatting for reasons +documented in `pyproject.toml`). + +### Tests + +Unit tests within the `tests` folder mock various CicuitPython modules to allow +them to be executed in a desktop development environment. + +Execute tests using the command `python -m unittest`. + +## Contriburing Documentation +While KMK welcomes documentation from anyone with and understanding of the issues +and a willingness to write them up, it's a good idea to familiarize yourself with +the docs. Documentation should be informative but concise. + +### Styling +Docs are written and rendered in GitHub Markdown. A comprehensive guide to GitHub's +Markdown can be found [here](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax). + +In particular, KMK's docs should include a title, demarcated with `#`, and subheadings +should be demarcated with `##`, `###`, and so on. Headings should be short and specific. + +### Example Code +Where possible, practical code examples should be included in documentation to help +new users understand how to implement features. In general, it's better to have a code- +block with comments inside it rather than multiple blocks of code broken up with +explanation. + +Code blocks should be formatted as Python code as follows: +```` +```python +print('Hello, world!') +``` +```` + +Inline code, indicated with ``backticks``, should be used when calling out specific +functions or Python keywords within the body of paragraphs or in lists.