Move and rename tutorials

IntersectMBO · Nov 29, 2022 · 86eca02 · 86eca02
1 parent 74b1d82
commit 86eca02
Show file tree

Hide file tree

Showing 8 changed files with 37 additions and 72 deletions.
diff --git a/ouroboros-consensus-test/README.md b/ouroboros-consensus-test/README.md
@@ -11,17 +11,3 @@ This package contains:
 
 * `test-infra`: Tests of some of the infrastructure in `src`.
 
-* `test-examples` : Tutorial Introduction to the major consensus classes, 
-  as compilable Haskell code. Currently, `main` is trivial (future work), but
-  see these files:
-  ```
-  test-examples/Test/Tutorial.lhs
-  test-examples/Test/Tutorial2.lhs
-  ```
-
-  These files are written in a `markdown+lhs` style understood by `pandoc`.
-  To generate a documents from them file - it is as simple as:
-    ```
-    pandoc -s -f markdown+lhs test-examples/Test/Tutorial.lhs -o <output file>
-    ```
-  Which will work for many of the the output types supported by `pandoc`.
diff --git a/ouroboros-consensus-test/ouroboros-consensus-test.cabal b/ouroboros-consensus-test/ouroboros-consensus-test.cabal
@@ -312,36 +312,4 @@ test-suite test-infra
                        -Widentities
                        -Wredundant-constraints
                        -Wmissing-export-lists
-                       -fno-ignore-asserts
-
--- test-examples is just used to type-check tutorial code:
-
-test-suite test-examples
-  type:                exitcode-stdio-1.0
-  hs-source-dirs:      test-examples
-  main-is:             Main.hs
-  other-modules:       Test.Tutorial
-                     , Test.Tutorial2
-
-  build-depends:       base
-                     , containers
-                     , hashable
-                     , mtl
-                     , nothunks
-                     , serialise
-
-                     , ouroboros-consensus
-                     , ouroboros-consensus-test
-                     , ouroboros-network
-
-  default-language:    Haskell2010
-  ghc-options:         -Wall
-                       -Wcompat
-                       -Wincomplete-uni-patterns
-                       -Wincomplete-record-updates
-                       -Wpartial-fields
-                       -Widentities
-                       -Wredundant-constraints
-                       -Wmissing-export-lists
-                       -fno-ignore-asserts
-
+                       -fno-ignore-asserts
diff --git a/ouroboros-consensus/README.md b/ouroboros-consensus/README.md
@@ -12,6 +12,10 @@ This package contains:
 * `docs`: documentation, in particular, `docs/report` contains the technical
   report about the consensus and storage layer.
 
+* `src-docs`: a collection of tutorials that are helpful for understanding the
+  abstract structure of the consensus protocol. The structure of these is
+  explained in [docs/Tutorials.md](docs/Tutorials.md).
+
 The following packages use `ouroboros-consensus` to integrate specific ledgers:
 
 * `../ouroboros-consensus-byron`: integration with the Byron ledger, including

diff --git a/ouroboros-consensus/docs/Tutorials.md b/ouroboros-consensus/docs/Tutorials.md
@@ -0,0 +1,17 @@
+# Tutorials
+
+## Overview
+
+- [Ouroboros.Consensus.Tutorial.Simple](../src-docs/Ouroboros/Consensus/Tutorial/Simple.lhs):
+  Simple round-robin instantiation of the abstract Ouroboros consensus protocol.
+- [Ouroboros.Consensus.Tutorial.WithEpoch](../src-docs/Ouroboros/Consensus/Tutorial/WithEpoch.lhs):
+  Example in which the leader schedule depends on data from the chain.
+
+## Generating documents
+
+From the `ouroboros-consensus` directory, run for your choice of `<output file>`:
+
+    pandoc -s -f markdown+lhs src-docs/Ouroboros/Consensus/Tutorial/Simple.lhs -o <output file>
+
+
+
diff --git a/ouroboros-consensus/ouroboros-consensus.cabal b/ouroboros-consensus/ouroboros-consensus.cabal
@@ -359,8 +359,8 @@ library
 
 library src-docs
   hs-source-dirs:      src-docs
-  other-modules:       Test.Tutorial
-                     , Test.Tutorial2
+  other-modules:       Ouroboros.Consensus.Tutorial.Simple
+                     , Ouroboros.Consensus.Tutorial.WithEpoch
 
   build-depends:       base
                      , containers

diff --git a/ouroboros-consensus/src-docs/Main.hs b/ouroboros-consensus/src-docs/Main.hs
diff --git a/...oros-consensus/src-docs/Test/Tutorial.lhs → ...s/Ouroboros/Consensus/Tutorial/Simple.lhs b/...oros-consensus/src-docs/Test/Tutorial.lhs → ...s/Ouroboros/Consensus/Tutorial/Simple.lhs
@@ -32,7 +32,7 @@ This example uses several extensions:
 > {-# LANGUAGE MultiParamTypeClasses      #-}
 > {-# LANGUAGE StandaloneDeriving         #-}
 
-> module Test.Tutorial () where
+> module Ouroboros.Consensus.Tutorial.Simple () where
 
 First, some imports we'll need:
 

diff --git a/...ros-consensus/src-docs/Test/Tutorial2.lhs → ...uroboros/Consensus/Tutorial/WithEpoch.lhs b/...ros-consensus/src-docs/Test/Tutorial2.lhs → ...uroboros/Consensus/Tutorial/WithEpoch.lhs
@@ -3,20 +3,17 @@
 Introduction
 ============
 
-This tutorial builds on the example in `Tutorial.lhs` by specifying
-a block, ledger, and protocol for a blockchain that has a notion
-of epoch built into it - serving as an example of a case where
-the state of the ledger is used as part of the machinery
-of consensus.  It is highly recommended that the reader have
-read `Tutorial.lhs` before this if they are not already
-familiar with concepts such as `ConsensusProtocol` and
-`LedgerState`.
-
-Much like the previous example of `BlockC` this blockchain
-(with block type `BlockD`) models a single number resulting
-from a series of _increment_ and _decrement_ transactions in
-the block bodies.  However, the slots are now divided into
-**epochs** each of which has a fixed number of slots.
+This tutorial builds on the example in `Tutorial.lhs` by specifying a block,
+ledger, and protocol for a blockchain that has a notion of epoch built into it -
+serving as an example of a case where the state of the ledger is used as part of
+the machinery of consensus.  It is highly recommended that the reader have read
+`Tutorial.lhs` before this if they are not already familiar with concepts such
+as `ConsensusProtocol` and `LedgerState`.
+
+Much like the previous example of `BlockC` this blockchain (with block type
+`BlockD`) models a single number resulting from a series of _increment_ and
+_decrement_ transactions in the block bodies.  However, the slots are now
+divided into **epochs** each of which has a fixed number of slots.
 
 Further, the chain is set up such that there are 20 _nodes_
 labelled with a `NodeId` from 0 to 19 participating in the
@@ -57,7 +54,7 @@ As before, we require a few language extensions:
 > {-# LANGUAGE DeriveAnyClass #-}
 > {-# LANGUAGE StandaloneDeriving         #-}
 
-> module Test.Tutorial2() where
+> module Ouroboros.Consensus.Tutorial.WithEpoch () where
 
 And imports, of course: