Merge pull request #15 from brainelectronics/feature/improvements-and-findings-after-first-usage

Improvements and findings after first usage

Author: brainelectronics

.coveragerc

@@ -10,7 +10,7 @@ omit =
     .tox/*,
     build/*,
     dist/*,
-    version.py
+    be_upy_blink/version.py
 
 [report]
 # include = src/*

.editorconfig

@@ -15,6 +15,10 @@ trim_trailing_whitespace = true
 [*.py]
 indent_size = 4
 
+[*.json]
+indent_size = 4
+
+# 2 space indentation
 [*.yml]
 indent_size = 2
 

.flake8

@@ -45,7 +45,6 @@ exclude =
     libs_external
     sdist_upip.py
     setup.py
-    update_version.py
 
 # Provide a comma-separated list of glob patterns to add to the list of excluded ones.
 # extend-exclude =

.github/workflows/test.yml

@@ -13,6 +13,10 @@ on:
     branches-ignore:
       - 'main'
       - 'develop'
+  pull_request:
+    branches:
+      - 'main'
+      - 'develop'
 
 permissions:
   contents: read

LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 brainelectronics and contributors
+Copyright (c) 2023 brainelectronics and contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

README.md

@@ -15,6 +15,9 @@ MicroPython PyPi package template project with auto deploy
 
 MicroPython PyPi package template with GitHub Action based testing and deploy
 
+📚 The latest documentation is available at
+[MicroPython Package Template ReadTheDocs][ref-rtd-micropython-package-template] 📚
+
 <!-- MarkdownTOC -->
 
 - [Installation](#installation)
@@ -33,6 +36,7 @@ MicroPython PyPi package template with GitHub Action based testing and deploy
 	- [Upload to PyPi](#upload-to-pypi)
 - [Contributing](#contributing)
 	- [Unittests](#unittests)
+- [Steps after using this template](#steps-after-using-this-template)
 - [Credits](#credits)
 
 <!-- /MarkdownTOC -->
@@ -76,6 +80,13 @@ station.isconnected()
 
 Install the latest package version of this lib on the MicroPython device
 
+```python
+import mip
+mip.install("github:brainelectronics/micropython-package-template")
+```
+
+For MicroPython versions below 1.19.1 use the `upip` package instead of `mip`
+
 ```python
 import upip
 upip.install('micropython-package-template')
@@ -85,6 +96,16 @@ upip.install('micropython-package-template')
 
 Install a specific, fixed package version of this lib on the MicroPython device
 
+```python
+import mip
+# install a verions of a specific branch
+mip.install("github:brainelectronics/micropython-package-template", version="feature/initial-implementation")
+# install a tag version
+mip.install("github:brainelectronics/micropython-package-template", version="0.6.0")
+```
+
+For MicroPython versions below 1.19.1 use the `upip` package instead of `mip`
+
 ```python
 import upip
 upip.install('micropython-package-template==0.1.1')
@@ -97,6 +118,13 @@ Install a specific release candidate version uploaded to
 MicroPython device. If no specific version is set, the latest stable version
 will be used.
 
+```python
+import mip
+mip.install("github:brainelectronics/micropython-package-template", version="0.6.0-rc9.dev13")
+```
+
+For MicroPython versions below 1.19.1 use the `upip` package instead of `mip`
+
 ```python
 import upip
 # overwrite index_urls to only take artifacts from test.pypi.org
@@ -215,11 +243,33 @@ coverage html
 
 The coverage report is placed at `reports/coverage/html/index.html`
 
+## Steps after using this template
+
+In order to use this template for a new MicroPython package to following steps
+should be done and changes to these file being made
+
+| File | Changes | More details |
+| ---- | ------- | -------------|
+| `.coveragerc` | Path to `version.py` file | Omit version file from coverage |
+| `.coveragerc` | Path to `include` folder | Include the package folder for coverage |
+| `.github/workflows/release.yml` | Path to `version.py` file | Use package version file to set changelog based version |
+| `.github/workflows/test-release.yml` | Path to `version.py` file | Use package version file to set changelog based version |
+| `.github/workflows/test.yml` | Path to `version.py` file | Use package version file to set changelog based version |
+| `README.md` | Links in header section and installation instructions | |
+| `changelog.md` | Cleanup changelog from informations of template | Keep usage of SemVer |
+| `docs/DOCUMENTATION.md` | Kink to ReadTheDocs | |
+| `docs/conf.py` | List to modules to be mocked, package import, path to `version.py` file, update `author`, `project` and `linkcheck_ignore` | |
+| `docs/index.rst` | Header name and included modules | Replace `be_upy_blink` with new `.rst` file of new package |
+| `docs/NEW_MODULE_NAME.rst` | Create a new `.rst` file  named as the package | Use `docs/be_upy_blink.rst` as template |
+| `package.json` | Files and paths to new package and repo | Used by `mip` |
+| `setup.py` | Path to `version.py` file, `name`, `description`, `url`, `author`, `author_email`, `keywords`, `project_urls`, `packages`, `install_requires` | Used to create the package and its informations published at e.g. PyPI |
+
 ## Credits
 
 Based on the [PyPa sample project][ref-pypa-sample].
 
 <!-- Links -->
+[ref-rtd-micropython-package-template]: https://micropython-package-template.readthedocs.io/en/latest/
 [ref-remote-upy-shell]: https://github.com/dhylands/rshell
 [ref-brainelectronics-test-pypiserver]: https://github.com/brainelectronics/test-pypiserver
 [ref-pypa-sample]: https://github.com/pypa/sampleproject

changelog.md

@@ -17,6 +17,26 @@ r"^\#\# \[\d{1,}[.]\d{1,}[.]\d{1,}\] \- \d{4}\-\d{2}-\d{2}$"
 -->
 
 ## Released
+## [0.7.0] - 2023-03-17
+### Added
+- Set settings for JSON files to use an indentation of 4 in `.editorconfig`
+- `package.json` for `mip` installation with MicroPython v1.19.1 or newer
+- Instructions for installation with `mip` on  MicroPython v1.19.1 or newer in `README`
+- Instructions to be performed after using this template package in `README`
+- Example files for `boot` and `main`
+
+### Changed
+- Omit package version file from coverage calculation in `.coveragerc`
+- Run test workflow also on pull requests
+- Update date of license to 2023
+
+### Removed
+- No longer used `update_version.py` file removed from flake8 exclude list
+
+### Fixed
+- Path to documentation build output folder is only highlighted to avoid broken links errors
+- Mock commonly used MicroPython specific modules in docs config file
+
 ## [0.6.0] - 2023-02-22
 ### Added
 - `.editorconfig` for common editor settings, see #12
@@ -90,8 +110,9 @@ r"^\#\# \[\d{1,}[.]\d{1,}[.]\d{1,}\] \- \d{4}\-\d{2}-\d{2}$"
 - [`setup.py`](setup.py) and [`sdist_upip.py`](sdist_upip.py) file
 
 <!-- Links -->
-[Unreleased]: https://github.com/brainelectronics/micropython-package-template/compare/0.6.0...main
+[Unreleased]: https://github.com/brainelectronics/micropython-package-template/compare/0.7.0...main
 
+[0.7.0]: https://github.com/brainelectronics/micropython-package-template/tree/0.7.0
 [0.6.0]: https://github.com/brainelectronics/micropython-package-template/tree/0.6.0
 [0.5.0]: https://github.com/brainelectronics/micropython-package-template/tree/0.5.0
 [0.4.0]: https://github.com/brainelectronics/micropython-package-template/tree/0.4.0

docs/DOCUMENTATION.md

@@ -34,7 +34,7 @@ sphinx-build docs/ docs/build/linkcheck -d docs/build/docs_doctree/ --color -bli
 sphinx-build docs/ docs/build/html/ -d docs/build/docs_doctree/ --color -bhtml -j auto -W
 ```
 
-The created documentation can be found at [`docs/build/html`](docs/build/html).
+The created documentation can be found at `docs/build/html`.
 
 <!-- Links -->
 [ref-rtd-micropython-package-template]: https://micropython-package-template.readthedocs.io/en/latest/

docs/conf.py

@@ -14,16 +14,22 @@
 here = Path(__file__).parent.resolve()
 
 try:
-    import be_upy_blink
-except ImportError:
-    raise SystemExit("be_upy_blink has to be importable")
-else:
     # Inject mock modules so that we can build the
     # documentation without having the real stuff available
     from mock import Mock
 
-    sys.modules['micropython'] = Mock()
-    print("Mocked 'micropython' module")
+    to_be_mocked = [
+        'micropython',
+        'machine',
+        'time.sleep_ms', 'time.sleep_us',
+    ]
+    for module in to_be_mocked:
+        sys.modules[module] = Mock()
+        print("Mocked '{}' module".format(module))
+
+    import be_upy_blink
+except ImportError:
+    raise SystemExit("be_upy_blink has to be importable")
 
 # load elements of version.py
 exec(open(here / '..' / 'be_upy_blink' / 'version.py').read())

examples/boot.py

@@ -0,0 +1,15 @@
+#!/usr/bin/env python3
+# -*- coding: UTF-8 -*-
+
+"""
+Boot script
+Do initial stuff here, similar to the setup() function on Arduino
+"""
+
+# This file is executed on every boot (including wake-boot from deepsleep)
+# import esp
+# esp.osdebug(None)
+# import webrepl
+# webrepl.start()
+
+print('System booted successfully!')