Skip to content

Commit 98c9e50

Browse files
oncleben31Quentame
oncleben31
and
Quentame
authoredOct 11, 2020
Improve documentation (#33)
* Add darglint in dev dependencies * Add darglint check in nox pre-commit session * Add darglint configuration file * Update python module top docstrings * Rewrite client docstrings with the Google style * Rewrite helpers docstrings with Google style * use the term metropolitan France * Rewrite session docstrings with the Google doc style * Rewrite forecast model docstrings * Rewrite picture of day model docstrings * Rewrite place model doctstrings * Add missing type information for __init__ methods * Rewrite rain model doctstrings * Rewrite warning model docstrings * Add docstrings for __init__ methods * Add sphinx to dev dependencies * Init sphinx configuration * Add nox session to generate docs * Add sphinx-autobuild to dev dependencies * Update sphinx configuration * Convert LICENSE in reST * Convert README to reST * update README reference in Poetry project * Convert CONTRIBUTING to reST * Add sphinx documentation * Add docs-build in Nox defaults sessions * Update README anchors and links * Update CONTRIBUTING anchors and links * Apply suggestions from code review Co-authored-by: Quentame <polletquentin74@me.com> * Implement fix from code review * Fix code style by Black * Refresh poetry.lock * Code style modification by Black Co-authored-by: Quentame <polletquentin74@me.com>
1 parent de8888b commit 98c9e50

25 files changed

+1112
-336
lines changed
 

‎.darglint

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
[darglint]
2+
strictness = short

‎.flake8

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
[flake8]
2-
select = B,B9,C,D,E,F,N,S,W
2+
select = B,B9,C,D,DAR,E,F,N,S,W
33
max-complexity = 10
44
docstring-convention = google
55
exclude = .venv,.git,.tox,docs,venv,bin,lib,deps,build,.eggs

‎CONTRIBUTING.md

-117
This file was deleted.

‎CONTRIBUTING.rst

+158
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
Contribuer | Contributing
2+
=========================
3+
4+
You will find instructions in English in the section `Contributing`_.
5+
6+
Vous trouverez les instructions en français dans la section `Contribuer`_.
7+
8+
Contribuer
9+
----------
10+
11+
Vous êtes tous invités à contribuer à ce projet pour le maintenir ou l'améliorer.
12+
Même si vous n'êtes pas un développeur, vous pouvez sûrement donner un coup de
13+
main en remontant les bugs constatés, en partageant vos idées d'amélioration ou
14+
en participant à la documentation.
15+
16+
Préparer votre environement de développement
17+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
18+
19+
Vous aurez besoin de Python 3.6+ et des outils suivants:
20+
21+
- Poetry_
22+
- Nox_
23+
24+
Installez le package avec les dépendances de développement:
25+
26+
.. code:: console
27+
28+
$ poetry install
29+
30+
Vous pouvez maintenant utiliser une session interactive Python:
31+
32+
.. code:: console
33+
34+
$ poetry run python
35+
36+
Je vous recommande d'installer un pre-commit-hook pour lancer automatiquement quelques
37+
vérfication avant de commit vos modifications.
38+
39+
.. code:: console
40+
41+
$ nox -s pre-commit -- install
42+
43+
Tester le projet
44+
^^^^^^^^^^^^^^^^
45+
46+
Dérouler la suite de tests complète:
47+
48+
.. code:: console
49+
50+
$ nox
51+
52+
Lister toutes les sessions disponibles dans Nox:
53+
54+
.. code:: console
55+
56+
$ nox --list-sessions
57+
58+
Vous pouvez lancer une session Nox spécifique. Par exemple, lancez la suite de
59+
tests unitaires avec:
60+
61+
.. code:: console
62+
63+
$ nox --session=tests
64+
65+
Les tests unitaires sont dans le répertoire `tests` et utilisent le framework pytest.
66+
67+
Soumettre votre Pull Request (PR)
68+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
69+
70+
Ouvrez une `pull request`_ pour proposer des changements à ce projet.
71+
72+
Votre pull request doit vérifier les conditions suivantes pour être acceptée:
73+
74+
* La suite de tests Nox doit réussir sans erreurs ni warning.
75+
* Doit inclure des tests unitaires. Ce projet maintien une couverture de code à 100%.
76+
77+
Proposer une nouvelle fonctionnalité
78+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
79+
80+
Pour proposer vos idées d'amélioration, ouvrez une `issue <https://github.com/hacf-fr/meteofrance-api/issues>`_
81+
en utilisant le modèle ``feature request``.
82+
83+
Contributing
84+
------------
85+
86+
You are all invited to contribute to this project for maintenance or improvement.
87+
Even if you are not a developer, you can help to report some bugs, share
88+
improvements ideas, or contribute to the documentation.
89+
90+
How to set up your development environment
91+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
92+
93+
You need Python 3.6+ and the following tools:
94+
95+
- Poetry_
96+
- Nox_
97+
98+
Install the package with development requirements:
99+
100+
.. code:: console
101+
102+
$ poetry install
103+
104+
You can now run an interactive Python session, or the command-line interface:
105+
106+
.. code:: console
107+
108+
$ poetry run python
109+
110+
I recommand to install a pre-commit-hook to have some checks done automatically before you commit your changes.
111+
112+
.. code:: console
113+
114+
$ nox -s pre-commit -- install
115+
116+
How to test the project
117+
^^^^^^^^^^^^^^^^^^^^^^^
118+
119+
Run the full test suite:
120+
121+
.. code:: console
122+
123+
$ nox
124+
125+
List the available Nox sessions:
126+
127+
.. code:: console
128+
129+
$ nox --list-sessions
130+
131+
You can also run a specific Nox session. For example, invoke the unit test suite like this:
132+
133+
.. code:: console
134+
135+
$ nox --session=tests
136+
137+
Unit tests are located in the tests directory, and are written using the pytest testing framework.
138+
139+
How to submit changes
140+
^^^^^^^^^^^^^^^^^^^^^
141+
142+
Open a `pull request`_ to submit
143+
changes to this project.
144+
145+
Your pull request needs to meet the following guidelines for acceptance:
146+
147+
- The Nox test suite must pass without errors and warnings.
148+
- Include unit tests. This project maintains 100% code coverage.
149+
150+
Feature suggestion
151+
^^^^^^^^^^^^^^^^^^
152+
153+
If you want to suggest a new feature for this project, please open an `issue <https://github.com/hacf-fr/meteofrance-api/issues>`_
154+
by using the `feature request` template.
155+
156+
.. _Poetry: https://python-poetry.org/
157+
.. _Nox: https://nox.thea.codes/
158+
.. _pull request: https://github.com/hacf-fr/meteofrance-api/pulls

‎LICENSE ‎LICENSE.rst

+8-7
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
MIT License
2+
===========
23

34
Copyright (c) 2020 HACF Home Assistant Communauté Francophone
45

@@ -12,10 +13,10 @@ furnished to do so, subject to the following conditions:
1213
The above copyright notice and this permission notice shall be included in all
1314
copies or substantial portions of the Software.
1415

15-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16-
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17-
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18-
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19-
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20-
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21-
SOFTWARE.
16+
**The software is provided "as is", without warranty of any kind, express or
17+
implied, including but not limited to the warranties of merchantability,
18+
fitness for a particular purpose and noninfringement. In no event shall the
19+
authors or copyright holders be liable for any claim, damages or other
20+
liability, whether in an action of contract, tort or otherwise, arising from,
21+
out of or in connection with the software or the use or other dealings in the
22+
software.**

‎README.md

-88
This file was deleted.

0 commit comments

Comments
 (0)