Best practice setting up docs environment for an unregistered package

General Usage
,
#1

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
./make.jl

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:

[[AnotherParser]]
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
Stacktrace:
  [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.

Thanks.

#2

Did you using NahaJuliaLib?

#3

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.

#4

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"
 
 [[AnotherParser]]
-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"
 
 [[NahaJuliaLib]]
-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 = "https://github.com/MarkNahabedian/NahaJuliaLib.jl"
 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"
 
+[[PrettyPrint]]
+git-tree-sha1 = "632eb4abab3449ab30c5e1afaa874f0b98b586e4"
+uuid = "8162dcfd-2161-5ef2-ae6c-7681170c5f98"
+version = "0.2.0"
+
 [[Printf]]
 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:
-push!(LOAD_PATH,"../src/")
-
 #=
 # One time setup of deployment secret
 DocumenterTools.genkeys(; user="MarkNahabedian",
1 Like
#5

Thanks for your efforts looking in to this.

In the AnotherParser/docs workspace I did

Pkg.develop(path="..")

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

[[NahaJuliaLib]]
deps = ["DataStructures", "HTTP", "InteractiveUtils", "Logging", "MacroTools", "Pkg", "URIs", "VectorLogging"]
git-tree-sha1 = "7839c7fd8dd7f4be2c538d0b31f62b9fee4e7748"
repo-rev = "master"
repo-url = "https://github.com/MarkNahabedian/NahaJuliaLib.jl"
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.

#6

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

#7

Thanks. Pushed.

#8

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