Skip to content

Commit 04f455b

Browse files
author
Kenneth Reitz
committed
Merge pull request realpython#240 from dechols/master
Add new Reading section.
2 parents bd7cf67 + 7d22f84 commit 04f455b

File tree

3 files changed

+777
-731
lines changed

3 files changed

+777
-731
lines changed

‎docs/contents.rst.inc‎

Lines changed: 119 additions & 118 deletions
Original file line numberDiff line numberDiff line change
@@ -1,118 +1,119 @@
1-
Getting Started
2-
---------------
3-
4-
This part of the guide focuses on setting up your Python environment.
5-
6-
.. toctree::
7-
:maxdepth: 2
8-
9-
starting/which-python
10-
11-
- Properly Install Python
12-
13-
.. toctree::
14-
:maxdepth: 1
15-
16-
starting/install/osx
17-
starting/install/win
18-
starting/install/linux
19-
20-
21-
22-
Writing Great Code
23-
------------------
24-
25-
This part of the guide focuses on best practices for writing Python code.
26-
27-
.. toctree::
28-
:maxdepth: 2
29-
30-
writing/structure
31-
writing/style
32-
writing/documentation
33-
writing/tests
34-
writing/gotchas
35-
writing/license
36-
37-
38-
39-
Scenario Guide
40-
--------------
41-
42-
This part of the guide focuses on tool and module advice based on
43-
different scenarios.
44-
45-
.. toctree::
46-
:maxdepth: 2
47-
48-
scenarios/client
49-
scenarios/web
50-
scenarios/cli
51-
scenarios/gui
52-
scenarios/db
53-
scenarios/network
54-
scenarios/admin
55-
scenarios/ci
56-
scenarios/speed
57-
scenarios/scientific
58-
scenarios/imaging
59-
scenarios/xml
60-
61-
62-
Shipping Great Code
63-
-------------------
64-
65-
This part of the guide focuses on deploying your Python code.
66-
67-
.. toctree::
68-
:maxdepth: 2
69-
70-
shipping/packaging
71-
shipping/freezing
72-
73-
74-
Development Environment
75-
-----------------------
76-
77-
.. toctree::
78-
:maxdepth: 2
79-
80-
dev/env
81-
dev/virtualenvs
82-
83-
84-
85-
86-
Additional Notes
87-
----------------
88-
89-
This part of the guide, which is mostly prose, begins with some
90-
background information about Python, then focuses on next steps.
91-
92-
.. toctree::
93-
:maxdepth: 2
94-
95-
intro/duction
96-
intro/community
97-
intro/learning
98-
intro/documentation
99-
intro/news
100-
101-
102-
103-
104-
--------------------------------------
105-
106-
Contribution notes and legal information are here (for those interested).
107-
108-
.. toctree::
109-
:maxdepth: 2
110-
111-
notes/contribute
112-
notes/license
113-
notes/styleguide
114-
115-
116-
117-
118-
1+
Getting Started
2+
---------------
3+
4+
This part of the guide focuses on setting up your Python environment.
5+
6+
.. toctree::
7+
:maxdepth: 2
8+
9+
starting/which-python
10+
11+
- Properly Install Python
12+
13+
.. toctree::
14+
:maxdepth: 1
15+
16+
starting/install/osx
17+
starting/install/win
18+
starting/install/linux
19+
20+
21+
22+
Writing Great Code
23+
------------------
24+
25+
This part of the guide focuses on best practices for writing Python code.
26+
27+
.. toctree::
28+
:maxdepth: 2
29+
30+
writing/structure
31+
writing/style
32+
writing/reading
33+
writing/documentation
34+
writing/tests
35+
writing/gotchas
36+
writing/license
37+
38+
39+
40+
Scenario Guide
41+
--------------
42+
43+
This part of the guide focuses on tool and module advice based on
44+
different scenarios.
45+
46+
.. toctree::
47+
:maxdepth: 2
48+
49+
scenarios/client
50+
scenarios/web
51+
scenarios/cli
52+
scenarios/gui
53+
scenarios/db
54+
scenarios/network
55+
scenarios/admin
56+
scenarios/ci
57+
scenarios/speed
58+
scenarios/scientific
59+
scenarios/imaging
60+
scenarios/xml
61+
62+
63+
Shipping Great Code
64+
-------------------
65+
66+
This part of the guide focuses on deploying your Python code.
67+
68+
.. toctree::
69+
:maxdepth: 2
70+
71+
shipping/packaging
72+
shipping/freezing
73+
74+
75+
Development Environment
76+
-----------------------
77+
78+
.. toctree::
79+
:maxdepth: 2
80+
81+
dev/env
82+
dev/virtualenvs
83+
84+
85+
86+
87+
Additional Notes
88+
----------------
89+
90+
This part of the guide, which is mostly prose, begins with some
91+
background information about Python, then focuses on next steps.
92+
93+
.. toctree::
94+
:maxdepth: 2
95+
96+
intro/duction
97+
intro/community
98+
intro/learning
99+
intro/documentation
100+
intro/news
101+
102+
103+
104+
105+
--------------------------------------
106+
107+
Contribution notes and legal information are here (for those interested).
108+
109+
.. toctree::
110+
:maxdepth: 2
111+
112+
notes/contribute
113+
notes/license
114+
notes/styleguide
115+
116+
117+
118+
119+

