Merge pull request #69 from SystemsApproach/workflows

Add workflows to validate PRs and publish latest docs

.github/CODEOWNERS

@@ -0,0 +1,3 @@
+#require review
+* @llpeterson @drbruced12
+

.github/workflows/publish-docs.yml

@@ -0,0 +1,46 @@
+name: Publish Docs Workflow
+run-name: ${{ github.actor }} is publishing document artifacts 🚀
+on:
+  push:
+    branches:
+      - master
+
+
+          # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Single deploy job since we're just deploying
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+      - name: Build html
+        run: make html
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          # Upload build repository
+          path: './_build/html'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+
+
+
+      - run: echo "🍏 This job's status is ${{ job.status }}."

.github/workflows/validate-docs.yml

@@ -0,0 +1,22 @@
+name: Validate Docs Workflow
+run-name: ${{ github.actor }} is validating document source
+on: [pull_request, workflow_dispatch]
+jobs:
+  Validate_Docs:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo "🎉 The job was automatically triggered by a ${{ github.event_name }} event."
+      - run: echo "🐧 This job is now running on a ${{ runner.os }} server hosted by GitHub!"
+      - run: echo "🔎 The name of your branch is ${{ github.ref }} and your repository is ${{ github.repository }}."
+      - name: Check out repo
+        uses: actions/checkout@v4
+      - name: Validate source
+        run: make test
+      - name: Build html
+        run: make html
+      - name: List built files
+        run: |
+          ls ${{ github.workspace }}/_build/html
+
+      - run: echo "🍏 This job's status is ${{ job.status }}."
+

CLA.rst

@@ -4,7 +4,7 @@ Contributor License Agreement
 Thank you for contributing to COMPUTER NETWORKS: A SYSTEMS
 APPROACH (the “Work”). This Agreement between you (the “You”)
 and Elsevier Inc. regarding your Contribution to the Work (the
-“Contribution”) outlines our respective obligations and rights. 
+“Contribution”) outlines our respective obligations and rights.
 
 A. You grant to the Publisher a non-exclusive publishing and
 distribution license in the Contribution in print, electronic and

Makefile

@@ -26,8 +26,8 @@ $(VIRTUALENV):
   source ./$@/bin/activate ;\
   pip install -r requirements.txt
 
-# lint and link verification. linkcheck is built into sphinx
-test: lint spelling linkcheck
+# lint and spelling verification. linkcheck is built into sphinx
+test: lint spelling 
 
 # lint all .rst files
 lint: $(VIRTUALENV)

README.rst

@@ -44,7 +44,7 @@ Releases and Editions
 
 We release ever-changing open source content rather than publish fixed
 books, although you can roughly equate v6.0 with a 6th Edition. Read the
-`Preface <preface.html>`__ to find out what’s new in this version. Note
+:ref:`preface` to find out what’s new in this version. Note
 that Morgan Kaufmann (Elsevier)  published the 6th edition of the
 textbook based on a fork of v6.0, but going forward, open source
 releases found here will not necessarily stay in sync with any future
@@ -61,7 +61,7 @@ maintenance release (although we do not bother to tag it as such).
 Minor releases (e.g., v6.1) are tagged whenever there is sufficient new
 content to justify the effort. This happens quarterly, give-or-take, and
 is primarily to create a snapshot so that everyone in a course can know
-they are using the same version. 
+they are using the same version.
 
 Build the Book
 --------------
@@ -71,13 +71,13 @@ source:
 
 .. code:: shell
 
-   $ mkdir ~/systemsapproach 
-   $ cd ~/systemsapproach 
-   $ git clone https://github.com/systemsapproach/book.git 
+   $ mkdir ~/systemsapproach
+   $ cd ~/systemsapproach
+   $ git clone https://github.com/systemsapproach/book.git
    $ cd book
 
-The build process is stored in the ``Makefile`` and requires Python be 
-installed. The ``Makefile`` will create a virtualenv (``venv-docs``) which 
+The build process is stored in the ``Makefile`` and requires Python be
+installed. The ``Makefile`` will create a virtualenv (``venv-docs``) which
 installs the documentation generation toolset.  You may also need to
 install the ``enchant`` C library using your system’s package manager
 for the spelling checker to function properly.

applications.rst

@@ -1,7 +1,7 @@
 Chapter 9: Applications
 =======================
 
-   Now this is not the end. It is not even the beginning of the end. But 
+   Now this is not the end. It is not even the beginning of the end. But
    it is, perhaps, the end of the beginning.
 
    *—Winston Churchill*

applications/infrastructure.rst

@@ -123,7 +123,7 @@ addresses; we will come back to this issue later in this section.
 
 Like the Unix file hierarchy, the DNS hierarchy can be visualized as a
 tree, where each node in the tree corresponds to a domain, and the
