Document(er) mystery

General Usage
1

I use project - specific files in docs, Project.toml and Manifest.toml.
I wish to run

  docs:
    name: Documentation
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: julia-actions/setup-julia@v1
        with:
          version: '1'
      - run: julia --project=docs docs/make.jl
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}

to generate the documentation.

The command julia --project=docs docs/make.jl works fine when I run it with local Julia (1.6.2 and up).
However, when run as part of CI I get this error

image
image1050Ă—331 15.2 KB

I don’t know what to make of it, since the docs/Manifest.toml file
clearly includes a reference to Documenter!? Locally I do get
image

2

It means Documenter is not downloaded. Run Pkg.instantiate() first (like the error message says).

3

So, --project= actually doesn’t do any of that (activate, instantiate), I am guessing?

Edit: Verified. I wonder what the use of --project then might be?

Edit 2: Fixed the above issue with
- run: julia -e "using Pkg; Pkg.activate(\"docs\"); Pkg.instantiate(); include(\"docs/make.jl\")"

4

The --project flag just tells Julia which environment to use (just like activate does from within a Julia session). E.g. if you start Julia with julia --project=docs and press ] you will see you’re in the docs environment:

(docs) pkg>

It doesn’t do anything more than that though, so you still need to call instantiate yourself (but it tells Julia which environment to instantiate!).

5

Right. But if you have to do instantiate manually afterwards, why not make --project do both activate and instantiate?

6

Well if you’ve already done it once you don’t need to do it again. It’s just the same as activate, that doesn’t instantiate either.

I think the deeper reason though is security: just opening a Julia session shouldn’t run untrusted code. But if —project instantiated, that would install packages (which could be unregistered if there’s a Manifest), which would call their build step, which can execute code.

7

It’s easier to see why this a problem if you consider a Julia session could be started by automatic tools (like the language server) or a script etc.

8

Ref https://github.com/JuliaLang/Pkg.jl/issues/1415