From 2d30675baa9f12f040442eed37072d14bb1718c5 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Fri, 16 Dec 2022 15:06:03 +0200 Subject: [PATCH] README: Update formatting and links --- README.rst | 94 +++++++++++++++++++++++++++++------------------------- 1 file changed, 51 insertions(+), 43 deletions(-) diff --git a/README.rst b/README.rst index e42a75926..e2f303fe9 100644 --- a/README.rst +++ b/README.rst @@ -32,10 +32,14 @@ language by making tests pass. Most tests are *fixed* by filling the missing parts of assert functions. Eg: +.. code-block:: python + self.assertEqual(__, 1+2) which can be fixed by replacing the __ part with the appropriate code: +.. code-block:: python + self.assertEqual(3, 1+2) Occasionally you will encounter some failing tests that are already filled out. @@ -50,11 +54,11 @@ a taste of Test Driven Development (TDD). Downloading Python Koans ------------------------ -Python Koans is available through git on Github: +Python Koans is available on GitHub: - http://github.com/gregmalcolm/python_koans +* https://github.com/gregmalcolm/python_koans -Either site will allow you to download the source as a zip/gz/bz2. +You can clone with Git or download the source as a zip/gz/bz2. Installing Python Koans @@ -63,7 +67,7 @@ Installing Python Koans Aside from downloading or checking out the latest version of Python Koans, you need to install the Python interpreter. -At this time of writing, we support Python3. The policy is to try to keep +At this time of writing, we support Python 3. The policy is to try to keep current with the latest production version. You should be able to work with newer Python versions, but older ones will @@ -71,17 +75,17 @@ likely give you problems. You can download Python from here: - http://www.python.org/download +* https://www.python.org/downloads/ After installing Python make sure the folder containing the python executable is in the system path. In other words, you need to be able to run Python from a -command console. It will either be `python3` or for windows it will be `python.exe`. +command console. It will either be ``python3`` or for Windows it will be ``python.exe``. If you have problems, this may help: - http://www.python.org/about/gettingstarted +* https://www.python.org/about/gettingstarted/ -Windows users may also want to update the line in the batch file `run.bat` to +Windows users may also want to update the line in the batch file ``run.bat`` to set the python path:: SET PYTHON_PATH=C:\Python39 @@ -92,19 +96,23 @@ Getting Started Jake Hebbert has created a couple of screencasts available here: -http://www.youtube.com/watch?v=e2WXgXEjbHY&list=PL5Up_u-XkWgNcunP_UrTJG_3EXgbK2BQJ&index=1 +https://www.youtube.com/watch?v=e2WXgXEjbHY&list=PL5Up_u-XkWgNcunP_UrTJG_3EXgbK2BQJ&index=1 Or if you prefer to read: -From a \*nix terminal or windows command prompt run:: +From a \*nix terminal or Windows command prompt run:: + +.. code-block:: sh python contemplate_koans.py -or:: +or: + +.. code-block:: sh python3 contemplate_koans.py -In my case I'm using Python 3 with windows, so I fire up my command +In my case I'm using Python 3 with Windows, so I fire up my command shell (cmd.exe) and run this: .. image:: https://user-images.githubusercontent.com/2614930/28401747-f723ff00-6cd0-11e7-9b9a-a6993b753cf6.png @@ -114,11 +122,13 @@ Apparently a test failed:: AssertionError: False is not True It also tells me exactly where the problem is, it's an assert on line 12 -of .\\koans\\about_asserts.py. This one is easy, just change False to True to +of ``.\\koans\\about_asserts.py``. This one is easy, just change ``False`` to ``True`` to make the test pass. Sooner or later you will likely encounter tests where you are not sure what the -expected value should be. For example:: +expected value should be. For example: + +.. code-block:: python class Dog: pass @@ -138,40 +148,51 @@ Sniffer Support Sniffer allows you to run the tests continuously. If you modify any files files in the koans directory, it will rerun the tests. -To set this up, you need to install sniffer:: +To set this up, you need to install sniffer: + +.. code-block:: sh - $ pip install sniffer + python3 -m pip install sniffer You should also run one of these libraries depending on your system. This will automatically trigger sniffer when a file changes, otherwise sniffer will have to poll to see if the files have changed. -On Linux:: +On Linux: + +.. code-block:: sh - $ pip install pyinotify + python3 -m pip install pyinotify -On Windows:: +On Windows: - $ pip install pywin32 +.. code-block:: sh + + python3 -m pip install pywin32 Also available here: https://github.com/mhammond/pywin32/releases -On Mac OS X:: +On macOS: + +.. code-block:: sh + + python3 -m pip install MacFSEvents - $ pip install MacFSEvents +Once it is set up, you just run: -Once it is set up, you just run:: +.. code-block:: sh - $ sniffer + sniffer -Just modify one of the koans files and you'll see that the tests are triggered automatically. Sniffer is controlled by `scent.py` +Just modify one of the koans files and you'll see that the tests are triggered +automatically. Sniffer is controlled by ``scent.py``. Getting the Most From the Koans ------------------------------- -Quoting the Ruby Koans instructions:: +Quoting the Ruby Koans instructions: "In test-driven development the mantra has always been, red, green, refactor. Write a failing test and run it (red), make the test pass @@ -182,28 +203,15 @@ Quoting the Ruby Koans instructions:: and improve the code to better communicate its intent (refactor)." -Content -------- - -The Python Koans is a made up of about 2/3 Ruby Koans ported material and 1/3 -Python specific tests. The content ported from Ruby Koans includes all the -assignment projects. - -Content for Python 3 is a little different to the Python 2 flavor due to big -changes between the two different versions of the language. For example, in -the Python 2 variant the differences between old and new style classes are -covered. This loses relevance in in the Python 3 version, but there are some -extra tests covering new functionality. - Finding More Koan Projects -------------------------- There are number of other great Koan projects out there for various languages -and frameworks. Most of them can be found in github. Also there is a little -koans activity on bitbucket. +and frameworks. Most of them can be found in GitHub. Also there is a little +koans activity on Bitbucket. -* Github koan projects: +* GitHub koan projects: https://github.com/search?q=koans&ref=cmdform * Bitbucket koan projects: @@ -228,7 +236,7 @@ Also thanks to everyone who has contributed to Python Koans! I got a great headstart by taking over a code base initiated by the combined Mikes of FPIP. So here's a little plug for their very cool Python podcast: - http://frompythonimportpodcast.com/ +* https://www.frompythonimportpodcast.com/ A big thanks also to Mike Pirnat @pirnat and Kevin Chase @kjc have pitched in as co-maintainers at various times