Best practice setting up docs environment for an unregistered package

I’m trying to use Documenter.jl to generate documentation for an unregistered package.

What is the best practice for setting up the docs directory environment for this?

The AnotherParser project (GitHub - MarkNahabedian/AnotherParser.jl) I’m working on is not yet registered.

That project builds fine, but its documentation doesn’t.

The documentation for AnotherParser only uses two packages:

$ find . -name *.jl -exec grep using '{}' ';' -print
using Documenter
using AnotherParser

Since it’s meant to document the “immediate” version of AnotherParser, rather than the tip of the main branch, the docs/Manifest.toml file refers to AnotherParser using a relative path:

deps = ["DataStructures", "Logging", "MacroTools", "NahaJuliaLib", "VectorLogging"]
git-tree-sha1 = "06c1877e1b8fd2cf35a3878cb76a6ef9c01fde29"
repo-rev = "master"
repo-url = ".."
uuid = "2ebba909-c633-4b8c-b8fe-948aaf993ef9"
version = "0.1.0-dev"

Trying to build the documentation, or trying to use AnotherParser with the AnotherParser/docs environment activated gets the error

ERROR: LoadError: UndefVarError: @trace not defined
  [1] top-level scope
    @ :0
  [2] #macroexpand#51
    @ .\expr.jl:115 [inlined]
  [3] macroexpand
    @ .\expr.jl:114 [inlined]
  [4] docm(source::LineNumberNode, mod::Module, meta::Any, ex::Any, define::Bool) (repeats 2 times)
    @ Base.Docs .\docs\Docs.jl:537
  [5] var"@doc"(::LineNumberNode, ::Module, ::String, ::Vararg{Any})
    @ Core .\boot.jl:517
  [6] include(mod::Module, _path::String)
    @ Base .\Base.jl:418
  [7] include(x::String)
    @ AnotherParser C:\Users\Mark Nahabedian\.julia\packages\AnotherParser\TAM93\src\AnotherParser.jl:1

The @trace macro is defined in the unregistered package NahaJuliaLib, which is used by AnotherParser and is is identified in AnotherParser/Manifest.toml.


Did you using NahaJuliaLib?

Yes. My package, AnotherParser, builds and runs.

The problem is with it’s documentation.

docs has its own Project.toml which refers to AnitherParser and Documenter.

I don’t think that its docs environment should need to reference all of the packages that AnotherParser uses, just what the documentation uses.

I checked out the repo, you need to use dev with a path, not add (add checks out a snapshot of the latest commit, dev tracks the path).

Here is a diff which makes it work (although, don’t apply it, use Pkg to generate it):

diff --git a/docs/Manifest.toml b/docs/Manifest.toml
index aba6171..a643144 100644
--- a/docs/Manifest.toml
+++ b/docs/Manifest.toml
@@ -6,10 +6,8 @@ uuid = "a4c015fc-c6ff-483c-b24f-f7ea428134e9"
 version = "0.0.1"
-deps = ["DataStructures", "Logging", "MacroTools", "NahaJuliaLib", "VectorLogging"]
-git-tree-sha1 = "bc5b1927bd8203daaabf9ff38fc88c0bfc31e702"
-repo-rev = "master"
-repo-url = ".."
+deps = ["DataStructures", "Logging", "MacroTools", "NahaJuliaLib", "PrettyPrint", "VectorLogging"]
+path = ".."
 uuid = "2ebba909-c633-4b8c-b8fe-948aaf993ef9"
 version = "0.1.0-dev"
@@ -149,8 +147,10 @@ uuid = "a63ad114-7e13-5084-954f-fe012c677804"
 uuid = "14a3606d-f60d-562e-9121-12d972cd8159"
-deps = ["HTTP", "InteractiveUtils", "Pkg", "URIs"]
-git-tree-sha1 = "ac14a7941c24bbc97a551fd1c60a13e2c8567603"
+deps = ["DataStructures", "HTTP", "InteractiveUtils", "Logging", "MacroTools", "Pkg", "URIs", "VectorLogging"]
+git-tree-sha1 = "7839c7fd8dd7f4be2c538d0b31f62b9fee4e7748"
+repo-rev = "master"
+repo-url = ""
 uuid = "9569be99-1faa-4e84-9751-444b87a7f9a0"
 version = "0.1.0"
@@ -176,6 +176,11 @@ version = "2.2.4"
 deps = ["Artifacts", "Dates", "Downloads", "LibGit2", "Libdl", "Logging", "Markdown", "Printf", "REPL", "Random", "SHA", "Serialization", "TOML", "Tar", "UUIDs", "p7zip_jll"]
 uuid = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"
+git-tree-sha1 = "632eb4abab3449ab30c5e1afaa874f0b98b586e4"
+uuid = "8162dcfd-2161-5ef2-ae6c-7681170c5f98"
+version = "0.2.0"
 deps = ["Unicode"]
 uuid = "de0858da-6303-5e67-8744-51eddeeeb8d7"
diff --git a/docs/make.jl b/docs/make.jl
index 427d90d..0a67baa 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -9,9 +9,6 @@ for somewhat rambling instructions about how to set up a
 documentation generation workflow.
-# Temporary hack:
 # One time setup of deployment secret
 DocumenterTools.genkeys(; user="MarkNahabedian",

1 Like

Thanks for your efforts looking in to this.

In the AnotherParser/docs workspace I did


I think that’s what you meant.

When I diff the resulting docs/Manifest.toml and compare the [[AnotherParser]] section of that diff with your diff above, they’re the same.

I still get this error though:

julia make.jl
  Activating project at `c:\Users\Mark Nahabedian\.julia\dev\AnotherParser\docs`
ERROR: LoadError: UndefVarError: @trace not defined

@trace is exported from the unregistered package NahaJuliaLib, which appeats in AnotherParser/Manifest.toml as

deps = ["DataStructures", "HTTP", "InteractiveUtils", "Logging", "MacroTools", "Pkg", "URIs", "VectorLogging"]
git-tree-sha1 = "7839c7fd8dd7f4be2c538d0b31f62b9fee4e7748"
repo-rev = "master"
repo-url = ""
uuid = "9569be99-1faa-4e84-9751-444b87a7f9a0"
version = "0.1.0"

AnotherParser loads and tests successfully.

If I Pkg.update() in docs, I get this warning

┌ Warning: The active manifest file at `C:\Users\Mark Nahabedian\.julia\dev\AnotherParser\docs\Manifest.toml` has an old format that is being maintained.

but I don’t know how to address it. I’d have expected Pkg.update to make whatever updates are necessary to Manifest.toml.

Can you push your updates to Github? I didn’t get any errors and could build the docs with my diff at least.

Thanks. Pushed.

It’s interesting that the doc build on GitHub fails in a different way than locally.