Merge pull request #139 from daj-code/daj/better-docs

Small improvements to the floki documentation navigation and build/test process

Author: rlupton20

.github/PULL_REQUEST_TEMPLATE.md

@@ -15,4 +15,6 @@ Anything you think will be useful for reviewers.
 These aren't hard requirements, just guidelines
 
 - [ ] New/modified Rust code formatted with `cargo fmt`
+- [ ] Documentation and `README.md` updated for this change, if necessary
+- [ ] `CHANGELOG.md` updated for this change
 

CHANGELOG.md

@@ -17,6 +17,8 @@ Status: Available for use
 
 ### Added
 - Added Bors support
+- Added a navigation section to the documentation (temporary until documentation format is redesigned)
+- Added a floki config file for quickly running `hugo` for building and testing documentation
 
 ### Fixed
 - Don't require a floki config file to be present to run `floki completion`

README.md

@@ -28,7 +28,7 @@ Suppose we want a build environment based on `alpine:latest` with a C compiler,
 
 First create your `Dockerfile`:
 
-```
+```dockerfile
 FROM alpine:latest
 
 RUN apk update && apk add alpine-sdk clang openssh
@@ -37,7 +37,7 @@ RUN apk update && apk add alpine-sdk clang openssh
 and then add a file called `floki.yaml` to the root of your codebase:
 
 
-```
+```yaml
 image:
   build:
     name: hello-floki
@@ -55,8 +55,8 @@ Now run `floki`. You should see the docker container be built, and you will be d
 
 It's recommended you add your user to the `docker` group:
 
-```
-sudo usermod -a -G docker USERNAME
+```shell
+$ sudo usermod -a -G docker USERNAME
 ```
 
 and logout and in again to pick up the changes.
@@ -69,21 +69,21 @@ Precompiled binaries can be downloaded from the releases page (for linux and OSX
 
 To obtain `curl` and extract the latest linux binary directly in your shell, run
 
-```
+```shell
 $ curl -L https://github.com/Metaswitch/floki/releases/download/0.6.1/floki-0.6.1-linux.tar.gz | tar xzvf -
 ```
 
 You should be able to run `floki` from your working directory:
 
-```
+```shell
 $ ./floki --version
 floki 0.6.1
 ```
 
 Move it onto your path to run it from anywhere. E.g.
 
-```
-# mv floki /usr/local/bin/
+```shell
+$ mv floki /usr/local/bin/
 ```
 
 Enjoy!
@@ -92,7 +92,7 @@ Enjoy!
 
 `floki` can also be installed directly from `cargo`.
 
-```
+```shell
 $ cargo install floki
 ```
 

docs/content/documentation/getting-started.md

@@ -6,30 +6,54 @@ draft: false
 
 ## Installation
 
+### Prerequisites
+
+It's recommended you add your user to the `docker` group:
+
+```shell
+$ sudo usermod -a -G docker USERNAME
+```
+
+and logout and in again to pick up the changes.
+
+Alternatively you can run `floki` (after installation) with `sudo -E floki`.
+
+### Installation from pre-built binaries
+
 Precompiled binaries for linux and OSX can be downloaded from the [releases](https://github.com/Metaswitch/floki/releases) page.
 
 For example, to obtain the latest binary with `curl` and extract it, run
 
-```
+```shell
 $ curl -L https://github.com/Metaswitch/floki/releases/download/0.6.1/floki-0.6.1-linux.tar.gz | tar xzvf -
 ```
 
 in a shell. You should now be able to run `floki` from your working directory:
 
-```
+```shell
 $ ./floki --version
 floki 0.6.1
 ```
 
 Copy this into your path to run it without needing to specify the path absolutely. E.g.
 
+```shell
+$ mv floki /usr/local/bin/
 ```
-# mv floki /usr/local/bin/
+
+### Installation from cargo
+
+`floki` can also be installed directly from `cargo`.
+
+```shell
+$ cargo install floki
 ```
 
+### Shell completions
+
 Shell completions can be added to your existing shell session with
 
-```
+```shell
 source <(floki completion <shell>)
 ```
 
@@ -41,21 +65,21 @@ Enjoy!
 
 `floki` is configured using a configuration file typically placed in the root of your codebase. As a basic example, write a basic configuration file, and name it `floki.yaml`.
 
-```
+```yaml
 image: debian:latest
 init:
   - echo "Welcome to your first floki container!"
 ```
 
 Now, in the same directory, run
 
-```
+```shell
 floki
 ```
 
 A container will launch with the working directory mounted as your working directory. Verify this by running `ls`:
 
-```
+```shell
 $ ls
 ...  floki.yaml  ...
 ```
@@ -68,7 +92,7 @@ In general, invoking `floki` in any child directory of this root directory will
 
 You can use a different configuration file with `floki` by telling it to use a different file from the command line. For example, if you have another configuration in `config.yaml`, you can run `floki` with
 
-```
+```shell
 floki -c config.yaml
 ```
 

docs/content/intro/feature-overview.md

@@ -22,7 +22,7 @@ The ideal workflow is
 
 Using a prebuilt image (e.g. one from dockerhub or a docker registry) is as simple as providing its name as a top-level key in `floki.yaml`:
 
-```
+```yaml
 image: debian:sid
 ```
 
@@ -34,7 +34,7 @@ Custom registries can be used by configuring `docker` to use these registries. `
 
 `floki` can use an image built from a `Dockerfile` in source tree. It's easiest to see an example of `floki.yaml` to see how to configure this.
 
