Question on correct set-up of docs/project.tom - adding documented package

[moustachio-belvedere]

As far as I understand, the docs/project.toml file should have all packages required for the building of the documentation. This includes Documenter.jl, and almost always the 'parent' package, i.e. in the the directory above ...

If you think it might be helpful, I would be happy to expand a bit the documentation section on that:

https://juliadocs.github.io/Documenter.jl/stable/man/hosting/#docs/Project.toml

As I noticed there are questions on this e.g.:

#1164

Before I do, however, I am wondering what is the best practice for adding the 'parent' package (i.e. the package being documented). I can think of a number of ways:

1. Adding by directory path ..
2. For unregistered package, add(PackageUrl)
3. For a registered package, just add(PackageName.jl)
4. dev in the package, by url or directory path

But I'm not sure which one will ensure that stable docs are built with the correct stable tagged version, and dev docs are built with the relevant commit. For example, I guess option 3 would mean it that only the latest stable version of a package is brought in, which wouldn't be good for dev docs if there were new functions being documented.

I tried to recreate something like:

https://github.com/fredrikekre/Literate.jl/blob/master/docs/Manifest.toml#L191

and found that a comparable Manifest.toml section was achieved using Pkg.develop(path = '..'), when the docs/project.toml environment was active.

I also found this lengthy and helpful discussion on Julia Discourse:

https://discourse.julialang.org/t/psa-use-a-project-for-building-your-docs/14974/24

but I'm not sure how up-to-date that advice is. Perhaps the latest best practice is summarized somewhere already and I just missed it.

Many thanks for your work on the package.

[fredrikekre]

Always use Pkg.develop. Either once and commit the manifest (like the Literate example) or on every build as recommended in the manual.

[mortenpi]

The hints in that discourse thread are still valid I believe. I think that expanding the "docs/Project.toml" section with this information would be great though, including perhaps a discussion of committing the Manifest.toml vs not.

[odow]

Closing in favor of #1413