feat(tvix/docs): switch to mdbook
Some of the docs are still outdated (like architecture and drv path inconsistencies). Change-Id: I7a6afceb008ef4cd19a764dd6c637b39fa842a2e Reviewed-on: https://cl.tvl.fyi/c/depot/+/11072 Autosubmit: flokli <flokli@flokli.de> Tested-by: BuildkiteCI Reviewed-by: edef <edef@edef.eu>
This commit is contained in:
Florian Klink
clbot
parent
6bdaebcb55
commit
65a810fc0b
14 changed files with 45 additions and 116 deletions
|
|
@ -13,13 +13,6 @@
|
|||
forceSSL = true;
|
||||
|
||||
extraConfig = ''
|
||||
# Serve the rendered Tvix component SVG.
|
||||
#
|
||||
# TODO(tazjin): Implement a way of serving this dynamically
|
||||
location = /about/tvix/docs/component-flow.svg {
|
||||
alias ${depot.tvix.docs.svg}/component-flow.svg;
|
||||
}
|
||||
|
||||
location = /go-get/tvix/build-go {
|
||||
alias ${pkgs.writeText "go-import-metadata.html" ''<html><meta name="go-import" content="code.tvl.fyi/tvix/build-go git https://code.tvl.fyi/depot.git:/tvix/build-go.git"></html>''};
|
||||
}
|
||||
|
|
|
|||
4
tvix/docs/.gitignore
vendored
4
tvix/docs/.gitignore
vendored
|
|
@ -1,2 +1,2 @@
|
|||
*.svg
|
||||
*.html
|
||||
book
|
||||
.mdbook-plantuml-cache/
|
||||
|
|
|
|||
|
|
@ -1,12 +0,0 @@
|
|||
all: build
|
||||
|
||||
puml:
|
||||
plantuml *.puml -tsvg
|
||||
|
||||
html:
|
||||
pandoc *.md -f markdown --self-contained -t html -s -o tvix.html --csl=${CSL}
|
||||
|
||||
build: puml html
|
||||
|
||||
clean:
|
||||
rm -f *.tex *.pdf *.png *.svg
|
||||
11
tvix/docs/book.toml
Normal file
11
tvix/docs/book.toml
Normal file
|
|
@ -0,0 +1,11 @@
|
|||
[book]
|
||||
authors = ["The Tvix Authors"]
|
||||
language = "en"
|
||||
multilingual = false
|
||||
src = "src"
|
||||
title = "Tvix Docs"
|
||||
|
||||
[preprocessor.plantuml]
|
||||
# override the /usr/bin/plantuml default
|
||||
plantuml-cmd = "plantuml"
|
||||
use-data-uris = true
|
||||
|
|
@ -1,47 +1,23 @@
|
|||
{ pkgs, lib, ... }:
|
||||
|
||||
let
|
||||
|
||||
tl = pkgs.texlive.combine {
|
||||
inherit (pkgs.texlive) scheme-medium wrapfig ulem capt-of
|
||||
titlesec preprint enumitem paralist ctex environ svg
|
||||
beamer trimspaces zhnumber changepage framed pdfpages
|
||||
fvextra minted upquote ifplatform xstring;
|
||||
};
|
||||
|
||||
csl = pkgs.fetchurl {
|
||||
name = "numeric.csl";
|
||||
url = "https://gist.githubusercontent.com/bwiernik/8c6f39cf51ceb3a03107/raw/1d75c2d62113ffbba6ed03a47ad99bde86934f2b/APA%2520Numeric";
|
||||
sha256 = "1yfhhnhbzvhrv93baz98frmgsx5y442nzhb0l956l4j35fb0cc3h";
|
||||
};
|
||||
|
||||
in
|
||||
pkgs.stdenv.mkDerivation {
|
||||
pname = "tvix-doc";
|
||||
pname = "tvix-docs";
|
||||
version = "0.1";
|
||||
|
||||
outputs = [ "out" "svg" ];
|
||||
outputs = [ "out" ];
|
||||
|
||||
src = lib.cleanSource ./.;
|
||||
|
||||
CSL = csl;
|
||||
|
||||
nativeBuildInputs = [
|
||||
pkgs.pandoc
|
||||
pkgs.mdbook
|
||||
pkgs.mdbook-plantuml
|
||||
pkgs.plantuml
|
||||
tl
|
||||
];
|
||||
|
||||
installPhase = ''
|
||||
runHook preInstall
|
||||
|
||||
mkdir -p $out
|
||||
cp -v *.html $out/
|
||||
|
||||
mkdir -p $svg
|
||||
cp -v *.svg $svg/
|
||||
|
||||
runHook postSubmit
|
||||
# plantuml wants to create ./.mdbook-plantuml-cache, which fails as $src is r/o.
|
||||
# copy all sources elsewhere to workaround.
|
||||
buildCommand = ''
|
||||
cp -R $src/. .
|
||||
mdbook build -d $out
|
||||
'';
|
||||
|
||||
}
|
||||
|
|
|
|||
10
tvix/docs/src/SUMMARY.md
Normal file
10
tvix/docs/src/SUMMARY.md
Normal file
|
|
@ -0,0 +1,10 @@
|
|||
# Summary
|
||||
|
||||
# Tvix
|
||||
- [Architecture & data flow](./architecture.md)
|
||||
- [.drvPath inconsistencies](./differences-drv-paths.md)
|
||||
|
||||
# Nix
|
||||
- [Specification of the Nix Language](./language-spec.md)
|
||||
- [Nix language version history](./lang-version.md)
|
||||
- [Value Pointer Equality](./value-pointer-equality.md)
|
||||
|
|
@ -1,21 +1,6 @@
|
|||
---
|
||||
title: "Tvix - Architecture & data flow"
|
||||
numbersections: true
|
||||
author:
|
||||
- adisbladis
|
||||
- flokli
|
||||
- tazjin
|
||||
email:
|
||||
- adis@blad.is
|
||||
- mail@tazj.in
|
||||
lang: en-GB
|
||||
classoption:
|
||||
- twocolumn
|
||||
header-includes:
|
||||
- \usepackage{caption, graphicx, tikz, aeguill, pdflscape}
|
||||
---
|
||||
# Tvix - Architecture & data flow
|
||||
|
||||
# Background
|
||||
## Background
|
||||
|
||||
We intend for Tvix tooling to be more decoupled than the existing,
|
||||
monolithic Nix implementation. In practice, we expect to gain several
|
||||
|
|
@ -32,9 +17,9 @@ benefits from this, such as:
|
|||
Communication between different components of the system will use
|
||||
gRPC. The rest of this document outlines the components.
|
||||
|
||||
# Components
|
||||
## Components
|
||||
|
||||
## Coordinator
|
||||
### Coordinator
|
||||
|
||||
*Purpose:* The coordinator (in the simplest case, the Tvix CLI tool)
|
||||
oversees the flow of a build process and delegates tasks to the right
|
||||
|
|
@ -52,7 +37,7 @@ coordinator on top of a state-machine model that would make it
|
|||
possible to reuse the FSM logic without tying it to any particular
|
||||
kind of application.
|
||||
|
||||
## Evaluator
|
||||
### Evaluator
|
||||
|
||||
*Purpose:* Eval takes care of evaluating Nix code. In a typical build
|
||||
flow it would be responsible for producing derivations. It can also be
|
||||
|
|
@ -72,7 +57,7 @@ accessible by the evaluator (this could be a FUSE filesystem, or the "real"
|
|||
We might be okay with running the evaluator with filesystem access for now and
|
||||
can extend the interface if the need arises.
|
||||
|
||||
## Builder
|
||||
### Builder
|
||||
|
||||
*Purpose:* A builder receives derivations from the coordinator and
|
||||
builds them.
|
||||
|
|
@ -106,7 +91,7 @@ derivations to that format). [^1]
|
|||
To build, the builder needs to be able to mount all build inputs into the build
|
||||
environment. For this, it needs the store to expose a filesystem interface.
|
||||
|
||||
## Store
|
||||
### Store
|
||||
|
||||
*Purpose:* Store takes care of storing build results. It provides a
|
||||
unified interface to get store paths and upload new ones, as well as querying
|
||||
|
|
@ -151,9 +136,11 @@ interface, exposing a lazily-substituting /nix/store mountpoint. Using this in
|
|||
remote build context dramatically reduces the amount of data transferred to a
|
||||
builder, as only the files really accessed during the build are substituted.
|
||||
|
||||
# Figures
|
||||
## Figures
|
||||
|
||||
|
||||
```plantuml,format=svg
|
||||
{{#include figures/component-flow.puml}}
|
||||
```
|
||||
|
||||
[^1]: There have already been some discussions in the Nix community, to switch
|
||||
to REAPI:
|
||||
|
|
@ -1,15 +1,4 @@
|
|||
---
|
||||
title: ".drvPath inconsistencies"
|
||||
author:
|
||||
- tazjin
|
||||
- flokli
|
||||
email:
|
||||
- tazjin@tvl.su
|
||||
- flokli@flokli.de
|
||||
lang: en-GB
|
||||
---
|
||||
|
||||
# Why .drvPath differs between Nix and Tvix
|
||||
# .drvPath inconsistencies / Why .drvPath differs between Nix and Tvix
|
||||
|
||||
Nix and Tvix currently use a different approach when it comes to tracking input
|
||||
references, in order to build the right dependencies in advance.
|
||||
|
|
@ -1,15 +1,4 @@
|
|||
---
|
||||
title: "Specification of the Nix language"
|
||||
numbersections: true
|
||||
author:
|
||||
- tazjin
|
||||
email:
|
||||
- tazjin@tvl.su
|
||||
lang: en-GB
|
||||
---
|
||||
|
||||
The Nix Language
|
||||
================
|
||||
# Specification of the Nix Language
|
||||
|
||||
WARNING: This document is a work in progress. Please keep an eye on
|
||||
[`topic:nix-spec`](https://cl.tvl.fyi/q/topic:nix-spec) for ongoing
|
||||
|
|
@ -4,7 +4,6 @@ let
|
|||
|
||||
scripts = [
|
||||
./hello.nix
|
||||
./derivation-svg.nix
|
||||
(substituteAll {
|
||||
src = ./blog.nix;
|
||||
# by making this a plain string this
|
||||
|
|
|
|||
|
|
@ -1,13 +0,0 @@
|
|||
# Warning: this is *very* slow on the first request
|
||||
{ depot, ... }:
|
||||
|
||||
let
|
||||
inherit (depot.web.bubblegum)
|
||||
respond
|
||||
;
|
||||
in
|
||||
respond "OK"
|
||||
{
|
||||
Content-type = "image/svg+xml";
|
||||
}
|
||||
(builtins.readFile "${depot.tvix.docs.svg}/component-flow.svg")
|
||||
Loading…
Reference in a new issue