Merge pull request #2676 from davidism/tutorial

rewrite tutorial docs and example

CONTRIBUTING.rst

@@ -75,7 +75,7 @@ First time setup
 .. _latest version of git: https://git-scm.com/downloads
 .. _username: https://help.github.com/articles/setting-your-username-in-git/
 .. _email: https://help.github.com/articles/setting-your-email-in-git/
-.. _Fork: https://github.com/pallets/flask/pull/2305#fork-destination-box
+.. _Fork: https://github.com/pallets/flask/fork
 .. _Clone: https://help.github.com/articles/fork-a-repo/#step-2-create-a-local-clone-of-your-fork
 
 Start coding

docs/conf.py

@@ -11,13 +11,13 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 from __future__ import print_function
+
+import datetime
 import os
 import sys
-import pkg_resources
 import time
-import datetime
 
-from sphinx.application import Sphinx
+import pkg_resources
 
 BUILD_DATE = datetime.datetime.utcfromtimestamp(int(os.environ.get('SOURCE_DATE_EPOCH', time.time())))
 
@@ -300,7 +300,7 @@ def update_wrapper(wrapper, wrapped, *a, **kw):
 del unwrap_decorators
 
 
-def setup(app: Sphinx):
+def setup(app):
     def cut_module_meta(app, what, name, obj, options, lines):
         """Remove metadata from autodoc output."""
         if what != 'module':
@@ -312,3 +312,34 @@ def cut_module_meta(app, what, name, obj, options, lines):
         ]
 
     app.connect('autodoc-process-docstring', cut_module_meta)
+
+    def github_link(
+        name, rawtext, text, lineno, inliner,
+        options=None, content=None
+    ):
+        app = inliner.document.settings.env.app
+        release = app.config.release
+        base_url = 'https://github.com/pallets/flask/tree/'
+
+        if text.endswith('>'):
+            words, text = text[:-1].rsplit('<', 1)
+            words = words.strip()
+        else:
+            words = None
+
+        if release.endswith('dev'):
+            url = '{0}master/{1}'.format(base_url, text)
+        else:
+            url = '{0}{1}/{2}'.format(base_url, release, text)
+
+        if words is None:
+            words = url
+
+        from docutils.nodes import reference
+        from docutils.parsers.rst.roles import set_classes
+        options = options or {}
+        set_classes(options)
+        node = reference(rawtext, words, refuri=url, **options)
+        return [node], []
+
+    app.add_role('gh', github_link)

docs/installation.rst

@@ -104,6 +104,8 @@ On Windows:
 
     \Python27\Scripts\virtualenv.exe venv
 
+.. _install-activate-env:
+
 Activate the environment
 ~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/patterns/jquery.rst

@@ -162,7 +162,5 @@ explanation of the little bit of code above:
    argument.  Note that we can use the `$SCRIPT_ROOT` variable here that
    we set earlier.
 
-If you don't get the whole picture, download the `sourcecode
-for this example
-<https://github.com/pallets/flask/tree/master/examples/jqueryexample>`_
-from GitHub.
+If you don't get the whole picture, download the :gh:`sourcecode
+for this example <examples/jqueryexample>`.

docs/patterns/packages.rst

@@ -17,9 +17,8 @@ this::
             login.html
             ...
 
-If you find yourself stuck on something, feel free
-to take a look at the source code for this example.
-You'll find `the full src for this example here`_.
+The :ref:`tutorial <tutorial>` is structured this way, see the
+:gh:`example code <examples/tutorial>`.
 
 Simple Packages
 ---------------
@@ -59,21 +58,21 @@ a big problem, just add a new file called :file:`setup.py` next to the inner
         ],
     )
 
-In order to run the application you need to export an environment variable 
-that tells Flask where to find the application instance:: 
+In order to run the application you need to export an environment variable
+that tells Flask where to find the application instance::
 
     export FLASK_APP=yourapplication
 
-If you are outside of the project directory make sure to provide the exact 
+If you are outside of the project directory make sure to provide the exact
 path to your application directory. Similarly you can turn on the
 development features like this::
 
     export FLASK_ENV=development
 
-In order to install and run the application you need to issue the following 
+In order to install and run the application you need to issue the following
 commands::
 
-    pip install -e . 
+    pip install -e .
     flask run
 
 What did we gain from this?  Now we can restructure the application a bit
@@ -134,7 +133,6 @@ You should then end up with something like that::
 
 
 .. _working-with-modules:
-.. _the full src for this example here: https://github.com/pallets/flask/tree/master/examples/patterns/largerapp
 
 Working with Blueprints
 -----------------------

docs/testing.rst

@@ -28,10 +28,7 @@ The Application
 
 First, we need an application to test; we will use the application from
 the :ref:`tutorial`.  If you don't have that application yet, get the
-source code from `the examples`_.
-
-.. _the examples:
-   https://github.com/pallets/flask/tree/master/examples/flaskr/
+source code from :gh:`the examples <examples/tutorial>`.
 
 The Testing Skeleton
 --------------------