new takeaway directive

.gitignore

@@ -9,4 +9,6 @@ local/
 scripts/
 _build/
 *~
+__pycache__/
+
 

_ext/takeaway.py

@@ -0,0 +1,50 @@
+from docutils import nodes
+from sphinx.util.docutils import SphinxDirective
+
+
+class takeaway_node(nodes.General, nodes.Element):
+    pass
+
+
+class TakeawayDirective(SphinxDirective):
+    has_content = True
+
+    def run(self):
+        node = takeaway_node()
+        self.state.nested_parse(self.content, self.content_offset, node)
+        return [node]
+
+
+def visit_takeaway_html(self, node):
+    self.body.append('<div class="takeaway">\n')
+
+
+def depart_takeaway_html(self, node):
+    self.body.append('</div>\n')
+
+
+def visit_takeaway_latex(self, node):
+    self.body.append('\n\\begin{takeawaybox}\n')
+
+
+def depart_takeaway_latex(self, node):
+    self.body.append('\n\\end{takeawaybox}\n')
+
+
+def visit_takeaway_text(self, node):
+    self.new_state(0)
+
+
+def depart_takeaway_text(self, node):
+    self.end_state()
+
+
+def setup(app):
+    app.add_node(
+        takeaway_node,
+        html=(visit_takeaway_html, depart_takeaway_html),
+        latex=(visit_takeaway_latex, depart_takeaway_latex),
+        text=(visit_takeaway_text, depart_takeaway_text),
+    )
+    app.add_directive('takeaway', TakeawayDirective)
+    return {'version': '0.1', 'parallel_read_safe': True}

_static/css/rtd_theme_mods.css

@@ -84,6 +84,39 @@ h3 {
   display: block;
 }
 
+.admonition-further-reading .admonition-title::before {
+    display: none;
+}
+
+.admonition .admonition-title {
+    background-color: #6a99d0;
+}
+
+div.takeaway {
+    position: relative;
+    background-color: #e7f2fa;
+    padding: 12px 16px 12px 3.236em;
+    margin: 12px 0 12px -3.236em;
+    border-radius: 0 4px 4px 0;
+}
+
+div.takeaway p:last-child {
+    margin-bottom: 0;
+}
+
+div.takeaway::before {
+    content: '';
+    position: absolute;
+    left: 12px;
+    top: 12px;
+    width: 28px;
+    height: 28px;
+    background-image: url('../bridge.png');
+    background-size: contain;
+    background-repeat: no-repeat;
+    background-position: center;
+}
+
 aside.sidebar {
     margin: 0 0 0.5em 1em;
     border: 1px solid #ddb;

applications/anatomy.rst

@@ -350,7 +350,7 @@ questions.
     site often in close proximity to users.
 
 
-.. admonition:: Systems Thinking Takeaway
+.. takeaway::
 
    An important takeaway from this discussion is that arbitrary
    computation can take place throughout the network, and not just at

applications/dash.rst

@@ -268,7 +268,7 @@ annoying. So this demands a different approach that doesn't rely on
 TCP for congestion control and reliable delivery. We will
 examine this problem space in Chapter |Stream|.
 
-.. admonition:: Systems Thinking Takeaway
+.. takeaway::
 
    The development of video streaming over HTTP and TCP illustrates
    the importance of looking at the interplay between protocol

applications/web.rst

@@ -417,7 +417,7 @@ transport/application boundary.
 
 .. The following is an example of the new design element. Exact name TBD
 
-.. admonition:: Systems Thinking Takeaway
+.. takeaway::
 
    An important lesson from this discussions is that layering
    decisions can have a profound impact on system behavior and

capacity/scheduler.rst

@@ -319,7 +319,7 @@ priority queue is empty. This approach has been implemented in some
 commercial routers to provide one low-latency queue and a set of DRR
 queues that share the remaining bandwidth in a weighted fair manner.
 
-.. admonition:: Systems Thinking Takeaway
+.. takeaway::
 
    The preceding discussion of queue management illustrates an
    important system design principle known as *separating policy and

conf.py

@@ -17,6 +17,8 @@
 # sys.path.insert(0, os.path.abspath('.'))
 
 import os
+import sys
+sys.path.insert(0, os.path.abspath('_ext'))
 
 from subprocess import check_output, CalledProcessError
 
@@ -62,6 +64,7 @@ def get_version():
     'sphinx.ext.todo',
     'sphinxcontrib.spelling',
     "sphinx_multiversion",
+    'takeaway',
 ]
 
 # Text files with lists of words that shouldn't fail the spellchecker:
