Fixed all H2 headings

Before, H2 fomratting was not consistent. Now, all H2 headings use over/under asterisks.
2026-06-05 14:50:19 +00:00 · 2018-12-04 13:44:41 -07:00
parent 58fe178325
commit 35c13bc9ea
43 changed files with 532 additions and 203 deletions
@@ -1,5 +1,8 @@
+
+
+#############
 Documentation
-=============
+#############

 .. image:: /_static/photos/35620636012_f66aa88f93_k_d.jpg

@@ -7,8 +10,10 @@ Readability is a primary focus for Python developers, in both project
 and code documentation. Following some simple best practices can save
 both you and others a lot of time.

+
+*********************
 Project Documentation
---------------------
+*********************

 A :file:`README` file at the root directory should give general information
 to both users and maintainers of a project. It should be raw text or
@@ -32,8 +37,10 @@ planned development for the code.
 A :file:`CHANGELOG` file or section in :file:`README` should compile a short
 overview of the changes in the code base for the latest versions.

+
+*******************
 Project Publication
-------------------
+*******************

 Depending on the project, your documentation might include some or all
 of the following components:
@@ -97,8 +104,9 @@ Reference`_ should help you familiarize yourself with its syntax.
 .. _reStructuredText Quick Reference: http://docutils.sourceforge.net/docs/user/rst/quickref.html


+*************************
 Code Documentation Advice
-------------------------
+*************************

 Comments clarify the code and they are added with purpose of making the
 code easier to understand. In Python, comments begin with a hash
@@ -249,8 +257,10 @@ For further reading on docstrings, feel free to consult :pep:`257`
 .. _sphinx.ext.napoleon: https://sphinxcontrib-napoleon.readthedocs.io/
 .. _`NumPy style`: http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html

+
+***********
 Other Tools
-----------
+***********

 You might see these in the wild. Use :ref:`sphinx-ref`.

@@ -1,5 +1,8 @@
+
+
+##############
 Common Gotchas
-==============
+##############

 .. image:: /_static/photos/34435688380_b5a740762b_k_d.jpg

@@ -16,8 +19,10 @@ the surprise.

 .. _default_args:

+
+*************************
 Mutable Default Arguments
-------------------------
+*************************

 Seemingly the *most* common surprise new Python programmers encounter is
 Python's treatment of mutable default arguments in function definitions.
@@ -88,8 +93,9 @@ to maintain state between calls of a function. This is often done when writing
 a caching function.


+****************************
 Late Binding Closures
---------------------
+****************************

 Another common source of confusion is the way Python binds its variables in
 closures (or in the surrounding global scope).
@@ -189,9 +195,9 @@ lots of situations. Looping to create unique functions is unfortunately a case
 where they can cause hiccups.


-
+*********************************
 Bytecode (.pyc) Files Everywhere!
---------------------------------
+*********************************

 By default, when executing Python code from files, the Python interpreter
 will automatically write a bytecode version of that file to disk, e.g.
@@ -1,5 +1,8 @@
+
+
+##################
 Choosing a License
-==================
+##################

 .. image:: /_static/photos/33907149294_82d7535a6c_k_d.jpg

@@ -1,5 +1,8 @@
+
+
+#######
 Logging
-=======
+#######

 .. image:: /_static/photos/35254379756_c9fe23f843_k_d.jpg

@@ -17,8 +20,9 @@ Logging serves two purposes:
  reports or to optimize a business goal.


+*************
 ... or Print?
-------------
+*************

 The only time that ``print`` is a better option than logging is when
 the goal is to display a help statement for a command line application.
@@ -34,8 +38,9 @@ Other reasons why logging is better than ``print``:
  :attr:`logging.Logger.disabled` to ``True``.


+********************
 Logging in a Library
--------------------
+********************

 Notes for `configuring logging for a library`_ are in the
 `logging tutorial`_.  Because the *user*, not the library, should
@@ -61,8 +66,9 @@ this in your ``__init__.py``
    logging.getLogger(__name__).addHandler(logging.NullHandler())


+*************************
 Logging in an Application
-------------------------
+*************************

 The `twelve factor app <http://12factor.net>`_, an authoritative reference
 for good practice in application development, contains a section on
@@ -1,5 +1,8 @@
+
+
+##################
 Reading Great Code
-==================
+##################

 .. image:: /_static/photos/34689452831_93d7fd0571_k_d.jpg

@@ -1,5 +1,8 @@
+
+
+########################
 Structuring Your Project
-========================
+########################

 .. image:: /_static/photos/33907151224_0574e7dfc2_k_d.jpg

@@ -21,9 +24,9 @@ project. We then discuss various perspectives on how to build code which
 can be extended and tested reliably.


-
+***************************
 Structure of the Repository
---------------------------
+***************************

 It's Important.
 :::::::::::::::
@@ -313,9 +316,9 @@ The resulting structure:



-
+************************
 Structure of Code is Key
------------------------
+************************

 Thanks to the way imports and modules are handled in Python, it is
 relatively easy to structure a Python project. Easy, here, means
@@ -366,8 +369,9 @@ include:
  task at hand, you might be swimming in ravioli code.


