fix: typing and documentation

.github/workflows/test.yml

@@ -22,7 +22,7 @@ jobs:
       - name: Install dependencies
         run: poetry install
       - name: Type checking
-        run: poetry run mypy src/wsl_tools.py
+        run: poetry run mypy src/wsl_tools
       - name: Test with pytest
         run: poetry run pytest --cov=./ --cov-report=xml
       - name: Upload coverage to Codecov

CONTRIBUTING.md

@@ -0,0 +1,77 @@
+# Contributing
+
+Your contribution is very welcome!
+These are some guidelines to ensure that your changes are quickly accepted.
+
+The goal is to write code that works, is secure and easy to read and understand.
+To achieve that:
+
+- limit the length of the lines of code to 80 chars
+  (well, you don't need to worry about that as long as you use the [pre-commit check](#pre-commit-check));
+- use typing annotation for all the functions and methods you write;
+- document every public method and module using [google style docstring](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html);
+- write `pytest` tests to ensure a 100% coverage.
+
+## Setup
+
+### Install development tools
+
+Install `poetry`, and `pre-commit` in your default python (3.7+) distribution:
+
+```shell
+pip install poetry pre-commit
+```
+
+### clone the repository
+
+Use `git` to clone the repo and enter the newly created directory:
+
+```shell
+git clone https://github.com/sanzoghenzo/wsl-tools
+cd wsl-tools
+```
+
+### Initialize virtualenv
+
+Simply run the following:
+
+```shell
+poetry install
+```
+
+It will create the virtualenv and install the dependencies.
+
+<!-- prettier-ignore -->
+!!! NOTE
+    If you use conda, the command will use the currently active environment.
+
+    To ensure an isolated environment,
+    you should run `conda create -n wsl-tools python=3.7 poetry`
+    and `conda activate wsl-tool` before `poetry install`.
+
+### enable pre-commit hook
+
+This will ensure that your code is checked before committing the changes:
+
+```shell
+pre-commit install
+```
+
+## Run tests
+
+To run the test suite, simply run:
+
+```shell
+poetry run pytest
+```
+
+## Pre-commit check
+
+You can manunally perform the checks that run before a commit via `pre commit --all-files`.
+
+This will:
+
+- auto-format code and docstrings;
+- perform static and runtime type checking;
+- run security check on the dependencies;
+- run the tests and check there's 100% coverage.

README.md

@@ -2,26 +2,27 @@
 
 Handy classes for WSL management.
 
-Inspired by [GWSL](https://opticos.github.io/gwsl/), a great work from [Pololot64](https://github.com/Pololot64)
+Inspired by [GWSL](https://opticos.github.io/gwsl/),
+a great work from [Pololot64](https://github.com/Pololot64),
+this project is a wrapper around the WSL executable to:
 
-## Classes
+- check if WSL is installed;
+- list and access the installed distribution;
+- import new distribution from tarball files;
+- run commands inside a distribution;
+- read and set known environment variables in the user `.profile`;
+- get the installed apps (that have a .desktop entry).
 
-### WSLManager
+```python
 
-`UserDict` that holds the installed WSL distributions.
+from wsl_tools import wsl_tools
 
-It also has a few helper methods/properties to check if `wsl` is installed and import distributions from tarball files.
+manager = wsl_tools.WSLManager()
 
-### WSLDistro
+```
 
-This class does the heavy lifting.
+For more information read the reference documentation.
 
-It mainly calls subprocess to run `wsl ~ -d distro-name sh -lc '....'`.
-Running the commands via `sh -lc` gives us a broader distribution support,
-and ensures that we can use and edit the user .profile file.
+## contributing
 
-### WSLApp
-
-Object holding the information found in the distro installed apps that have a xdg Desktop Entry.
-
-It doesn't do much at the time.
+Contributions are welcome! See [contributing](CONTRIBUTING.md).