docs: Replace static page with mdBook site
Uses mdBook[1] to generate a documentation overview page instead of the previous HTML site. This makes it possible to add more elaborate documentation without having to deal with finicky markup. [1]: https://github.com/rust-lang-nursery/mdBook
This commit is contained in:
parent
099c99b7ad
commit
7c41a7a872
11 changed files with 97 additions and 108 deletions
2
tools/nixery/.gitattributes
vendored
Normal file
2
tools/nixery/.gitattributes
vendored
Normal file
|
@ -0,0 +1,2 @@
|
|||
# Ignore stylesheet modifications for the book in Linguist stats
|
||||
*.css linguist-detectable=false
|
1
tools/nixery/docs/.gitignore
vendored
Normal file
1
tools/nixery/docs/.gitignore
vendored
Normal file
|
@ -0,0 +1 @@
|
|||
book
|
8
tools/nixery/docs/book.toml
Normal file
8
tools/nixery/docs/book.toml
Normal file
|
@ -0,0 +1,8 @@
|
|||
[book]
|
||||
authors = ["Vincent Ambo <tazjin@google.com>"]
|
||||
language = "en"
|
||||
multilingual = false
|
||||
src = "src"
|
||||
|
||||
[output.html]
|
||||
additional-css = ["theme/nixery.css"]
|
4
tools/nixery/docs/src/SUMMARY.md
Normal file
4
tools/nixery/docs/src/SUMMARY.md
Normal file
|
@ -0,0 +1,4 @@
|
|||
# Summary
|
||||
|
||||
- [Nixery](./nixery.md)
|
||||
- [Nix, the language](./nix-1p.md)
|
2
tools/nixery/docs/src/nix-1p.md
Normal file
2
tools/nixery/docs/src/nix-1p.md
Normal file
|
@ -0,0 +1,2 @@
|
|||
This page is a placeholder. During the build process, it is replaced by the
|
||||
actual `nix-1p` guide from https://github.com/tazjin/nix-1p
|
Before Width: | Height: | Size: 190 KiB After Width: | Height: | Size: 190 KiB |
77
tools/nixery/docs/src/nixery.md
Normal file
77
tools/nixery/docs/src/nixery.md
Normal file
|
@ -0,0 +1,77 @@
|
|||
![Nixery](./nixery-logo.png)
|
||||
|
||||
------------
|
||||
|
||||
Welcome to this instance of [Nixery][]. It provides ad-hoc container images that
|
||||
contain packages from the [Nix][] package manager. Images with arbitrary
|
||||
packages can be requested via the image name.
|
||||
|
||||
Nix not only provides the packages to include in the images, but also builds the
|
||||
images themselves by using an interesting layering strategy described in [this
|
||||
blog post][layers].
|
||||
|
||||
## Quick start
|
||||
|
||||
Simply pull an image from this registry, separating each package you want
|
||||
included by a slash:
|
||||
|
||||
docker pull nixery.dev/shell/git/htop
|
||||
|
||||
This gives you an image with `git`, `htop` and an interactively configured
|
||||
shell. You could run it like this:
|
||||
|
||||
docker run -ti nixery.dev/shell/git/htop bash
|
||||
|
||||
Each path segment corresponds either to a key in the Nix package set, or a
|
||||
meta-package that automatically expands to several other packages.
|
||||
|
||||
Meta-packages **must** be the first path component if they are used. Currently
|
||||
the only meta-package is `shell`, which provides a `bash`-shell with interactive
|
||||
configuration and standard tools like `coreutils`.
|
||||
|
||||
**Tip:** When pulling from a private Nixery instance, replace `nixery.dev` in
|
||||
the above examples with your registry address.
|
||||
|
||||
## FAQ
|
||||
|
||||
If you have a question that is not answered here, feel free to file an issue on
|
||||
Github so that we can get it included in this section. The volume of questions
|
||||
is quite low, thus by definition your question is already frequently asked.
|
||||
|
||||
### Where is the source code for this?
|
||||
|
||||
Over [on Github][Nixery]. It is licensed under the Apache 2.0 license. Consult
|
||||
the documentation entries in the sidebar for information on how to set up your
|
||||
own instance of Nixery.
|
||||
|
||||
### Which revision of `nixpkgs` is used for the builds?
|
||||
|
||||
The instance at `nixery.dev` tracks a recent NixOS channel, currently NixOS
|
||||
19.03. The channel is updated several times a day.
|
||||
|
||||
Private registries might be configured to track a different channel (such as
|
||||
`nixos-unstable`) or even track a git repository with custom packages.
|
||||
|
||||
### Is this an official Google project?
|
||||
|
||||
**No.** Nixery is not officially supported by Google.
|
||||
|
||||
### Should I depend on `nixery.dev` in production?
|
||||
|
||||
While we appreciate the enthusiasm, if you would like to use Nixery in your
|
||||
production project we recommend setting up a private instance. The public Nixery
|
||||
at `nixery.dev` is run on a best-effort basis and we make no guarantees about
|
||||
availability.
|
||||
|
||||
### Who made this?
|
||||
|
||||
Nixery was written mostly by [tazjin][].
|
||||
|
||||
[grahamc][] authored the image layering strategy. Many people have contributed
|
||||
to Nix over time, maybe you could become one of them?
|
||||
|
||||
[Nixery]: https://github.com/google/nixery
|
||||
[Nix]: https://nixos.org/nix
|
||||
[layers]: https://grahamc.com/blog/nix-and-layered-docker-images
|
||||
[tazjin]: https://github.com/tazjin
|
||||
[grahamc]: https://github.com/grahamc
|
BIN
tools/nixery/docs/theme/favicon.png
vendored
Normal file
BIN
tools/nixery/docs/theme/favicon.png
vendored
Normal file
Binary file not shown.
After Width: | Height: | Size: 16 KiB |
3
tools/nixery/docs/theme/nixery.css
vendored
Normal file
3
tools/nixery/docs/theme/nixery.css
vendored
Normal file
|
@ -0,0 +1,3 @@
|
|||
h2, h3 {
|
||||
margin-top: 1em;
|
||||
}
|
Binary file not shown.
Before Width: | Height: | Size: 164 KiB |
|
@ -1,108 +0,0 @@
|
|||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<title>Nixery</title>
|
||||
<style>
|
||||
body {
|
||||
margin: 40px auto;
|
||||
max-width: 650px;
|
||||
line-height: 1.6;
|
||||
font-size: 18px;
|
||||
color: #444;
|
||||
padding: 010px
|
||||
}
|
||||
|
||||
.logo {
|
||||
max-width: 650px;
|
||||
}
|
||||
|
||||
h1, h2, h3 {
|
||||
line-height: 1.2
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<header>
|
||||
<div align="center">
|
||||
<img class="logo" src="nixery-logo.png">
|
||||
</div>
|
||||
<aside>ad-hoc container images - powered by <a href="https://nixos.org/nix/">Nix</a></aside>
|
||||
<hr>
|
||||
</header>
|
||||
|
||||
<p>
|
||||
This is an instance
|
||||
of <a href="https://github.com/google/nixery">Nixery</a>, which
|
||||
provides the ability to pull ad-hoc container images from a
|
||||
Docker-compatible registry server. The image names specify the
|
||||
contents the image should contain, which are then retrieved and
|
||||
built by the Nix package manager.
|
||||
</p>
|
||||
<p>
|
||||
Nix is also responsible for the creation of the container images
|
||||
themselves. To do this it uses an interesting layering strategy
|
||||
described in
|
||||
<a href="https://grahamc.com/blog/nix-and-layered-docker-images">this blog post</a>.
|
||||
</p>
|
||||
<h3>How does it work?</h3>
|
||||
<p>
|
||||
Simply point your local Docker installation (or other compatible
|
||||
registry client) at Nixery and ask for an image with the
|
||||
contents you desire. Image contents are path separated in the
|
||||
name, so for example if you needed an image that contains a
|
||||
shell and <code>emacs</code> you could pull it as such:
|
||||
</p>
|
||||
<p>
|
||||
<code>nixery.dev/shell/emacs25-nox</code>
|
||||
</p>
|
||||
<p>
|
||||
Image tags are currently ignored. Every package name needs to
|
||||
correspond to a key in the
|
||||
<a href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/all-packages.nix">nixpkgs package set</a>.
|
||||
</p>
|
||||
<p>
|
||||
The special meta-package <i>shell </i> provides default packages
|
||||
you would expect in an interactive environment (such as an
|
||||
interactively configured bash). If you use this package
|
||||
you <b>must</b> specify it as the first package in an image.
|
||||
</p>
|
||||
<h3>FAQ</h3>
|
||||
<ul>
|
||||
<li>
|
||||
<strong>Where is the source code for this?</strong>
|
||||
<br>
|
||||
Over <a href="https://github.com/google/nixery">on Github</a>.
|
||||
</li>
|
||||
<li>
|
||||
<strong>Which revision of <code>nixpkgs</code> is used?</strong>
|
||||
<br>
|
||||
Nixery imports a Nix channel
|
||||
via <code>builtins.fetchTarball</code>. Currently the channel
|
||||
to which this instance is pinned is NixOS 19.03.
|
||||
</li>
|
||||
<li>
|
||||
<strong>Is this an official Google project?</strong>
|
||||
<br>
|
||||
<strong>No.</strong> Nixery is not officially supported by
|
||||
Google.
|
||||
</li>
|
||||
<li>
|
||||
<strong>Can I depend on the demo instance in production?</strong>
|
||||
<br>
|
||||
<strong>No.</strong> The demo instance is just a demo. It
|
||||
might go down, move, or disappear entirely at any point.
|
||||
<br>
|
||||
To make use of Nixery in your project, please deploy a private
|
||||
instance. Stay tuned for instructions for how to do this on
|
||||
GKE.
|
||||
</li>
|
||||
<li>
|
||||
<strong>Who made this?</strong>
|
||||
<br>
|
||||
<a href="https://github.com/tazjin">tazjin</a>
|
||||
</li>
|
||||
</ul>
|
||||
</body>
|
||||
</html>
|
Loading…
Reference in a new issue