+*******
 Modules
-------
+*******

 Python modules are one of the main abstraction layers available and probably the
 most natural one. Abstraction layers allow separating code into parts holding
@@ -476,8 +480,9 @@ Being able to tell immediately where a class or function comes from, as in the
 all but the simplest single file projects.


+********
 Packages
--------
+********

 Python provides a very straightforward packaging system, which is simply an
 extension of the module mechanism to a directory.
@@ -509,8 +514,10 @@ Lastly, a convenient syntax is available for importing deeply nested packages:
 ``import very.deep.module as mod``. This allows you to use `mod` in place of the
 verbose repetition of ``very.deep.module``.

+
+***************************
 Object-oriented programming
---------------------------
+***************************

 Python is sometimes described as an object-oriented programming language. This
 can be somewhat misleading and needs to be clarified.
@@ -587,8 +594,9 @@ things that are manipulated (windows, buttons, avatars, vehicles) have a
 relatively long life of their own in the computer's memory.


+**********
 Decorators
----------
+**********

 The Python language provides a simple yet powerful syntax called 'decorators'.
 A decorator is a function or a class that wraps (or decorates) a function
@@ -621,8 +629,10 @@ expensive function in a table and use them directly instead of recomputing
 them when they have already been computed. This is clearly not part
 of the function logic.

+
+****************
 Context Managers
----------------
+****************

 A context manager is a Python object that provides extra contextual information
 to an action. This extra information takes the form of running a callable upon
@@ -694,8 +704,10 @@ to decide when to use which. The class approach might be better if there's
 a considerable amount of logic to encapsulate. The function approach
 might be better for situations where we're dealing with a simple action.

+
+**************
 Dynamic typing
--------------
+**************

 Python is dynamically typed, which means that variables do not have a fixed
 type. In fact, in Python, variables are very different from what they are in
@@ -758,8 +770,10 @@ a `final` keyword and it would be against its philosophy anyway. However, it may
 be a good discipline to avoid assigning to a variable more than once, and it
 helps in grasping the concept of mutable and immutable types.

+
+***************************
 Mutable and immutable types
---------------------------
+***************************

 Python has two kinds of built-in or user-defined types.

@@ -873,16 +887,20 @@ like above or in cases where you are adding to an existing string, using
    foobar = '{foo}{bar}'.format(foo=foo, bar=bar) # It is best


+************************
 Vendorizing Dependencies
------------------------
+************************


+
+*******
 Runners
-------
+*******


+***************
 Further Reading
---------------
+***************

 - http://docs.python.org/2/library/
 - http://www.diveintopython.net/toc/index.html
@@ -1,7 +1,9 @@
 .. _code_style:

+
+##########
 Code Style
-==========
+##########

 .. image:: /_static/photos/33907150054_5ee79e8940_k_d.jpg

@@ -21,8 +23,10 @@ what is considered the best (hear: most readable) way.
 On some border cases, no best way has been agreed upon on how to express
 an intent in Python code, but these cases are rare.

+
+****************
 General concepts
----------------
+****************

 Explicit code
 ~~~~~~~~~~~~~
@@ -260,8 +264,10 @@ is needed.
       return x  # One single exit point for the returned value x will help
                 # when maintaining the code.

+
+******
 Idioms
------
+******

 A programming idiom, put simply, is a *way* to write code. The notion of
 programming idioms is discussed amply at `c2 <http://c2.com/cgi/wiki?ProgrammingIdiom>`_
@@ -417,8 +423,9 @@ hashtable will often be greater than the time saved by the improved search
 speed.


+*************
 Zen of Python
-------------
+*************

 Also known as :pep:`20`, the guiding principles for Python's design.

@@ -450,8 +457,10 @@ Also known as :pep:`20`, the guiding principles for Python's design.
 For some examples of good Python style, see `these slides from a Python user
 group <http://artifex.org/~hblanks/talks/2011/pep20_by_example.pdf>`_.

+
+*****
 PEP 8
-----
+*****

 :pep:`8` is the de-facto code style guide for Python. A high quality,
 easy-to-read version of PEP 8 is also available at `pep8.org <http://pep8.org/>`_.
@@ -504,8 +513,10 @@ Excluding the ``--in-place`` flag will cause the program to output the modified
 code directly to the console for review. The ``--aggressive`` flag will perform
 more substantial changes and can be applied multiple times for greater effect.

+
+***********
 Conventions
----------------
+***********

 Here are some conventions you should follow to make your code easier to read.

@@ -1,5 +1,8 @@
+
+
+#################
 Testing Your Code
-=================
+#################

 .. image:: /_static/photos/34435687940_8f73fc1fa6_k_d.jpg

@@ -71,8 +74,11 @@ Some general rules of testing:
  be to add a test to ensure that the new functionality is not already a
  working path that has not been plugged into the interface.

+
+
+**********
 The Basics
-::::::::::
+**********


 Unittest
@@ -136,8 +142,10 @@ When running this module from the command line as in ``python module.py``, the
 doctests will run and complain if anything is not behaving as described in the
 docstrings.

+
+*****
 Tools
-:::::
+*****


 py.test