7

I've been following this guide to build Plutus documentation locally. The key line is -

[~/plutus] nix-build -A plutus-playground.haddock

This works fine, but I'm following the Pioneer Program and this requires checking out specific commits each week in order to follow the lesson. When re-building the documentation, the resulting docs doesn't seem to reflect the tag that I've checked out.

My steps are -

  • git pull origin master to get the latest commits
  • git checkout of the tag specified for the week
  • rebuild the documentation using nix-build -A plutus-playground.haddock

I'm guessing that there is some caching going on that I'm not cleaning up but, if I compare the source files in the plutus dir they don't match the source that is linked to in the documentation.

Should mention that I have a superficial understanding of both nix and haddock.
Any guidance appreciated :)

Improve this question
4
  • 1
    I've not tried building the documentation. But here is what I use
    – Aoaddeola
    Commented Aug 1, 2021 at 21:38
  • Thanks @Aoaddeola . That works for the latest version, but the API changes quite a lot from week to week. It makes it hard to follow the lectures when the docs that Lars is referencing are different from the latest. The lectures themselves are a lot to take in, so easier when you can follow what he's pointing out 1:1.
    – Phil Boltt
    Commented Aug 2, 2021 at 2:20
  • You can say that again, Phil. I also find myself having to figure out the latest signature of functions through searching Github using Keywords... It sure would be nice to know how to build the documentation.
    – Aoaddeola
    Commented Aug 2, 2021 at 7:15
  • There is also an option to build the documentation using docker, I tried it and it failed when starting it using docker-compose. Have you tried this option? The commands you need are docker-compose build --no-cache followed by docker-compose up in the /docker directory.
    – eddex ♦
    Commented Aug 3, 2021 at 11:27

3 Answers 3

Reset to default
1

I have been building the documentation with

[~/plutus] nix-build -A plutus-playground.haddock

following the Plutus Community guide and

nix build -f default.nix docs.site

from the Plutus repo and they both work as expected, generating the documentation for the current checkout.

The most probable cause for the issue is that git may not have updated as expected, i.e. throwing an error due to changed files in the local repo. That happened to me a few times when I was switching between the pioneer lecture weeks.

And in my opinion it is worth to set up the webserver as per the Plutus Community instructions, it makes the up to date documentation a great resource!

Improve this answer
3

How to build local Plutus document:

  1. cd plutus
  2. nix-shell
  3. nix build -f default.nix docs.site
  4. cd result
  5. python3 -m http.server 8081

Try open http://localhost:8081/haddock/plutus-ledger-api/html/Plutus-V1-Ledger-Value.html#g:1

Improve this answer
1
  • this worked for me
    – D S
    Commented Jul 28, 2022 at 23:18
0

I keep finding myself coming back here as i hate remembering commands.

So I somewhat automated the process. On Ubuntu (Unless you disable your Firefox browser) the following script will build and launch your plutus docs.

To use it copy the script to your plutus folder and activate your environment with nix-shell.

Then run the bash script from the terminal using the command:

sh Make_Docs.sh

You can get the Make_Docs file from my plutus automation repo.

Improve this answer

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.