@@ -89,7 +92,7 @@ def get_version():
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = [u'_build', 'venv-docs', 'requirements.txt', 'Thumbs.db', 'private', '.DS_Store', '*/README.rst', 'CONTRIBUTING.rst', 'software/*rst', '*/*rst']
+exclude_patterns = [u'_build', '_ext', 'venv-docs', 'requirements.txt', 'Thumbs.db', 'private', '.DS_Store', '*/README.rst', 'CONTRIBUTING.rst', 'software/*rst', '*/*rst']
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = None

federation/hetero.rst

@@ -505,7 +505,7 @@ only need those same four entries. This is a good first step (although
 by no means the last) in achieving scalability.
 
 .. _key-aggregation:
-.. admonition:: Systems Thinking Takeaway
+.. takeaway::
 
    This illustrates one of the most important principles of building
    scalable networks: To achieve scalability, you need to reduce the

introduction/architecture.rst

@@ -304,7 +304,7 @@ prescriptive since we can't know what applications and technologies
 will emerge over time, and (2) it makes the job of architecting the
 system easier if we keep our focus narrow.
 
-.. admonition:: Systems Thinking Takeaway
+.. takeaway::
 
    The separation of concerns principle can be summarized
    as follows: When faced with the design of a complex system, carve
@@ -418,7 +418,7 @@ network:
 This is why we highlight the fact that there is more to the end-to-end
 argument than the popular one-line summary.
 
-.. admonition:: Systems Thinking Takeaway
+.. takeaway::
 
    The end-to-end argument is one of the key principles in networking
    that helps a system designer decide where to place a function. It
@@ -430,7 +430,6 @@ argument than the popular one-line summary.
    it only in the end systems. It is a tool for reasoning about tradeoffs, not
    a hard-and-fast rule.
 
-
 As we walk through the
 system components that deliver the Internet's best-effort service in
 Part II we will see numerous examples of functions that are

operations/config.rst

@@ -390,7 +390,7 @@ with the system described earlier in this section, although it ends up
 being more bespoke than off-the-shelf. This makes it more cumbersome
 to maintain and evolve.
 
-.. admonition:: Systems Thinking Takeaway
+.. takeaway::
 
    A lesson illustrated by this example is that there is no single
    right set of tools for any problem space. Instead, you typically

operations/telemetry.rst

@@ -191,7 +191,7 @@ displays of the collected data.
    planning.
 
 
-.. admonition:: Systems Thinking Takeaway
+.. takeaway::
 
    This discussion illustrates one of the key tradeoffs in monitoring
    a system: our attempts to monitor can themselves have an impact on

policy/routingbgp.rst

@@ -168,7 +168,7 @@ have no-one higher up to depend on, so they must carry all the
 Internet's  routable prefixes in their routing tables.
 
 .. _key-scaling:
-.. admonition:: Systems Thinking Takeaway
+.. takeaway::
 
    The design of BGP illustrates again the principle of hierarchical
    aggregation of information to achieve scalability. First, the

routing/distancevector.rst

@@ -375,7 +375,7 @@ networks—those with no paths longer than 15 hops.
 
 
 .. _key-routing-alg:
-.. admonition:: Systems Thinking Takeaway
+.. takeaway::
 
    One of the most important tradeoffs to be made in networking systems
    is between distributed versus centralized control. Distance-vector