-leaves in the tree correspond to the hosts being named. :numref:`Figure 
+leaves in the tree correspond to the hosts being named. :numref:`Figure
 %s <fig-domains>` gives an example of a domain hierarchy. Note that we
 should not assign any semantics to the term *domain* other than that it
 is simply a context in which additional names can be defined.\ [#]_
@@ -641,8 +641,8 @@ is actively pursuing is called gNMI (*gRPC Network Management
 Interface*). As you might guess from its name, gNMI uses gRPC, which you
 may recall, runs on top of HTTP. This means gNMI also adopts Protobufs
 as the way it specifies the data actually communicated over the HTTP
-connection. Thus, as depicted in :numref:`Figure %s <fig-mgmt>`, gNMI 
-is intended as a standard management interface for network devices. 
+connection. Thus, as depicted in :numref:`Figure %s <fig-mgmt>`, gNMI
+is intended as a standard management interface for network devices.
 What’s not standardized is the richness of the management tool’s ability to
 automate, or the exact form of the operator-facing interface. Like any
 application that is trying to serve a need and support more features

applications/multimedia.rst

@@ -126,7 +126,7 @@ a single character. For example, the line tells us that “version” has
 the value zero; that is, this message is formatted according to version
 zero of SDP. The next line provides the “origin” of the session which
 contains enough information to uniquely identify the session. ``larry``
-is a username of the session creator, and ``128.112.136.10`` is the IP 
+is a username of the session creator, and ``128.112.136.10`` is the IP
 address of his computer. The number following ``larry`` is a session
 identifier that is chosen to be unique to that machine. This is followed
 by a “version” number for the SDP announcement; if the session information

applications/overlays.rst

@@ -687,7 +687,7 @@ routing information propagates through the overlay.
 
 The reader may have noticed that although structured overlays provide a
 probabilistic bound on the number of routing hops required to locate a
-given object—the number of hops in Pastry is bounded by :math:`log_{16}N`, 
+given object—the number of hops in Pastry is bounded by :math:`log_{16}N`,
 where N is the number of nodes in the overlay—each hop may contribute
 substantial delay. This is because each intermediate node may be at a
 random location in the Internet. (In the worst case, each node is on a

applications/traditional.rst

@@ -12,7 +12,7 @@ that predated it). By contrast, later sections will look at a class of
 applications that have become popular more recently: streaming
 applications (e.g., multimedia applications like video and audio) and
 various overlay-based applications. (Note that there is a bit of a
-blurring between these classes, as we increasingly access 
+blurring between these classes, as we increasingly access
 streaming multimedia data over the Web, but for now we’ll focus on the
 general usage of the Web to request pages, images, etc.)
 
@@ -534,7 +534,7 @@ sounds, the ``POST`` command enables much mischief (including spam) on
 the Internet.
 
 .. _tab-ops:
-.. table::  HTTP Request Operations. 
+.. table::  HTTP Request Operations.
    :align: center
    :widths: auto
 
@@ -605,7 +605,7 @@ first digit of the code indicating its type. :numref:`Table %s <tab-codes>`
 summarizes the five types of codes.
 
 .. _tab-codes:
-.. table::  Five Types of HTTP Result Codes. 
+.. table::  Five Types of HTTP Result Codes.
    :align: center
    :widths: auto
 
@@ -801,12 +801,12 @@ exchange of certificates and encryption keys follows the establishment
 of a TCP session, QUIC handles these steps as part of session
 establishment, leading to a considerable reduction in the number of
 round-trips needed to establish a secure connection before the first
-content is delivered. 
+content is delivered.
 
 HTTP/3 is implemented in the majority of browsers and is incrementally
 being deployed on servers across the Internet. There remain
 plenty of servers running HTTP/2 and even some HTTP/1.1 as well, so version negotiation is
-likely to be part of HTTP implementations for the foreseeable future. 
+likely to be part of HTTP implementations for the foreseeable future.
 
 Caching
 ~~~~~~~

conf.py

@@ -103,9 +103,9 @@ def get_version():
     }
 
 # Ignore link check for the following websites
-# linkcheck_ignore = [
-#     'https://SDN.systemspproach.org/',
-# ]
+linkcheck_ignore = [
+     'https://www.amazon.com/', 'https://amzn.to',
+]
 
 # -- Options for HTML output -------------------------------------------------
 

congestion.rst

@@ -6,12 +6,12 @@ Chapter 6:  Congestion Control
    *—William Shakespeare*
 
 .. toctree::
-   :maxdepth: 2 
+   :maxdepth: 2
 
    congestion/problem.rst
-   congestion/issues.rst 
+   congestion/issues.rst
    congestion/queuing.rst
    congestion/tcpcc.rst
-   congestion/avoidance.rst       
-   congestion/qos.rst       
+   congestion/avoidance.rst
+   congestion/qos.rst
    congestion/trend.rst

congestion/issues.rst

@@ -109,7 +109,7 @@ reserved for a particular circuit are not available for use by other
 traffic even if they were not currently being used by that circuit. The
 focus of this chapter is on resource allocation approaches that apply in
 an internetwork, and thus we focus mainly on connectionless networks.
-   
+
 .. _fig-congestion:
 .. figure:: figures/f06-01-9780123850591.png
    :width: 500px
@@ -139,14 +139,14 @@ reason we introduce a new term is that a flow is visible to the
 routers inside the network, whereas a channel is an end-to-end
 abstraction. :numref:`Figure %s <fig-flow>` illustrates several flows
 passing through a series of routers.
-   
+
 .. _fig-flow:
 .. figure:: figures/f06-02-9780123850591.png
    :width: 500px
    :align: center
 
    Multiple flows passing through a set of routers.
-   
+
 Because multiple related packets flow through each router, it sometimes
 makes sense to maintain some state information for each flow,
 information that can be used to make resource allocation decisions about
@@ -391,7 +391,7 @@ improves as more jobs are admitted into the system, until it reaches a
 point when there are so many jobs running that the system begins to
 thrash (spends all of its time swapping memory pages) and the throughput
 begins to drop.
-   
+
 .. _fig-power:
 .. figure:: figures/f06-03-9780123850591.png
    :width: 350px
@@ -435,7 +435,7 @@ fair shares.  Should we also consider the length of the paths being
 compared? For example, as illustrated in :numref:`Figure %s
 <fig-path-len>`, what is fair when one four-hop flow is competing with
 three one-hop flows?
-   
+
 .. _fig-path-len:
 .. figure:: figures/f06-04-9780123850591.png
    :width: 600px
@@ -470,7 +470,7 @@ case is
 
    \frac{n^2}{n \times n} = 1
 
-Now, suppose one flow receives a throughput of :math:`1 + \Delta`. 
+Now, suppose one flow receives a throughput of :math:`1 + \Delta`.
 Now the fairness index is
 
 .. math::
@@ -480,7 +480,7 @@ Now the fairness index is
 
 Note that the denominator exceeds the numerator by :math:`(n-1)\Delta^2`.
 Thus, whether the odd flow out was getting more or less than all the
-other flows (positive or negative :math:`\Delta`), the fairness index has 
+other flows (positive or negative :math:`\Delta`), the fairness index has
 now dropped below one. Another simple case to
 consider is where only *k* of the *n* flows receive equal throughput,
 and the remaining *n-k* users receive zero throughput, in which case the

congestion/qos.rst

@@ -404,9 +404,9 @@ time. One way to describe the bandwidth characteristics of sources is
 called a *token bucket* filter. Such a filter is described by two
 parameters: a token rate *r*, and a bucket depth *B*. It works as
 follows. To be able to send a byte, I must have a token. To send a
-packet of length *n*, I need *n* tokens. I start with no 
-tokens and I accumulate them at a rate of *r* 
-per second. I can accumulate no more than *B* tokens. What this means is 
+packet of length *n*, I need *n* tokens. I start with no
+tokens and I accumulate them at a rate of *r*
+per second. I can accumulate no more than *B* tokens. What this means is
 that I can send a burst of as many as *B* bytes into the network as fast
 as I want, but over a sufficiently long interval I can’t send more than
 *r* bytes per second. It turns out that this information is very helpful
@@ -633,7 +633,7 @@ and no more. Calculating the correct overall TSpec from all of the
 sender TSpecs is clearly application specific. Also, we may only be
 interested in hearing from a subset of all possible speakers; RSVP has
 different reservation styles to deal with such options as “Reserve
-resources for all speakers,” “Reserve resources for any :math:`n` 
+resources for all speakers,” “Reserve resources for any :math:`n`
 speakers,” and “Reserve resources for speakers A and B only.”
 
 Packet Classifying and Scheduling
@@ -843,11 +843,11 @@ of another network service provider. The customer and the network
 service provider agree on some sort of profile for the assured service
 (and perhaps the customer pays the network service provider for this
 profile). The profile might be something like “Customer X is allowed to
-send up to :math:`y` Mbps of assured traffic,” 
+send up to :math:`y` Mbps of assured traffic,”
 or it could be significantly more complex.
 Whatever the profile is, the edge router can clearly mark the packets
 that arrive from this customer as being either in or out of profile. In
-the example just mentioned, as long as the customer sends less than 
+the example just mentioned, as long as the customer sends less than
 :math:`y` Mbps, all his packets will be marked “in,” but once he exceeds that
 rate the excess packets will be marked “out.”
 
@@ -896,7 +896,7 @@ queue a weight of 4, that ensures that the bandwidth available to
 premium packets is
 
 .. centered:: B\ :sub:`premium` = W\ :sub:`premium` / (W\ :sub:`premium`
-		   + W\ :sub:`best-effort`\ ) = 1/(1 + 4) = 0.2
+              + W\ :sub:`best-effort`\ ) = 1/(1 + 4) = 0.2
 
 That is, we have effectively reserved 20% of the link for premium
 packets, so if the offered load of premium traffic is only 10% of the