I only changed the content of the Example.jl under src folder; just removed the hello function.
module Example
export domath
"""
domath(x::Number)
Return `x + 5`.
"""
domath(x::Number) = x + 5
end
When I run
julia make.jl
inside docs folder using cmd on windows It showhow still builds index.html with the initial content. Still showing me hello function in documentation even do I removed it from Example.jl.
I am suspecting though one thing; after downloading Example.jl from GitHub and making the first: julia make.jl
It threw an error and asked me to make Pkg.add("Example"). I suspect that it’s somehow creating the document from the library itself, not from the folder.
But I’m making a pure guess.
For example, I made a copy of Example and saved it as xyz. So the new package is called xyz. Made the relevant changes in the docs folder.
The content of Example.jl:
module Example
export domath
"""
domath(x::Number)
Return `x + 5`.
"""
domath(x::Number) = x + 5
end
# xyz
Example Julia package repo.
@autodocs
Modules = [xyz]
# 3 left quotation marks before and after @autodocs. it is not displaying correctly here if I add them.
After running:
julia make.jl
The output in the terminal is:
It’s asking me to install the package first. I am sure I’m making a simple mistake somewhere, but I could not figure it out.
The documentation of Documenter.jl needs to be definitely improved. Nowadays, Julia, R, and Python languages are used predominantly by non-computer scientists, and it is very difficult to figure out the problem.
While messing with the LOAD_PATH works, the standard approach here is to make sure you package is correctly added as a dev dependency to docs/Project.toml. That’s why you generally have something like Pkg.develop(PackageSpec(path=pwd())) in your docs CI configuration, e.g.:
Could you please also advise how the content of make.jl looks like?
If I do it the way you suggest, it only impacts the folders in GitHub. How can I document the package I’m developing on my local machine?
I pushed the folders from my local to GitHub, but I added a new dependency; therefore, It threw the “Documentation workflow run failed for main branch” error:
ERROR: LoadError: ArgumentError: Package PortfolioAnalytics does not have NamedArrays in its dependencies:
- You may have a partially installed environment. Try `Pkg.instantiate()`
to ensure all packages in the environment are installed.
- Or, if you have PortfolioAnalytics checked out for development and have
added NamedArrays as a dependency but haven't updated your primary
environment's manifest file, try `Pkg.resolve()`.
- Otherwise you may need to report an issue with PortfolioAnalytics
Basically, you do the exact same thing as on CI. Nothing goes into make.jl. Usually, when I need to build the docs for a newly cloned package, I run the following (assuming my working directory is in the root of the package):
$ julia --project=docs/
pkg> dev .
julia> include("docs/make.jl")
Note that you only need to do this once, since the relative path to your package gets stored in docs/Manifest.toml. Later, doing julia --project=docs/ docs/make.jl will pick up the correct package.
Locally, one thing you need to make sure is „which version of your package is used“.
If you just Pkg.add (or ] add ...) your package from the local folder, the package is copied over to the Julia folder. To load the package from the folder where you develop the package make sure tu run ] dev . in Julia REPL. that way the package is loaded from the folder where you issued this command. you can also check this in ] status that the package lists a folder behind where it loads from.
Then you can also run docs locally
PS: Don‘t worry the start takes a while in any language with package development, feel free to ask further questions of course.
Thanks very much, This connected the dots. Finally, I can continue improving my package and the documentation.
(@v1.8) pkg> dev .
Resolving package versions...
Updating `C:\Users\ploot\.julia\environments\v1.8\Project.toml`
[7876af07] ~ Example v0.5.3 ⇒ v0.5.4 `..\..\..\Downloads\Example`
Updating `C:\Users\ploot\.julia\environments\v1.8\Manifest.toml`
[7876af07] ~ Example v0.5.3 ⇒ v0.5.4 `..\..\..\Downloads\Example`
(@v1.8) pkg> status
Status `C:\Users\ploot\.julia\environments\v1.8\Project.toml`
[336ed68f] CSV v0.10.9
[159f3aea] Cairo v1.0.5
⌃ [a93c6f00] DataFrames v1.4.4
[31c24e10] Distributions v0.25.80
[e30172f5] Documenter v0.27.24
[35a29f4d] DocumenterTools v0.1.16
[7876af07] Example v0.5.4 `..\..\..\Downloads\Example`
julia> include("docs/make.jl")
┌ Warning: Unable to determine HTML(edit_link = ...) from remote HEAD branch, defaulting to "master".
│ Calling `git remote` failed with an exception. Set JULIA_DEBUG=Documenter to see the error.
│ Unless this is due to a configuration error, the relevant variable should be set explicitly.
└ @ Documenter.Utilities C:\Users\ploot\.julia\packages\Documenter\H5y27\src\Utilities\Utilities.jl:822
[ Info: SetupBuildDirectory: setting up build directory.
[ Info: Doctest: running doctests.
[ Info: ExpandTemplates: expanding markdown templates.
[ Info: CrossReferences: building cross-references.
[ Info: CheckDocument: running document checks.
[ Info: Populate: populating indices.
[ Info: RenderDocument: rendering document.
[ Info: HTMLWriter: rendering HTML pages.
…and on GitHub the documenter.yml GitHub workflow/action does the same then, but this way you can also generate the docs locally (in docs/build).but be careful not to add that folder to your repo, that is just a cause for merge conflicts.
It puts the package that is in the current folder (.) into development mode, that is, when you do using ThatPackage (the one on .) the code is compiled from that folder.
if you do ] status (that is in package mode) you see the folder listed after the package. For example in my status I have
Well, the version in the folder that you dev-ed. If you check out the repository of a version a few releases back in that folder, that is what you are running on. If it is even something newer than the last registered version (because you develop that further) that is what you are running on.
