diff --git a/default.nix b/default.nix index a09d49af27f..4d6d4950afa 100644 --- a/default.nix +++ b/default.nix @@ -163,6 +163,7 @@ let docs = { plutus-tutorial = pkgs.callPackage ./plutus-tutorial/doc {}; + plutus-book = pkgs.callPackage ./plutus-book {}; plutus-core-spec = pkgs.callPackage ./plutus-core-spec { inherit latex; }; multi-currency = pkgs.callPackage ./docs/multi-currency { inherit latex; }; diff --git a/plutus-book/.gitignore b/plutus-book/.gitignore new file mode 100644 index 00000000000..7cb551067fd --- /dev/null +++ b/plutus-book/.gitignore @@ -0,0 +1,3 @@ +*.html +asciidoctor.css +pygments-tango.css diff --git a/plutus-book/01-intro.adoc b/plutus-book/01-intro.adoc new file mode 100644 index 00000000000..0cdb54f59b8 --- /dev/null +++ b/plutus-book/01-intro.adoc @@ -0,0 +1,3 @@ += Introduction + +I'm an introduction, put text here. diff --git a/plutus-book/README.md b/plutus-book/README.md new file mode 100644 index 00000000000..ffd99d81c4c --- /dev/null +++ b/plutus-book/README.md @@ -0,0 +1,42 @@ +# The Plutus Book + +This is the Plutus Book. It is written using [asciidoctor](https://asciidoctor.org/), +make sure to consult its excellent documentation. + +## Building the book + +### Using `nix` + +The book can be built in all its formats using `nix` (which is +what the CI uses). + +- Run `nix build -f default.nix docs.plutus-book` in the root of + the repository. + - Make sure you've followed [the main README](../README.md#binary-caches). +- Look inside the `result` directory. + +### Using `asciidoctor` directly + +This will just get you the html output, which is probably what +you want during development. + +- Ensure you have the following installed: + - `asciidoctor` + - `python` +- Run `asciidoctor plutus.adoc`. +- Open the resulting `plutus.html` in a browser. + +## Book structure + +The entry point to the book is `plutus.adoc`. This defines the main document +attributes and includes all the chapters in sequence. + +Chapters should be written in separate files (beginning the files with their +sequence number is not essential but helpful), and included into `plutus.adoc`. + +## Miscellaneous + +Unfortunately due to a quirk of how `asciidoctor` parses double colons, it's +tricky to write Haskell type signatures in the main text without them +rendering wrong. To get around that, use an attribute reference `{2c}` +instead of the colons. diff --git a/plutus-book/default.nix b/plutus-book/default.nix new file mode 100644 index 00000000000..b06d65cf130 --- /dev/null +++ b/plutus-book/default.nix @@ -0,0 +1,27 @@ +{ stdenv, lib, asciidoctor, python2, pandoc }: + +stdenv.mkDerivation { + name = "plutus-book"; + src = lib.sourceFilesBySuffices ./. [ ".adoc" ".png" ".PNG" ".gif" ".ico" ".css" ]; + buildInputs = [ asciidoctor python2 pandoc ]; + buildPhase = '' + asciidoctor plutus.adoc -b html5 -o plutus.html + + asciidoctor-pdf plutus.adoc -o plutus.pdf + + # TODO: run epubcheck on the epub (it's not in our nixpkgs yet) + asciidoctor plutus.adoc -b docbook5 -o plutus.docbook + pandoc -f docbook -t epub plutus.docbook -o plutus.epub + ''; + installPhase = '' + install -D -t $out/html plutus.html + cp -aR images $out/html + cp -aR css $out/html + + install -D -t $out/pdf plutus.pdf + + install -D -t $out/epub plutus.epub + + install -D -t $out/mobi plutus.mobi + ''; +} diff --git a/plutus-book/images/favicon.ico b/plutus-book/images/favicon.ico new file mode 100644 index 00000000000..e8dfec8c049 Binary files /dev/null and b/plutus-book/images/favicon.ico differ diff --git a/plutus-book/plutus.adoc b/plutus-book/plutus.adoc new file mode 100644 index 00000000000..d184b2b23e0 --- /dev/null +++ b/plutus-book/plutus.adoc @@ -0,0 +1,28 @@ += Plutus +:authors: Some IOHK folk +:email: plutus@iohk.io +:orgname: IOHK +:doctype: book +:toc: left +:sectnums: +:source-highlighter: pygments +// Considerations: +// - Shouldn't mess up alignment (weirdly some of them do, including the default) +// - Shouldn't have a dark background, otherwise callouts don't show up (otherwise I'd pick monokai) +// - Should have a non-white background, to distinguish code blocks +:pygments-style: tango +:imagesdir: images +// uses fontawesome, seems okay for now, could use real icons later +:icons: font +:favicon: {imagesdir}/favicon.ico +:stylesdir: css +:linkcss: +// prevents setting the last-updated-label etc. +:reproducible: + +// unfortunately, asciidoctor likes to parse these as definition lists :( +// https://github.com/asciidoctor/asciidoctor/issues/1066 +:2c: :: + +// Include each chapter here +include::01-intro.adoc[leveloffset=+ 1]