README.md 6.63 KB
Newer Older
1 2 3
# Apt / CloudLab Documentation

This repository contains the documentation for multiple testbed
Gary Wong's avatar
Gary Wong committed
4
environments---currently [Apt](https://aptlab.net),
Gary Wong's avatar
Gary Wong committed
5 6 7
[CloudLab](https://cloudlab.us), [PhantomNet](https://phantomnet.org),
and [Emulab](https://emulab.net).
The four have similar user interfaces and
Gary Wong's avatar
Gary Wong committed
8
concepts, so each share much documentation in common.
9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47

----------

## Building

### Dependencies

 * [Racket](http://download.racket-lang.org) - Make sure the Racket binaries
    (particularly `scribble`) are in your `$PATH`


 * [LaTeX (eg. TeX Live)](https://www.tug.org/texlive/) for building PDF
    copies of the manual. Most Linux distributions have LaTeX in their package
    managers, and there is a
    [package for Windows](https://www.tug.org/texlive/windows.html) and
    [OS X](https://www.tug.org/mactex/)

 * GNU make

### Building

To build HTML pages:

```
    make 
```

To build Apt HTML pages only:

```
    make apt
```

To build CloudLab HTML pages only:

```
    make cloudlab
```

Gary Wong's avatar
Gary Wong committed
48 49 50 51 52 53
To build PhantomNet HTML pages only:

```
    make phantomnet
```

Gary Wong's avatar
Gary Wong committed
54 55 56 57 58 59
To build Emulab HTML pages only:

```
    make emulab
```

Gary Wong's avatar
Gary Wong committed
60
To build PDFs for all testbeds: (warning: can be quite slow) 
61 62 63 64 65 66 67

```
    make pdf
```

### Viewing

Gary Wong's avatar
Gary Wong committed
68
Simply open `apt-manual/index.html`, `cloudlab-manual/index.html`,
Gary Wong's avatar
Gary Wong committed
69 70
`phantomnet-manual/index.html`, or `emulab-manual/index.html` in your browser.
PDFs are placed in the `pdf/` subdirectory.
71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87

----------

## Contributing

This manual is written in Scribble, a documentation tool that is distributed
as part of the Racket language. At a basic level, you can think of Scribble as
being somewhat LaTeX-like, with the main difference that the underlying
language is Racket (a language in the Lisp/Scheme family) rather than the TeX
macro system. Scribble is essentially Racket "inside-out"---most text is passed
directly to the output file, with the exception of Scribble commands, which
start with a `@` and can contain Racket code. Scribble is
[very well documented](http://docs.racket-lang.org/scribble/).

### General strategy for contributing

 * Fork the main [apt-manual](https://gitlab.flux.utah.edu/emulab/apt-manual)
88 89
   repository, and submit your changes as merge requests. Sign up for an
   account to do so.
90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191

 * Do **not** check in build products, such as the `.html` and `.pdf` files

 * Make sure that the `make all` and `make pdf` targets build properly before
   submitting pull requests

 * **Do** include reasonable commit message---they don't have to be long, but they
   should be meaningful. Author name and email address should be set correctly.

 * **Do** read through the existing manual and try to be consistent with the
   existing writing and source code styles.

 * Do **not** make gratuitous whitespace changes, it makes it harder to see the
   changes you've made.

### File/directory structure

Scribble files end in `.scrbl`. Each corresponds to a chapter. All Scribble
files in this manual include `defs.rkt`, which is written directly in Racket.

The toplevel file for the Apt manual is `apt-manual.scrbl`, and the toplevel file
for CloudLab is `cloudlab-manual.scrbl`. Most other `.scrbl` files are included
by these toplevel files. **If you add a new `.scrbl` file, make sure to include
it in both toplevel files** (unless it is only relevant to one of the testbeds).

The `screenshots/` directory contains subdirectories for Apt and CloudLab: when
screenshots are included (via the `@screenshot` command), the proper subdirectory
will be consulted. This is because the two have somewhat different UIs, and
it's confusing to see a screenshot from one in the manual for the other. **If you
add a new screenshot, make sure to include versions for both testbeds.** See more
on taking screenshots below.

The `code-samples/` directory is used for documentation of `geni-lib` scripts.

There are testbed-specific `.css` files for the HTML output of each of the two
manuals.

### Apt vs. CloudLab

Most of the material in this manual applies to either testbed. For the most
part, technical details are the same across both testbeds, unless they refer to
specific hardware. The biggest differences in the manual tend to be in text
related to policy. If you're not sure, just ask.

When referring to the testbed, use the `@(tb)` command, which will expand to
the name of the testbed that the manual is being built for.

For material that applies only to one testbed or the other, you can enclose it
in an `@apt-only{ }` or `@clab-only{ }` block.

For links, use the `@apturl` command, which prepends the URL of appropriate
testbed (*with* trailing slash) to the argument.

### Other custom commands

 * `@screenshot["FOO.png"]`
 
     Include screenshots/<testbed>/FOO.png, sized to the width of the current
     document

 * `@instructionstep["TITLE" #:screenshot "FOO.png"]{ BODY }`

    Intended for use in an `@itemlist`---formats multi-step tutorial content
    in a consistent way. The `#:screenshot` (and its argument) are optional; if
    included, they are placed at the beginning of the step.

 * `@future-work["TAG"]`

    Adds a note in the margin indicating that there is content eslewhere in
    the manual (probably `planned.scrbl`) describing a related feature that
    we are planning to add in the future

 * `@code-sample["FOO.py"]`

    Pulls in `code-samples/FOO.py`; used primarly to document geni-lib scripts.
    If possible, the script should be a fully-working, standalone python program,
    as we intend to start regression testing of the scripts in the world. The
    script should *not* however, contain the `#!` line at the top.

### Taking screenshots

All screenshots should be as "clean" as possible---this means no extraneous tabs,
UI elements such as add-ons, etc. If you use Firefox, one way of achieving this
is to create a new "profile" that has your usual add-ons, etc. disabled. 

The window should be sized such that the relevant UI elements fill it nicely. It
will automatically be re-sized in the documentation to be a constant width. The
screenshot should include the full browser window in order to provide context.

We take screenshots on a Mac, which has the added benefit of automatically adding
a nice drop-shadow around the window. The shortcut is `command-shift-4`, then
press `space`, then click on the window you want to take a shot of.

For tutorial content (for example, the CloudLab tutorial chapter), it can be
helpful to circle or otherwise highlight the relevant element. We ask that you
try to roughly keep the same style as existing screenshots (which are marked up
with Apple's Preview application).

All screenshots should be in `.png` format.

If you find it difficult at all to take screenshots that are consistent with the
rest of the manual, you can ask us to help take them.