Docs-specific dependencies - should I use a separate environment?

New to Julia
,
1

I’ve been working on my first package for counterfactual explanations and algorithmic recourse in Julia. To create tutorials as part of the documentation I have been using packages that are not dependencies of the package itself. For example, I show here how to use my package to create counterfactual explanations for Flux.jl models, but Flux is not a dependency of my package.

Now here’s what I’m hoping to get some advice on:

  • If I add these packages to my package environment, they will by default be added as deps to the Project.toml, if I’m not mistaken.
  • To avoid this I have set up a separate environment in docs/src/tutorials which uses the dev version of my repo as a dependency along with any other packages (like Flux) I need for the tutorials.

This approach works, but is at times a bit fiddly. When working on the package itself I use its own environment. Whenever I work on tutorials in docs I need to remember to

  1. Push any potential changes in my dev branch to remote.
  2. Update the environment in docs/src/tutorials to incorporate those changes like so:
(@v1.6) pkg> activate .
  Activating environment at `AlgorithmicRecourse.jl/docs/src/tutorials/Project.toml`

(tutorials) pkg> update AlgorithmicRecourse

I imagine there’s a better way to go about this?

Appreciate this is a bit of a convoluted topic so hopefully I’ve been clear enough. For reference: I’m working in VS code and using Jupyter+nbconvert to create the tutorials.

Any thoughts/comments would be much appreciated!

2

Should I use a separate environment?

Yes.

No, you can “install” your package into the doc environment by using a relative path. It will look something like this: fredrikekre/Literate.jl/docs/Manifest.toml#L389.

3

Thanks for the quick response, Fredrik. I’m guessing that by ‘install’ you mean adding a the local folder to the environment as suggested here? If so, I had actually previously done it that way since it avoids having to push to remote. But if for some reason the local folder structure changes, then this causes trouble.

Edit: Also I saw your Literate.jl package which seems to be addressing these kinds of problems, so nice to see for future reference.

4

Yes, pkg> dev relative/path/to/package.

Sure, but how often do you need to change the structure?

5

Yup, fair point! Thanks again, much appreciate the quick response.