Merge #2842

2842: Build the consensus technical report in CI r=dcoutts a=mrBliss



Co-authored-by: Thomas Winant <thomas@well-typed.com>

README.md

@@ -19,14 +19,14 @@
 We have two documents which describe various levels of the networking layer of
 the Cardano Shelley implementation:
 
-* [Introduction to the design of Data Diffusion and Networking of Cardano Shelley](https://hydra.iohk.io/job/Cardano/ouroboros-network/native.docs.x86_64-linux/latest/download/1)
+* [Introduction to the design of Data Diffusion and Networking of Cardano Shelley](https://hydra.iohk.io/job/Cardano/ouroboros-network/native.network-docs.x86_64-linux/latest/download/1)
 
   This document explains the technical requirements and key constraints for the networking
   layer of the _Cardano Shelley_ implementation of _Ouroboros Praos_.  This is
   a design document.
 
-* [The Shelley Networking Protocol](https://hydra.iohk.io/job/Cardano/ouroboros-network/native.docs.x86_64-linux/latest/download/2)
-  
+* [The Shelley Networking Protocol](https://hydra.iohk.io/job/Cardano/ouroboros-network/native.network-docs.x86_64-linux/latest/download/2)
+
   This document is a technical specification of the networking protocol.  It
   includes serialisation formats, necessary details of multiplexer and
   technical specifications of mini-protocols used by either _node-to-node_ and
@@ -87,6 +87,41 @@ nix-build -A haskellPackages.ouroboros-consensus.checks
 
 Consensus layer of the family Ouroboros blockchain protocols.
 
+## Ouroboros-Consensus Documentation
+
+The `ouroboros-consensus/docs` folder contains documentation about the consensus
+layer.
+
+* [The Cardano Consensus and Storage Layer](https://hydra.iohk.io/job/Cardano/ouroboros-network/native.consensus-docs.x86_64-linux/latest/download/1)
+
+  This technical report explains the design of the consensus and storage layer.
+
+## Formatting
+
+The consensus team uses `stylish-haskell` >= 0.11.0.0 to format its code. This
+is enforced by CI.
+
+Either enable editor integration or run the following command to manually
+format all of the consensus code (but not the network code):
+
+```bash
+stylish-haskell -i `git ls-files -- 'ouroboros-consensus*/*.hs' | grep -v Setup.hs`
+```
+
+Alternatively, call the script used by CI itself:
+https://github.com/input-output-hk/ouroboros-network/blob/master/scripts/buildkite/check-stylish.sh
+
+```bash
+./scripts/buildkite/check-stylish.sh
+```
+
+When using Nix, you can use the following command, which will build and use
+the right version of `stylish-haskell`.
+
+```bash
+nix-shell --run ./scripts/buildkite/check-stylish.sh
+```
+
 ## Tests
 
 ### Consensus test suite
@@ -145,29 +180,3 @@ or with `nix`
 ```
 nix-build -A haskellPackages.ouroboros-consensus-cardano-test.checks.test
 ```
-
-## Formatting
-
-The consensus team uses `stylish-haskell` >= 0.11.0.0 to format its code. This
-is enforced by CI.
-
-Either enable editor integration or run the following command to manually
-format all of the consensus code (but not the network code):
-
-```bash
-stylish-haskell -i `git ls-files -- 'ouroboros-consensus*/*.hs' | grep -v Setup.hs`
-```
-
-Alternatively, call the script used by CI itself:
-https://github.com/input-output-hk/ouroboros-network/blob/master/scripts/buildkite/check-stylish.sh
-
-```bash
-./scripts/buildkite/check-stylish.sh
-```
-
-When using Nix, you can use the following command, which will build and use
-the right version of `stylish-haskell`.
-
-```bash
-nix-shell --run ./scripts/buildkite/check-stylish.sh
-```

default.nix

@@ -27,7 +27,7 @@ let
   };
 
   self = {
-    inherit haskellPackages docs;
+    inherit haskellPackages network-docs consensus-docs;
 
     inherit (haskellPackages.ouroboros-network.identifier) version;
 

docs/shell.nix

@@ -1 +1 @@
-(import ../nix {}).docs
+(import ../nix {}).network-docs

nix/consensus-docs.nix

@@ -0,0 +1,41 @@
+{ pkgs }: with pkgs;
+let
+  src = haskell-nix.haskellLib.cleanGit {
+      name = "ouroboros-consensus-docs-src";
+      src = ../.;
+      subDir = "ouroboros-consensus/docs";
+  };
+in pkgs.runCommand "ouroboros-consensus-docs" {
+  nativeBuildInputs = [ bash ];
+  buildInputs = [ (texlive.combine {
+    inherit (texlive)
+      amsmath
+      cleveref
+      collection-fontsrecommended
+      enumitem
+      latexmk
+      scheme-small
+      todonotes
+    ;
+  })];
+} ''
+
+  for d in report; do
+    mkdir -p docs/$d
+    ln -s ${src}/$d/* docs/$d/
+  done
+
+  mkdir -p $out
+
+  (
+    cd docs/report
+    latexmk -pdf -pdflatex="pdflatex -interaction=nonstopmode" report.tex
+    cp -a *.pdf $out/
+  )
+
+  mkdir -p $out/nix-support
+
+  for pdf in $out/*.pdf; do
+    echo "file binary-dist $pdf" >> $out/nix-support/hydra-build-products
+  done
+''

nix/pkgs.nix

@@ -10,5 +10,6 @@ pkgs: _: with pkgs; {
       ;
   };
 
-  docs = callPackages ./docs.nix {};
+  network-docs = callPackage ./network-docs.nix {};
+  consensus-docs = callPackage ./consensus-docs.nix {};
 }

ouroboros-consensus/README.md

@@ -2,10 +2,13 @@
 
 This package contains:
 
-* `src`: The implementation of the Ouroboros consensus protocols and required
+* `src`: the implementation of the Ouroboros consensus protocols and required
   components, e.g., the storage layer, mempool, protocol clients and servers,
   etc. This library abstract over the ledger.
 
+* `docs`: documentation, in particular, `docs/report` contains the technical
+  report about the consensus and storage layer.
+
 Related packages:
 
 * `../ouroboros-consensus-byron`: integration with the Byron ledger, including

release.nix

@@ -63,7 +63,7 @@ let
   nonDefaultBuildSystems = tail supportedSystems;
 
   # Paths or prefixes of paths of derivations to build only on the default system (ie. linux on hydra):
-  onlyBuildOnDefaultSystem = [ ["docs" ] ];
+  onlyBuildOnDefaultSystem = [ ["network-docs" "consensus-docs"] ];
   # Paths or prefix of paths for which cross-builds (mingwW64, musl64) are disabled:
   noCrossBuild = let
     # checks are available from two path: