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
This is a template repository ready to develop code. It uses poetry to manage dependencies, python environmnet, and packagaing. Flake8 and Black to format code. Mkdocs to create documentation from docstrings. And adds GitHub actions to automitize tasks.
6
+
This is a template repository ready to develop code. It uses poetry to manage dependencies, python environment, and packaging. Flake8 and Black to format code. Mkdocs to create documentation from docstring. And adds GitHub actions to automatize tasks.
7
7
8
8
## Poetry
9
9
10
-
[Poetry](https://python-poetry.org/docs/) helps you to manage a python ppackage project. It manage dependencies, versions, and python environments.
10
+
[Poetry](https://python-poetry.org/docs/) helps you to manage a python package project. It manage dependencies, versions, and python environments.
11
11
First initialize a project:
12
12
13
13
```
@@ -47,29 +47,29 @@ and then we publish with:
47
47
```
48
48
poetry publish
49
49
```
50
-
This will upload the package to the index. We will do this everytime there is a new major or minor version of our package. This can be done also as a GitHub action, will add that later.
50
+
This will upload the package to the index. We will do this every time there is a new major or minor version of our package. This can be done also as a GitHub action, will add that later.
51
51
52
52
53
53
## GitHub
54
54
55
55
Initialize Git repository and sync with GitHub:
56
-
In the poejct directory do
56
+
In the project directory do
57
57
```
58
58
git init
59
59
```
60
60
to initialize the Git repo. Now we can add changes and commit to the main branch and sync with GitHub.
61
61
62
62
```
63
63
git add *
64
-
git commit -m "first comit"
64
+
git commit -m "first commit"
65
65
git remote add origin <GITHUB url>
66
66
git push -u origin main
67
67
```
68
68
More info [here](https://docs.github.com/en/repositories/creating-and-managing-repositories/quickstart-for-repositories?tool=webui).
69
69
70
70
## MkDocs
71
71
72
-
To create a documentation page using the docstrings in our code we will use `mkdocs`[wesite](https://docs.readthedocs.io/en/stable/intro/getting-started-with-mkdocs.html).
72
+
To create a documentation page using the docstring in our code we will use `mkdocs`[wesite](https://docs.readthedocs.io/en/stable/intro/getting-started-with-mkdocs.html).
73
73
First, install the library in the virtual env:
74
74
```
75
75
poetry add -G dev mkdocs mkdocstrings mkdocs-material
@@ -86,25 +86,40 @@ To build the documentation as a page we use:
86
86
poetry run mkdocs build
87
87
poetry run mkdocs serve
88
88
```
89
-
This will build the documentation and creater a local view of the page to visualize in our browser.
89
+
This will build the documentation and create a local view of the page to visualize in our browser.
90
90
91
91
TO deploy the the page to Github branch with the documentation we do
92
92
```
93
93
poetry run mkdocs gh-deploy
94
94
```
95
95
this will create the website [https://jorgemarpa.github.io/repo-template/](https://jorgemarpa.github.io/repo-template/) which has the documentation we have created.
96
96
97
+
98
+
## Pytest
99
+
100
+
Pytest will run any test code that is written in the `tests` folder. Ideally we want to test all our code to ensure nothing breaks and that function behavior is as expected. We can run `pytest` locally before committing to the branch or PR with:
101
+
```
102
+
poetry run pytest -v tests
103
+
```
104
+
97
105
## GitHub Actions
98
106
99
-
This are automatic actions that happens during pushing new commits and/or pull request. We can configure these actions in a `yml` file in the `.github/workflows` directory.
100
-
In this template we have one for `ruff`, `deploy-mkdocs`, `pytest`, `dependabot`, and `mypy`.
107
+
This are automatic actions that happens during pushing new commits and/or pull request. We can configure these actions in a `yaml` file in the `.github/workflows` directory. These actions automatize most of the routine steps described in this document.
108
+
109
+
In this template we have the following workflows:
110
+
-`ruff`: does code formatting, lint, and sorting. It replaces `flake8`, `isort`, and `black`.
111
+
-`deploy-mkdocs`: creates documentation page from with Mkdocs.
112
+
-`pytest`: runs python test
113
+
-`dependabot`: check for security and version updates of project dependencies and creates PRs when new version are available.
114
+
-`mypy`: check for python static programming.
115
+
-`pypi-publish`: published the project in PyPI when a new GitHub release/tag is created
101
116
102
117
### Publish to PyPI Action
103
118
104
-
This repo has the action `pypi-publish.yml` that automatically publish the package to TestPyPI once a
119
+
This repo has the action `pypi-publish.yaml` that automatically publish the package to TestPyPI once a
105
120
release or a tag version is created in GitHub. Note that for this example we used
106
-
[TestPyPI](https://test.pypi.org/) which is an instance of PyPI to test package deplyment and publishing
107
-
withou afecting the real index. It is ideal to test things.
121
+
[TestPyPI](https://test.pypi.org/) which is an instance of PyPI to test package deployment and publishing
122
+
without affecting the real index. It is ideal to test things.
108
123
We also need to setup a TestPyPI/PyPI API token and add it to GitHub secrets.
109
124
110
125
When our package is ready to be publish to the real PyPI, we need to update the action as follows:
@@ -127,11 +142,4 @@ to
127
142
This will change te repository configuration back to publish to PyPI. Remember to add the PyPI
128
143
API token to GitHub secrets.
129
144
130
-
See this [tutorial](https://www.ianwootten.co.uk/2020/10/23/publishing-to-pypi-using-github-actions/) for more details.
131
-
132
-
## Pytest
133
-
134
-
Pytest will run any test code that is written in the `tests` folder. Idially we want to test all our code to ensure nothing breaks and that function behavior is as expected. We can run pytest locally before commiting to the branch or PR with:
135
-
```
136
-
poetry run pytest -v tests
137
-
```
145
+
See this [tutorial](https://www.ianwootten.co.uk/2020/10/23/publishing-to-pypi-using-github-actions/) for more details.
0 commit comments