diff --git a/.gitignore b/.gitignore index 808ea55..2b65252 100644 --- a/.gitignore +++ b/.gitignore @@ -9,4 +9,6 @@ local/ scripts/ _build/ *~ +__pycache__/ + diff --git a/_ext/takeaway.py b/_ext/takeaway.py new file mode 100644 index 0000000..2cbc03b --- /dev/null +++ b/_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('
\n') + + +def depart_takeaway_html(self, node): + self.body.append('
\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} diff --git a/_static/bridge.png b/_static/bridge.png new file mode 100644 index 0000000..732735b Binary files /dev/null and b/_static/bridge.png differ diff --git a/_static/css/rtd_theme_mods.css b/_static/css/rtd_theme_mods.css index fd5f88f..b9efc90 100644 --- a/_static/css/rtd_theme_mods.css +++ b/_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; diff --git a/_static/scale.png b/_static/scale.png new file mode 100644 index 0000000..dfc2fe3 Binary files /dev/null and b/_static/scale.png differ diff --git a/applications/anatomy.rst b/applications/anatomy.rst index de9193d..d9f69da 100644 --- a/applications/anatomy.rst +++ b/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 diff --git a/applications/dash.rst b/applications/dash.rst index dc212e0..f77b9dd 100644 --- a/applications/dash.rst +++ b/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 diff --git a/applications/web.rst b/applications/web.rst index d9eb8ad..164ca93 100644 --- a/applications/web.rst +++ b/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 diff --git a/capacity/scheduler.rst b/capacity/scheduler.rst index 3f54213..f97be5f 100644 --- a/capacity/scheduler.rst +++ b/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 diff --git a/conf.py b/conf.py index 4e0617d..8954f06 100644 --- a/conf.py +++ b/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 diff --git a/federation/hetero.rst b/federation/hetero.rst index 5a94bfa..c50a780 100644 --- a/federation/hetero.rst +++ b/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 diff --git a/introduction/architecture.rst b/introduction/architecture.rst index e987699..f4dfea4 100644 --- a/introduction/architecture.rst +++ b/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 diff --git a/operations/config.rst b/operations/config.rst index 9fc5b0a..dbbbdb5 100644 --- a/operations/config.rst +++ b/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 diff --git a/operations/telemetry.rst b/operations/telemetry.rst index 2fc0e7b..619084e 100644 --- a/operations/telemetry.rst +++ b/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 diff --git a/policy/routingbgp.rst b/policy/routingbgp.rst index e3f1627..7bf9617 100644 --- a/policy/routingbgp.rst +++ b/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 diff --git a/routing/distancevector.rst b/routing/distancevector.rst index 6f38d6f..4781678 100644 --- a/routing/distancevector.rst +++ b/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