Merge pull request #1436 from stevenengler/docs

stevenengler · web-flow · commit 19cd3a7e9f56 · 2021-06-15T13:05:55.000-04:00
Formatting changes to docs
diff --git a/README.md b/README.md
@@ -41,7 +41,7 @@ code on top of real OS kernels in real time, but are non-determinsitic and have
 limited scalability: time distortion can occur if emulated processes exceed an
 unknown computational threshold, leading to undefined behavior.
 
-Network simulators (e.g., [ns-3](https://www.nsnam.org) ) offer more
+Network simulators (e.g., [ns-3](https://www.nsnam.org)) offer more
 experimental control and scalability, but have limited realism because they run
 application abstractions in place of real application code.
 
diff --git a/docs/ci.md b/docs/ci.md
@@ -1,14 +1,14 @@
-## Continuous integration tests
+# Continuous integration tests
 
-### On GitHub
+## On GitHub
 
 Our continuous integration tests build and test Shadow on every supported
 platform and configuration. GitHub runs these tests automatically when making
 or modifying a pull request, in the [build and test
 workflow](../.github/workflows/build_shadow.yml). Pull requests without passing
 integration tests are blocked from merging.
 
-### Running locally
+## Running locally
 
 We also have scripts for running the continuous integration tests locally,
 inside Docker containers. This can be useful for debugging and for quickly
@@ -40,7 +40,7 @@ sudo ci/run.sh -i -o "ubuntu:18.04;clang;debug fedora:33;gcc;release"
 
 For additional options, run `ci/run.sh -h`.
 
-### Debugging locally
+## Debugging locally
 
 After a local run fails, you can use Docker to help debug it. If you previously
 ran the tests without the `-i` option, re-run with the `-i` option to rebuild
diff --git a/docs/coding_style.md b/docs/coding_style.md
@@ -1,6 +1,6 @@
-## Coding style
+# Coding style
 
-### Clang-format
+## Clang-format
 
 Our C code formatting style is defined in our
 [clang-format](https://clang.llvm.org/docs/ClangFormat.html) [configuration
@@ -31,9 +31,9 @@ Examples:
 (cd src/support/logger/rust_bindings && cargo fmt)
 ```
 
-### Including headers
+## Including headers
 
-#### Which headers to include
+### Which headers to include
 
 Every source and header file should directly include the headers that export
 all referenced symbols and macros.
@@ -53,7 +53,7 @@ This style is loosely based on that used in
 supported by the [include what you use](https://include-what-you-use.org/)
 tool.
 
-#### Inclusion style
+### Inclusion style
 
 Headers included from within the project should use quote-includes, and should
 use paths relative to `src/`. e.g. `#include "main/utility/byte_queue.h"`, not
diff --git a/docs/contributing.md b/docs/contributing.md
@@ -1,4 +1,4 @@
-## Contributing
+# Contributing
 
 For trivial fixes (e.g. fixing typos or bugs spanning only a few
 lines), feel free to send a pull request with your changes.  For
diff --git a/docs/developer_guide.md b/docs/developer_guide.md
@@ -1,3 +1,5 @@
+# Debugging and profiling
+
 ## Building the C-Rust bindings
 
 When required, you can rebuild all of the C-Rust bindings by running:
diff --git a/docs/install_dependencies.md b/docs/install_dependencies.md
@@ -1,6 +1,6 @@
-## Installing Dependencies
+# Installing Dependencies
 
-#### Required:
+### Required:
   + gcc, gcc-c++ (or clang, clang++)
   + python (version >= 3.6)
   + glib (version >= 2.32.0)
@@ -11,13 +11,13 @@
   + procps
   + cargo, rustc (version \~ latest)
 
-#### Recommended Python Modules (for helper/analysis scripts):
+### Recommended Python Modules (for helper/analysis scripts):
   + numpy, scipy, matplotlib, networkx, lxml, pyyaml
 
-#### Recommended System Tools:
+### Recommended System Tools:
   + git, dstat, htop, tmux
 
-### APT (Debian/Ubuntu):
+## APT (Debian/Ubuntu):
 
 ```bash
 # required dependencies
@@ -57,7 +57,7 @@ sudo apt-get install -y \
     tmux
 ```
 
-### YUM (Fedora/CentOS):
+## YUM (Fedora/CentOS):
 
 In more recent versions of Fedora and CentOS, `yum` can be exchanged for `dnf`
 in these commands. Before running these commands, please check any
@@ -107,7 +107,7 @@ sudo yum install -y \
     tmux
 ```
 
-#### CentOS 7
+### CentOS 7
 
 You must enable the EPEL repository using:
 
@@ -126,7 +126,7 @@ alternatives --install /usr/local/bin/cmake cmake /usr/bin/cmake3 20 \
     --family cmake
 ```
 
-#### CentOS 8
+### CentOS 8
 
 As procps-ng-devel, igraph, and igraph-devel are not available on CentOS 8, you
 must install them manually.
diff --git a/docs/install_shadow_with_docker.md b/docs/install_shadow_with_docker.md
@@ -1,4 +1,4 @@
-## Run from the Dockerfile
+# Run from the Dockerfile
 
 1. Install docker from https://docs.docker.com/engine/install/.
 2. Build container:
diff --git a/docs/maintainer_playbook.md b/docs/maintainer_playbook.md
@@ -1,6 +1,6 @@
-## Maintainer playbook
+# Maintainer playbook
 
-### Tagging Shadow releases
+## Tagging Shadow releases
 
 We use [Semantic Versioning](https://semver.org/), and increment version
 numbers with the [bumpversion](https://pypi.org/project/bumpversion/) tool.
diff --git a/docs/migrating_from_1x.md b/docs/migrating_from_1x.md
@@ -15,7 +15,7 @@ scripts will either:
    Shadow, Shadow will raise an error for this unexpected field.
 2. Ignore it and output a warning.
 
-### Converting a configuration file to the Shadow 2.0 format
+## Converting a configuration file to the Shadow 2.0 format
 
 The following will create a new configuration file `my-shadow-config.yaml`.
 
@@ -35,7 +35,7 @@ use the
 option to use the Shadow 1.x working directory, but this is an experimental
 option and may be removed in the future.
 
-### Converting a network graph file to the Shadow 2.0 format
+## Converting a network graph file to the Shadow 2.0 format
 
 The following will create a new network graph file `my-shadow-topology.gml`.
 
diff --git a/docs/network_graph_overview.md b/docs/network_graph_overview.md
@@ -1,4 +1,4 @@
-### Network Graph Overview
+# Network Graph Overview
 
 Processes running in Shadow do not have access to the internet; instead,
 processes running on Shadow virtual hosts utilize an internal routing module to
@@ -14,7 +14,7 @@ routers (we do not run routing protocols like
 
 This page describes the routing module and how it can be configured.
 
-#### Graph
+## Graph
 
 Shadow represents a network topology over which processes can communicate using
 a [weighted graph](https://en.wikipedia.org/wiki/Graph_(discrete_mathematics)).
@@ -32,7 +32,7 @@ Shadow requires that the network graph is
 there exists at least one _path_ (a series of one or more edges) between every
 pair of nodes.
 
-#### Behavior
+## Behavior
 
 The graph encodes network positioning and path characteristics as attributes on
 the nodes and edges. Shadow uses the connectivity graph along with the
@@ -50,7 +50,7 @@ The bandwidth of the virtual hosts and the end-to-end latency and packet loss
 for a shortest path between two virtual hosts are then enforced for all network
 communication.
 
-#### Important Notes
+## Important Notes
 
   - The network graph may be directed or undirected, as long as the graph is
     structured such that every node can reach every other node through a
@@ -62,14 +62,14 @@ communication.
     [use_shortest_path
     option](shadow_config_spec.md#networkuse_shortest_path) to `False`.
 
-### Network Graph Attributes
+## Network Graph Attributes
 
 We encode attributes on the nodes and edges that allow for configuring the
 simulated network characteristics. The attributes and their effect on the
 simulated network are described in more detail (alongside a simple example
 graph) on [the network graph specification page](network_graph_spec.md).
 
-### Using an Existing Graph
+## Using an Existing Graph
 
 We created a large network graph representing worldwide latencies and bandwidths
 as of 2018 using the [RIPE Atlas measurement platform](https://atlas.ripe.net).
@@ -86,7 +86,7 @@ advanced knowledge of RIPE Atlas and also require that you possess RIPE Atlas
 credits to conduct the measurements needed to create a new graph. We recommend
 using our existing graph linked above instead, which we may periodically update.
 
-### Creating Your Own Graph
+## Creating Your Own Graph
 
 The python module [networkx](http://networkx.github.io/) can be used to create
 and manipulate more complicated graphs.
diff --git a/docs/network_graph_spec.md b/docs/network_graph_spec.md
@@ -1,4 +1,4 @@
-### Network Graph Specification
+# Network Graph Specification
 
 The [network graph overview](network_graph_overview.md) provides a general
 summary of Shadow's use of a network graph to abstractly model network position
diff --git a/docs/pull_requests.md b/docs/pull_requests.md
@@ -1,6 +1,6 @@
-## Pull requests (PRs)
+# Pull requests (PRs)
 
-### Clean commits
+## Clean commits
 
 Ideally, every commit in history of the `main` branch should:
 
@@ -10,7 +10,7 @@ Ideally, every commit in history of the `main` branch should:
 * Build (`./setup build --test`).
 * Pass tests (`./setup test`).
 
-### Drafting a PR
+## Drafting a PR
 
 PRs should be split into smaller, more focused, changes when feasible.
 However, we also want to avoid polluting the history with commits that don't
@@ -28,7 +28,7 @@ Once done iterating, first consider using `git rebase -i --autosquash` to clean
 up your commit history, and then force pushing to update your PR.  Finally, take
 the pull request out of draft mode to signal that you're ready for review.
 
-### Responding to review feedback
+## Responding to review feedback
 
 *During* PR review, please do not rebase or force-push, since this makes it
 difficult to see what's changed between rounds of review. Consider using
@@ -37,7 +37,7 @@ can be appropriately squashed before the final merge. [git autofixup](
 https://github.com/torbiak/git-autofixup/) can also be useful for generating
 `--fixup` commits.
 
-### Merging
+## Merging
 
 When the PR is ready to be merged, the reviewer might ask you to `git rebase`
 and force push to clean up history, or might do it themselves.
diff --git a/docs/shadow_config_overview.md b/docs/shadow_config_overview.md
@@ -32,12 +32,12 @@ expressed in units of seconds or larger.
 
 Acceptable units are:
 
-- "nanosecond" / "ns"
-- "microsecond" / "us" / "μs"
-- "millisecond" / "ms"
-- "second" / "sec" / "s"
-- "minute" / "min" / "m"
-- "hour" / "hr" / "h"
+- nanosecond / ns
+- microsecond / us / μs
+- millisecond / ms
+- second / sec / s
+- minute / min / m
+- hour / hr / h
 
 Examples: `30 s`, `2 hr`, `10 minutes`, `100 ms`
 
@@ -49,14 +49,14 @@ is invalid, but `30 Kbit` is valid).
 
 Acceptable unit *prefixes* are:
 
-- "kilo" / "K"
-- "kibi" / "Ki"
-- "mega" / "M"
-- "mebi" / "Mi"
-- "giga" / "G"
-- "gibi" / "Gi"
-- "tera" / "T"
-- "tebi" / "Ti"
+- kilo / K
+- kibi / Ki
+- mega / M
+- mebi / Mi
+- giga / G
+- gibi / Gi
+- tera / T
+- tebi / Ti
 
 Examples: `100 Mbit`, `100 Mbits`, `10 kilobits`, `128 bits`
 
@@ -66,13 +66,13 @@ Byte size values are expressed with the unit `byte` or `B`.
 
 Acceptable unit *prefixes* are:
 
-- "kilo" / "K"
-- "kibi" / "Ki"
-- "mega" / "M"
-- "mebi" / "Mi"
-- "giga" / "G"
-- "gibi" / "Gi"
-- "tera" / "T"
-- "tebi" / "Ti"
+- kilo / K
+- kibi / Ki
+- mega / M
+- mebi / Mi
+- giga / G
+- gibi / Gi
+- tera / T
+- tebi / Ti
 
 Examples: `20 B`, `100 MB`, `100 megabyte`, `10 kibibytes`, `30 MiB`, `1024 Mbytes`
diff --git a/docs/shadow_config_spec.md b/docs/shadow_config_spec.md
@@ -190,7 +190,7 @@ The network graph can be specified in the GML format, or a built-in
 
 #### `network.graph.<path|inline>`
 
-*Required if `network.graph.type` is `gml`*  
+*Required if `network.graph.type` is "gml"*  
 Type: String
 
 If the network graph type is not a built-in network graph, the graph data can be
@@ -201,7 +201,7 @@ current user's home directory.
 
 #### `network.use_shortest_path`
 
-*Required*
+*Required*  
 Type: Bool
 
 When routing packets, follow the shortest path rather than following a direct
@@ -317,7 +317,7 @@ performance in most cases.
 
 #### `experimental.use_o_n_waitpid_workarounds`
 
-Default: false
+Default: false  
 Type: Bool
 
 Use performance workarounds for waitpid being O(n). Beneficial to disable if
@@ -440,7 +440,7 @@ e.g. wireshark).
 
 #### `hosts`
 
-*Required*
+*Required*  
 Type: Object
 
 The simulated hosts which execute processes. Each field corresponds to a host
diff --git a/docs/supported_platforms.md b/docs/supported_platforms.md
@@ -1,4 +1,4 @@
-## Supported Platforms
+# Supported Platforms
 
 Shadow officially supports the following platforms:
 
diff --git a/docs/system_configuration.md b/docs/system_configuration.md

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-## Contributing`
	`1`	`+# Contributing`
`2`	`2`
`3`	`3`	`For trivial fixes (e.g. fixing typos or bugs spanning only a few`
`4`	`4`	`lines), feel free to send a pull request with your changes. For`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+# Debugging and profiling`
	`2`	`+`
`1`	`3`	`## Building the C-Rust bindings`
`2`	`4`
`3`	`5`	`When required, you can rebuild all of the C-Rust bindings by running:`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-## Run from the Dockerfile`
	`1`	`+# Run from the Dockerfile`
`2`	`2`
`3`	`3`	`1. Install docker from https://docs.docker.com/engine/install/.`
`4`	`4`	`2. Build container:`