-```
+```yaml
 image:
   build:
     name: foo                    # Will build the image with name foo:floki
@@ -44,9 +44,9 @@ image:
 ```
 
 ## Referencing a key in another yaml file
-`floki` can use an image by reference to another yaml file. This can help keep local development environments sync'd with a CI environment.
+`floki` can use an image by reference to another yaml file. This can help keep local development environments synced with a CI environment.
 
-```
+```yaml
 image:
   yaml:
     file: .gitlab-ci.yaml
@@ -67,7 +67,7 @@ The default shell is `sh`.
 
 A shell can be set for a container using the top-level `shell` key:
 
-```
+```yaml
 image: alpine:latest
 shell: sh
 ```
@@ -76,7 +76,7 @@ shell: sh
 
 A different shell can be used for initialization and the interactive shell provided to the user.
 
-```
+```yaml
 image: alpine:latest
 shell:
   inner: bash
@@ -87,7 +87,7 @@ init:
 
 A useful use case here is if you want to run the container with the same user as on the host. `floki` exposes the user id and user group id in environment variables, so you can add a user to the running container and switch to the new user in the inner shell:
 
-```
+```yaml
 image: foo:latest
 shell:
   inner: bash
@@ -102,7 +102,7 @@ The commands to make the above work depend on the container you are running. `fl
 
 Docker-in-docker (`dind`) can be enabled by setting the top-level `dind` key to `true`.
 
-```
+```yaml
 image: foo:bar
 dind: true
 ```
@@ -111,7 +111,7 @@ Note that the docker CLI tools are still required in the container, and the dock
 
 The precise `dind` image can also be set
 
-```
+```yaml
 dind:
   image: docker:stable-dind
 ```
@@ -122,7 +122,7 @@ This helps properly pin and version the docker-in-docker container.
 
 `floki` has the ability to use volumes for caching build artifacts between runs of the container (amongst other things). Volumes can be configured in `floki.yaml`:
 
-```
+```yaml
 volumes:
   cargo-registry:
     mount: /home/rust/.cargo/registry
@@ -132,7 +132,7 @@ The key names the volume (it can be any valid yaml name), while the `mount` key
 
 It's also possible to share volumes across different `floki.yaml`s. For example, you may want to share a `cargo` registry across all Rust build containers. These shared volumes are identified by the name given to the volume.
 
-```
+```yaml
 volumes:
   cargo-registry:
     shared: true
@@ -162,7 +162,7 @@ You can set where this directory is mounted in the container using the `mount` k
 
 Sometimes it is useful to be able to pull dependencies from source code management servers for builds. To make this easier to do in an automated fashion, `floki` can forward and `ssh-agent` socket into the container, and expose its path through `SSH_AUTH_SOCK`.
 
-```
+```yaml
 forward_ssh_agent: true
 ```
 
@@ -172,7 +172,7 @@ You will need to have an `ssh-agent` running on the host before launching `floki
 
 `floki` also allows single commands to be run, rather than dropping into an interactive shell.
 
-```
+```shell
 $ floki run ls
 floki.yaml
 ```
@@ -184,7 +184,7 @@ Note that if you have configured an inner shell, the command will run within the
 
 `floki` also allows you to pass additional switches to the underlying docker command, for example to forward port `8080` to the host.
 
-```
+```yaml
 image: debian:sid
 docker_switches:
   - -p

docs/content/intro/navigation.md

@@ -0,0 +1,13 @@
+---
+title: "Navigation"
+date: 2020-12-21T20:26:44+00:00
+draft: false
+# Give heavy weight so that it appears at the top of the documentation homepage
+weight: 100
+---
+
+For installation, and basic usage, see [getting started]({{< ref "/documentation/getting-started.md" >}} "floki: Getting Started").
+
+For an overview of the features of `floki`, see the [feature overview]({{< ref "/intro/feature-overview.md" >}} "floki: Feature Overview").
+
+Full documentation can be found [here]({{< ref "/" >}} "floki: Documentation").

floki-hugo.yaml

@@ -0,0 +1,14 @@
+# For shell to work, need Alpine, Debian or Ubuntu versions of this container.
+# See https://hub.docker.com/r/klakegg/hugo/.
+image: klakegg/hugo:alpine
+mount: /src
+docker_switches:
+  # Expose port 1313, as this is the port the server exposes for locally built
+  # documentation.
+  - -p
+  - 1313:1313
+# The entrypoint for this container is a direct call to the "hugo" script. To
+# get a shell, we need to pass "shell" to this script, hence the "hack" of
+# setting "shell" to "shell".
+shell: shell
+# To run a hugo server, run "hugo server -D" from the /src/docs directory.

src/config.rs

@@ -120,7 +120,7 @@ impl FlokiConfig {
                     .parent()
                     .ok_or_else(|| errors::FlokiInternalError::InternalAssertionFailed {
                         description: format!(
-                            "could not constuct path to external yaml file '{:?}'",
+                            "could not construct path to external yaml file '{:?}'",
                             &yaml.file
                         ),
                     })?

src/errors.rs

@@ -52,7 +52,7 @@ pub enum FlokiError {
         exit_status: FlokiSubprocessExitStatus,
     },
 
-    #[fail(display = "Failed to check existance of image '{}': {}", image, error)]
+    #[fail(display = "Failed to check existence of image '{}': {}", image, error)]
     FailedToCheckForImage { image: String, error: io::Error },
 
     #[fail(display = "Failed to find the key '{}' in file '{}'", key, file)]