Skip to content

Commit c596faf

Browse files
J08KBethanyG
J08K
and
BethanyG
authored
[Docs]: Cleanup, Push to site, and Spell check (exercism#2776)
* Entry for TOOLS.md * Correct links * Spell check and cleanup * [TESTING Docs]: Added intro and a few suggestions. (exercism#2778) * Add intro and a few suggestions. * Update docs/TESTS.md Co-authored-by: Job van der Wal <48634934+J08K@users.noreply.github.com> Co-authored-by: Job van der Wal <48634934+J08K@users.noreply.github.com> Co-authored-by: BethanyG <BethanyG@users.noreply.github.com>
1 parent beda223 commit c596faf

3 files changed

Lines changed: 52 additions & 57 deletions

File tree

‎docs/TESTS.md‎

Lines changed: 36 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,28 @@
11
# Tests
22

3-
- [Tests](#tests)
4-
- [Pytest](#pytest)
5-
- [Installing pytest Globally](#installing-pytest-globally)
6-
- [Windows](#windows)
7-
- [Linux / MacOS](#linux--macos)
8-
- [Installing pytest within a virtual environment](#installing-pytest-within-a-virtual-environment)
9-
- [Running the tests](#running-the-tests)
10-
- [Failures](#failures)
11-
- [Extra arguments](#extra-arguments)
12-
- [Stop After First Failure [`-x`]](#stop-after-first-failure--x)
13-
- [Failed Tests First [`--ff`]](#failed-tests-first---ff)
14-
- [Recommended Workflow](#recommended-workflow)
15-
- [Using PDB, the Python Debugger, with pytest](#using-pdb-the-python-debugger-with-pytest)
16-
- [Extending your IDE](#extending-your-ide)
17-
- [Additional information](#additional-information)
18-
- [Adding pytest to your PATH](#adding-pytest-to-your-path)
19-
- [Windows](#windows-1)
20-
- [Fixing warnings](#fixing-warnings)
3+
We use [pytest](http://pytest.org/en/latest/) as our website test runner.
4+
You will need to install pytest on your development machine if you want to download and run exercise tests for the Python track locally.
5+
We also recommend you install the following pytest plugins:
6+
7+
- [pytest-cache](http://pythonhosted.org/pytest-cache/)
8+
- [pytest-subtests](https://github.com/pytest-dev/pytest-subtests)
9+
- [pytest-pylint](https://github.com/carsongee/pytest-pylint)
10+
11+
The PyTest [Getting Started Guide](https://docs.pytest.org/en/latest/getting-started.html) has quick general instructions, although they do not cover installing the plugins.
12+
Continue reading below for more detailed instructions.
13+
14+
We also recommend using [pylint](https://pylint.pycqa.org/en/latest/user_guide/), as it is part of our automated feedback on the website, and can be a very useful (but also noisy) code analysis tool.
15+
16+
Pylint can be a bit much, so this [tutorial from pycqa.orgl](https://pylint.pycqa.org/en/latest/tutorial.html) can be helpful for getting started, as can this overview of [Code Quality: Tools and Best Practices](https://realpython.com/python-code-quality/) from Real Python.
17+
18+
---
19+
20+
- [Pytest](#pytest)
21+
- [Installing pytest](#installing-pytest)
22+
- [Running the tests](#running-the-tests)
23+
- [Extra arguments](#extra-arguments)
24+
- [Extending your IDE](#extending-your-ide)
25+
- [Additional information](#additional-information)
2126

2227
---
2328

@@ -27,7 +32,7 @@ _Official pytest documentation can be found on the [pytest Wiki](https://pytest.
2732

2833
Pytest lets you test your solutions using our provided tests, and is what we use to validate your solutions on the website.
2934

30-
### Installing pytest Globally
35+
### Installing pytest
3136

3237
Pytest can be installed and updated using the built-in Python utility `pip`.
3338

@@ -46,7 +51,7 @@ Successfully installed pytest-6.2.5 ...
4651

4752
```
4853

49-
To check if the installation was succesful:
54+
To check if the installation was successful:
5055

5156
```bash
5257
$ python3 -m pytest --version
@@ -57,9 +62,9 @@ If you do not want to precede every command with `python3 -m` please refer to [a
5762

5863
#### Installing pytest within a virtual environment
5964

60-
*For more information about virtual environments please refer to the [TOOLS](./TOOLS.md) file.*
65+
_For more information about virtual environments please refer to the [tools](./tools) file._
6166

62-
When installing pytest or any other module(s), make sure that you have [activated your environment](.\TOOLS.md#activating-your-virtual-environment). After which you can run:
67+
When installing pytest or any other module(s), make sure that you have [activated your environment](./tools#activating-your-virtual-environment). After which you can run:
6368

6469
```bash
6570
$ pip install pytest pytest-cache pytest-subtests pytest-pylint
@@ -150,7 +155,7 @@ This will test your solution. When `pytest` encounters a failed test, the progra
150155

151156
#### Using PDB, the Python Debugger, with pytest
152157

153-
If you want to truly debug like a pro, use the `--pdb` argument after the `pytest` command.
158+
If you want to truly debug like a pro, use the `--pdb` argument after the `pytest` command.
154159

155160
```bash
156161
$ python3 -m pytest --pdb bob_test.py
@@ -161,13 +166,13 @@ When a test fails, `PDB` allows you to look at variables and how your code respo
161166

162167
## Extending your IDE
163168

164-
If you'd like to extend your IDE with some tools that will help you with testing and improving your code, check the [TOOLS](./TOOLS.md) page. We go into multiple IDEs, editors and some useful extensions.
169+
If you'd like to extend your IDE with some tools that will help you with testing and improving your code, check the [tools](./tools) page. We go into multiple IDEs, editors and some useful extensions.
165170

166171
## Additional information
167172

168173
### Adding pytest to your PATH
169174

170-
**Note:** If you are running a [virtual environment](.\TOOLS.md) you do not need to *add to path* as it should work fine.
175+
**Note:** If you are running a [virtual environment](./tools.md) you do not need to _add to path_ as it should work fine.
171176

172177
Typing `python3 -m` every time you want to run a module can get a little annoying. You can add the `Scripts` folder of your Python installation to your path. If you do not know where you have installed Python, run the following command in your terminal:
173178

@@ -176,15 +181,15 @@ $ python3 -c "import os, sys; print(os.path.dirname(sys.executable))"
176181
{python_directory}
177182
```
178183

179-
The *returned* directory is where your Python version is installed, in this tutorial it is referred to as `{python_directory}`.
184+
The _returned_ directory is where your Python version is installed, in this tutorial it is referred to as `{python_directory}`.
180185

181186
#### Windows
182187

183-
Click the `Windows Start` button and lookup *Edit the system environment variables* and press enter. Next press, `Environment Variables...`:
188+
Click the `Windows Start` button and lookup _Edit the system environment variables_ and press enter. Next press, `Environment Variables...`:
184189

185190
![Press the blue button, lol](https://raw.githubusercontent.com/exercism/python/main/docs/img/Windows-SystemProperties.png)
186191

187-
Then find the `Path` variable in your *User variables*, select it, and click `Edit...`:
192+
Then find the `Path` variable in your _User variables_, select it, and click `Edit...`:
188193

189194
![Selecting the path variable](https://raw.githubusercontent.com/exercism/python/main/docs/img/Windows-EnvironmentVariables.png)
190195

@@ -202,10 +207,10 @@ You can also create your own file with the following content:
202207

203208
```ini
204209
[pytest]
205-
markers =
210+
markers =
206211
task: A concept exercise task.
207212
```
208213

209-
Whenever you run your tests, make sure that this file is in your _root_ or _working_ directory.
214+
Whenever you run your tests, make sure that this file is in your _root_ or _working_ directory for Exercism exercises.
210215

211-
_More information on customizing pytest can be found in the [PyTest docs](https://docs.pytest.org/en/6.2.x/customize.html#pytest-ini)_
216+
_More information on customizing pytest can be found in the [PyTest docs](https://docs.pytest.org/en/6.2.x/customize.html#pytest-ini)_

‎docs/TOOLS.md‎

Lines changed: 9 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -9,32 +9,14 @@ Before you can start coding, make sure that you have the proper version of Pytho
99
---
1010

1111
- [Environments](#environments)
12-
- [Virtualenv](#venv)
12+
- [Venv](#venv)
1313
- [Conda](#conda)
14-
15-
- [Tools](#tools)
16-
- [Environments](#environments)
17-
- [Venv](#venv)
18-
- [Creating your virtual environment](#creating-your-virtual-environment)
19-
- [Activating your virtual environment](#activating-your-virtual-environment)
20-
- [Virtual Environment wrapper](#virtual-environment-wrapper)
21-
- [Conda](#conda)
22-
- [Activating your conda environment](#activating-your-conda-environment)
23-
- [Editors and IDEs](#editors-and-ides)
24-
- [Visual Studio Code](#visual-studio-code)
25-
- [Python for VS Code](#python-for-vs-code)
26-
- [Selecting the interpreter](#selecting-the-interpreter)
27-
- [Other features](#other-features)
28-
- [PyCharm](#pycharm)
29-
- [Selecting the interpreter](#selecting-the-interpreter-1)
30-
- [Other features](#other-features-1)
31-
- [Spyder IDE](#spyder-ide)
32-
- [Selecting the interpreter](#selecting-the-interpreter-2)
33-
- [Other features](#other-features-2)
34-
- [Sublime text](#sublime-text)
35-
- [Notable extensions](#notable-extensions)
36-
- [JupyterLab](#jupyterlab)
37-
- [Notable extensions](#notable-extensions-1)
14+
- [Editors and IDEs](#editors-and-ides)
15+
- [Visual Studio Code](#visual-studio-code)
16+
- [PyCharm](#pycharm)
17+
- [Spyder IDE](#spyder-ide)
18+
- [Sublime text](#sublime-text)
19+
- [JupyterLab](#jupyterlab)
3820

3921
---
4022

@@ -55,6 +37,7 @@ To create a virtual environment, `cd` to the directory you want to store your en
5537
```bash
5638
$ python3 -m venv {name_of_virtualenv}
5739
created virtual environment ... in 8568ms
40+
```
5841

5942
#### Activating your virtual environment
6043

@@ -146,7 +129,7 @@ Open your project, then navigate to `File` >> `Settings` >> `Project: ...` >> `P
146129

147130
![Interpreter Selection Dropdown](https://raw.githubusercontent.com/exercism/python/main/docs/img/PyCharm-Config-InterpreterDropDown.png)
148131

149-
From there click on the `+` button to add a new interpreter. Select the type of interpreter on the left. We suggest you either run a [conda]() or [virtualenv]() environment, but running the *system interpreter* works fine, too. Once you selected your interpreter, press the `Okay` button.
132+
From there click on the `+` button to add a new interpreter. Select the type of interpreter on the left. We suggest you either run a [conda](#conda) or [virtualenv](#venv) environment, but running the *system interpreter* works fine, too. Once you selected your interpreter, press the `Okay` button.
150133

151134
![Add New Interpreter](https://raw.githubusercontent.com/exercism/python/main/docs/img/PyCharm-Config-InterpreterNew.png)
152135

‎docs/config.json‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,13 @@
2727
"path": "docs/RESOURCES.md",
2828
"title": "Useful Python resources",
2929
"blurb": "A collection of useful resources to help you master Python"
30+
},
31+
{
32+
"uuid": "0dbb029b-ec67-4bbe-9ff7-483bf3a96af1",
33+
"slug": "tools",
34+
"path": "docs/TOOLS.md",
35+
"title": "Useful tools for local development",
36+
"blurb": "Useful tools that can help you with developing Python Exercism code on your own machine."
3037
}
3138
]
3239
}

0 commit comments

Comments
 (0)