‎docs/writing/reading.rst‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
Reading Great Code
2+
==================
3+
4+
One of the core tenants behind the design of Python is creating
5+
readable code. The motivation behind this design is simple: The number
6+
one thing that Python programmers do is read code.
7+
8+
One of the secrets of becoming a great Python programmer is to read,
9+
understand, and comprehend excellent code.
10+
11+
Excellent code typically follows the guidelines outlined in :ref:`code_style`,
12+
and does its best to express a clear and consise intent to the reader.
13+
14+
Included below is a list of recommended Python projects for reading. Each of
15+
these projects are paragons of excellent Python code.
16+
17+
- `Howdoi <https://github.com/gleitz/howdoi>`_
18+
Howdoi is a code search tool, written in Python.
19+
20+
- `Flask <https://github.com/mitsuhiko/flask>`_
21+
Flask is a microframework for Python based on Werkzeug and Jinja2.
22+
It's intended for getting started very quickly and was developed with
23+
best intentions in mind.
24+
25+
- `Werkzeug <https://github.com/mitsuhiko/werkzeug>`_
26+
Werkzeug started as simple collection of various utilities for WSGI
27+
applications and has become one of the most advanced WSGI utility modules.
28+
It includes a powerful debugger, full-featured request and response objects,
29+
HTTP utilities to handle entity tags, cache control headers, HTTP dates,
30+
cookie handling, file uploads, a powerful URL routing system and a bunch
31+
of community-contributed addon modules.
32+
33+
- `Requests <https://github.com/kennethreitz/requests>`_
34+
Requests is an Apache2 Licensed HTTP library, written in Python,
35+
for human beings.
36+
37+
- `Tablib <https://github.com/kennethreitz/tablib>`_
38+
Tablib is a format-agnostic tabular dataset library, written in Python.
39+
40+
.. todo:: Embed and explain YouTube video showing python code reading: http://www.youtube.com/watch?v=Jc8M9-LoEuo This may require installing a Sphinx plugin. https://bitbucket.org/birkenfeld/sphinx-contrib/src/a09f29fc16970f34350ca36ac7f229e00b1b1674/youtube?at=default
41+
42+
.. todo:: Include code examples of exemplary code from each of the projects listed. Explain why it is excellent code. Use complex examples.
43+
44+
.. todo:: Explain techniques to rapidly identify data structures, algorithms and determine what the code is doing.

0 commit comments

Comments
 (0)