You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on May 26, 2026. It is now read-only.
[Git hooks](https://git-scm.com/docs/githooks) are programs you can place in a hooks directory to trigger actions at certain points in git’s execution.
47
+
[Pre-commit](https://pre-commit.com/) is a handy tool that manages the installation and execution of any hook written in any language before every commit.
48
+
49
+
We can configure pre-commit hooks in the [.pre-commit-config.yaml](.pre-commit-config.yaml) file. For this template we check the linting with *flake8* and the docs with *pydocstyle*. And code cannot be committed unless it passes those checks.
50
+
51
+
To install pre-commit:
52
+
1.`pip install pre-commit`
53
+
2. with your venv activated `pre-commit install`
54
+
55
+
To bypass the pre-commit checks you can commit your changes with the --no-verify option.
56
+
`git commmit -m "description" --no-verify`
47
57
48
58
## flake8
49
59
flake8 checks if the code is uggly according to [PEP8](https://www.python.org/dev/peps/pep-0008/).
@@ -72,27 +82,62 @@ Some IDEs have format on save features and can be configured to use black:
72
82
* Visual studio code: https://dev.to/adamlombard/how-to-use-the-black-python-code-formatter-in-vscode-3lo0
73
83
74
84
## pydocstyle
75
-
*[insert description]*
85
+
[pydocstyle](http://www.pydocstyle.org/en/stable/) is a static analysis tool for checking compliance with Python docstring conventions.
86
+
By using pydocstyle we make sure that all modules and functions have consistent and good documentation.
76
87
77
88
## pytest
78
89
*[insert description]*
79
90
91
+
## Sphinx documentation
92
+
[Sphinx](https://www.sphinx-doc.org/en/master/) is a tool that makes it easy to create intelligent and beautiful documentation.
93
+
The [docs/](docs) diretory is where the configuration for sphinx lives. The dependencies for the docs are in [docs/requiremetns.txt](docs/requiremetns.txt).
94
+
To build the documentation run the following:
95
+
1.`cd docs`*to go to the docs directory*
96
+
2.`make html`*to make the html version of the docs*
97
+
98
+
Sphinx has the automodule functionality that creates the documetation automatically from the docstrings for each module and function.
99
+
If you add a new module and you want to generate the documentation automatically, you'll need to add the following test in [index.rst](docs/source/index.rst):
100
+
```
101
+
newmodule
102
+
=============
103
+
104
+
.. automodule:: examplepackage.newmodule
105
+
:members:
106
+
```
107
+
108
+
The build directory that contains the html version of the docs is in the .gitignore and therefore not in the github repo.
109
+
110
+
Sphinx has many functionalities so for more details read the official documentation.
111
+
80
112
## setup.cfg
81
113
*[insert description]*
82
114
83
115
## setup.py
84
116
*[insert description]*
85
117
86
118
## Installing a package in Development mode
87
-
*[insert description]*
119
+
`pip install -e .` or `pip install --editable .` installs the package in editable (development) mode.
120
+
This is essential for development because the changes you make in the code are directly applied in the installed package without the need for re-installation.
.gitignore is a file where you can add files and directories that you want git to ignore.
92
-
The [.gitignore](.gitignore) has the typical content e.g. .venv, the directory that contains the python virtual environment, should not be push to github and is in .gitignore.
126
+
The title is pretty self explanatory.
127
+
128
+
.gitignore is a file where you can add files and directories that you want git to ignore. The [.gitignore](.gitignore) in this template has the typical content.
129
+
e.g. .venv, the directory that contains the python virtual environment, should not be push to github and is in .gitignore.
93
130
94
131
## Github Actions
95
-
*[insert description]*
132
+
From the official https://github.com/features/actions page:
133
+
*"GitHub Actions makes it easy to automate all your software workflows, now with world-class CI/CD. Build, test, and deploy your code right from GitHub. Make code reviews, branch management, and issue triaging work the way you want."*
134
+
135
+
Github actions are configured in yaml files in the [.github/workflows](.github/workflows) directory. For this template we have a single file [.github/workflows](.github/workflows/buildtest.yml).
136
+
This runs the following actions for every pull-request and every push to merge:
137
+
1. code-quality: flake8
138
+
2. docs-quality: pydocstyle
139
+
3. build and test (with pytest) for all the combinations of the chosen operating systems and python versions.
140
+
e.g. macos-latest and python 3.7, 3.8
96
141
97
142
## Licences
98
143
Details about the mainstream OSS (Open source software) licences can be found here:
@@ -101,8 +146,14 @@ https://opensource.org
101
146
Wikipedia has nice/comprehensive comparison table here:
0 commit comments