Merge branch 'master' of https://github.com/Akuli/Python-Tutorial

Akuli · Akuli · commit f9a2e3fcee68 · 2017-03-03T16:48:07.000+02:00
diff --git a/advanced/README.md b/advanced/README.md
@@ -0,0 +1,31 @@
+[comment]: # (This file is automatically generated. Don't edit this
+              file manually, run update-readmes.py instead.)
+
+# Advanced
+
+If you want to learn more advanced techniques, you can also read this
+section. Most of the techniques explained here are great when you're
+working on a large project, and your code would be really repetitive
+without these things.
+
+You can experient with these things freely, but please **don't use these
+techniques just because you know how to use them.** Prefer the simple
+techniques from the Basics part instead when possible. Simple is better
+than complex.
+
+1. [Handy data types](datatypes.md)
+2. [Advanced stuff with functions](functions.md)
+3. [Magic methods](magicmethods.md)
+4. [Iterables, iterators and generators](iters.md)
+
+***
+
+If you have trouble with this tutorial please [tell me about
+it](../contact-me.md) and I'll make this tutorial better. If you
+like this tutorial, please [give it a
+star](../README.md#how-can-i-thank-you-for-writing-and-sharing-this-tutorial).
+
+You may use this tutorial freely at your own risk. See
+[LICENSE](../LICENSE).
+
+[List of contents](../README.md#list-of-contents)
diff --git a/basics/README.md b/basics/README.md
@@ -0,0 +1,40 @@
+[comment]: # (This file is automatically generated. Don't edit this
+              file manually, run update-readmes.py instead.)
+
+# Basics
+
+This section will get you started with using Python and you'll be able
+to learn more about whatever you want after studying it.
+
+1. [What is programming?](what-is-programming.md)
+2. [Installing Python](installing-python.md)
+3. [Getting started with Python](getting-started.md)
+4. [ThinkPython: The way of the program](the-way-of-the-program.md)
+5. [Variables, Booleans and None](variables.md)
+6. [Using functions](using-functions.md)
+7. [Setting up an editor](editor-setup.md)
+8. [If, else and elif](if.md)
+9. [Handy stuff with strings](handy-stuff-strings.md)
+10. [Lists and tuples](lists-and-tuples.md)
+11. [Loops](loops.md)
+12. [Trey Hunner: zip and enumerate](trey-hunner-zip-and-enumerate.md)
+13. [Dictionaries](dicts.md)
+14. [Defining functions](defining-functions.md)
+15. [Writing a larger program](larger-program.md)
+16. [What is true?](what-is-true.md)
+17. [Files](files.md)
+18. [Modules](modules.md)
+19. [Exceptions](exceptions.md)
+20. [Classes](classes.md)
+
+***
+
+If you have trouble with this tutorial please [tell me about
+it](../contact-me.md) and I'll make this tutorial better. If you
+like this tutorial, please [give it a
+star](../README.md#how-can-i-thank-you-for-writing-and-sharing-this-tutorial).
+
+You may use this tutorial freely at your own risk. See
+[LICENSE](../LICENSE).
+
+[List of contents](../README.md#list-of-contents)
diff --git a/classes.md b/classes.md
@@ -1 +1,13 @@
 This file has been moved [here](basics/classes.md).
+
+***
+
+If you have trouble with this tutorial please [tell me about
+it](./contact-me.md) and I'll make this tutorial better. If you
+like this tutorial, please [give it a
+star](./README.md#how-can-i-thank-you-for-writing-and-sharing-this-tutorial).
+
+You may use this tutorial freely at your own risk. See
+[LICENSE](./LICENSE).
+
+[List of contents](./README.md#list-of-contents)
diff --git a/common.py b/common.py
@@ -69,17 +69,33 @@ def find_links(file):
 def get_markdown_files():
     """Yield the names of all markdown files in this tutorial.
 
-    This assumes that the README contains links to everything. The
-    yielded paths use / as the path separator.
+    The yielded paths use / as the path separator.
     """
-    yield 'README.md'
-    with open('README.md', 'r') as f:
-        for match, lineno in find_links(f):
-            target = posixpath.normpath(match.group(2))
-            # Currently he README links to itself, but we don't want to
-            # break things if it will be modified not to link in the future.
-            if target.endswith('.md') and target != 'README.md':
-                yield target
+    for root, dirs, files in os.walk('.'):
+        for file in files:
+            if not file.endswith('.md'):
+                continue
+            path = os.path.normpath(os.path.join(root, file))
+            yield path.replace(os.sep, '/')
+
+
+def header_link(title):
+    """Return a github-style link target for a title.
+
+    >>> header_link('Hello there!')
+    'hello-there'
+    """
+    # This doesn't do the-title-1, the-title-2 etc. with multiple titles
+    # with same text, but usually this doesn't matter.
+    result = ''
+    for character in title:
+        if character in string.whitespace:
+            result += '-'
+        elif character in string.punctuation:
+            pass
+        else:
+            result += character.lower()
+    return result
 
 
 def askyesno(question, default=True):
diff --git a/make-html.py b/make-html.py
@@ -32,7 +32,6 @@
 import os
 import posixpath
 import shutil
-import string
 import sys
 import textwrap
 import webbrowser
diff --git a/strip.py b/strip.py
diff --git a/update-readmes.py b/update-readmes.py
@@ -0,0 +1,116 @@
+#!/usr/bin/env python3
+
+# This is free and unencumbered software released into the public
+# domain.
+
+# Anyone is free to copy, modify, publish, use, compile, sell, or
+# distribute this software, either in source code form or as a
+# compiled binary, for any purpose, commercial or non-commercial, and
+# by any means.
+
+# In jurisdictions that recognize copyright laws, the author or
+# authors of this software dedicate any and all copyright interest in
+# the software to the public domain. We make this dedication for the
+# benefit of the public at large and to the detriment of our heirs
+# and successors. We intend this dedication to be an overt act of
+# relinquishment in perpetuity of all present and future rights to
+# this software under copyright law.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY
+# CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
+# CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+# For more information, please refer to <http://unlicense.org>
+
+"""Generate basics/README.md and advanced/README.md."""
+
+import os
+import posixpath
+
+import common
+
+
+BEGINNING = """\
+[comment]: # (This file is automatically generated. Don't edit this
+              file manually, run update-readmes.py instead.)
+
+"""
+
+
+def get_contents():
+    """Read descriptions and contents lists from README.
+
+    Return a {chaptername: content} dictionary.
+    """
+    result = {} 
+    current_section = None
+
+    with open('README.md', 'r') as f:
+        # move to where the content list starts
+        while f.readline().strip() != "## List of contents":
+            pass
+
+        for line in f:
+            if line.startswith('### '):
+                # new section
+                current_section = common.header_link(line.lstrip('#').strip())
+                result[current_section] = line[2:]  # one # instead of 3
+            elif line.startswith('## '):
+                # end of content lists
+                break
+            elif current_section is not None:
+                # we are currently in a section
+                result[current_section] += line
+
+    return result
+
+
+def update_file(filename, content):
+    """Make sure that a file contains the content.
+
+    Return True if the file changed and False if it didn't.
+    """
+    try:
+        with open(filename, 'r') as f:
+            # ignore the end
+            old_content = f.read().split('\n***\n')[0].rstrip()
+        if old_content == content:
+            print("Has correct content:", filename)
+            return False
+    except FileNotFoundError:
+        # the file doesn't exist yet, we'll create it
+        pass
+
+    print("Writing new content:", filename)
+    with open(filename, 'w') as f:
+        print(content, file=f)
+    return True
+
+
+def main():
+    something_changed = False
+    for directory, content in sorted(get_contents().items()):
+        if not os.path.exists(directory):
+            # something else under the list of contents than a chapter
+            # list, doesn't have a separate subdirectory
+            print("Not a directory:", directory)
+            continue
+
+        # the links that point to the subdir must now point to the
+        # current directory, so we fix that
+        content = BEGINNING + content.replace(directory + '/', '').rstrip()
+        path = os.path.join(directory, 'README.md')
+        this_changed = update_file(path, content)
+        something_changed = something_changed or this_changed
+
+    if something_changed:
+        print()
+        print("Run update-ends.py now so the files will have correct ends.")
+
+
+if __name__ == '__main__':
+    main()
diff --git a/what-next.md b/what-next.md
@@ -28,3 +28,15 @@ is a way to create generators
 | `from stuff import *`     | imports everything
 
 ## Fun modules
+
+***
+
+If you have trouble with this tutorial please [tell me about
+it](./contact-me.md) and I'll make this tutorial better. If you
+like this tutorial, please [give it a
+star](./README.md#how-can-i-thank-you-for-writing-and-sharing-this-tutorial).
+
+You may use this tutorial freely at your own risk. See
+[LICENSE](./LICENSE).
+
+[List of contents](./README.md#list-of-contents)
