Help absolute noob/scientist with a minimal example

New to Julia
1

I am following the official Documenter.jl’s Guide and I am running into problems.

To give some context:

I have a numerical “library” I made for my research I want to make public with Documenter.jl using GitHub. It is very basic, essentially a /src folder containing all the source code for the simulations and a /experiments folder that uses include("/src/src_file.jl") to perform various numerical experiments.

What I’ve tried:

I figured that in essence my code structure is the same as if everything was inside a massive src.jl file which gets called by experiment_1.jl files. So I created the following minimal example:

repo/
│── repo_env/     # Environment folder (only contains Documenter.jl)
│   │── Manifest.toml    
│   │── Project.toml   
│── src/
│   │── src.jl    # Module file
│   │── test.jl   # A file the module calls
│── docs/
│   │── make.jl   # The Guide example

with the following contents:

# src/src.jl
module Test_Module

export test

include("test.jl")

end # end of module

# src/test.jl
function test(x) 
    return 2*x 
end

push!(LOAD_PATH,"../src/")

using Documenter, .Test_Module

makedocs(sitename="My Documentation")

The reason I made a module (something I wouldnt normally do since I dont use/understand them properly) is because I sense that it is needed. In fact, the official Guide mentions that “Firstly, we need a Julia module to document. This could be a package generated via PkgDev.generate or a single .jl script accessible via Julia’s LOAD_PATH .”

Results/errors:

To be fair I’ve tried a plethora of little tweaks and none work with slightly different errors. I’m gonna put this one as it’s the one I expect to learn the most from:

(base) alex@Lord-Commander-Flagship Quantum_Geometric_Complexity % julia --project=repo_env docs/make.jl
ERROR: LoadError: UndefVarError: `Test_Module` not defined in `Main`
Suggestion: check for spelling errors or missing imports.
in expression starting at /Users/alex/Documents/GitHub/Quantum_Geometric_Complexity/docs/make.jl:3

So it’s obviously not finding the module Test_Module despite following the official Guide advice on this issue:
"
If your source directory is not accessible through Julia’s LOAD_PATH, you might wish to add the following line at the top of make.jl

push!(LOAD_PATH,"../src/")

"

Help!

I would love to see a minimal working example for something as basic as what I am doing and understand why I get the errors I get.

Unsolicited opinion:

For what is worth, I believe that the way the official Guide is written, it implicitly assumes the reader is versed in Modules, Packages and what not. This is fine and should probably be a good idea to learn anyways. However, there are many Julia users like myself who limit to writting efficient (yet unproffessional) numerical code and wish to share it. I know many Julia users in my enviroment that would follow a very similar workflow as what I described in the context above. Perhaps this could be addressed! (I would love to if I manage to understand what’s going on…)

2

I haven’t read your post in full to attempt an answer at your specific question, but this workshop was made exactly for people wanting to write documentation with documenter.jl , even starting just from pure scripts or source code functions :

an answer should be there.

As for your unsolicited opinion :stuck_out_tongue: : it is entirely possible to use Documenter.jl locally without knowning much, if anything, about the concept of modules and packages. However, doing so will make everything so much harder for you. It is literally easier to first learn the basisc of packages (5 minutes max in the official docs) and then go to documenter. And the advantage: you also learn about environments as you learn the other things, which a very important component of reproducible workflows.

3 Likes
3

Some minimal examples can be found here:

and

I use those instructions every time I´m creating a new package, but do not intend them to be comprehensive at all.

3 Likes
4

Great resource, let’s see if I can make it work after watching this! Speaker seems to be a close relative of yours :wink:

5

I have now watched the entire video and I am ashamed to admit that it doesn’t solve my issue. Worst is I don’t even know how to debug the code, errors are often unexpected ArgumentError: Unable to determine the commit for the remote repository (but there’s no repo!)

6

However, I really enjoyed the video and found it a great reference for documenting my code and future packages in the future. It’s pretty sexy the figs generation within the docs!

7

I think you need this directory structure:

repo/
│
│── Manifest.toml    
│── Project.toml   
│── src/
│   │── src.jl    # Module file
│   │── test.jl   # A file the module calls
│── docs/
│   │── make.jl   # The Guide example

Then change to this line of docs/make.jl:

using Documenter,  Test_Module

Then you will need to install git and initialize a git repo in your project folder (repo/). You do not need to use github, but I’m 95% sure you need a git repo for this line (of make.jl) to work:

makedocs(sitename="My Documentation")

You also need to activate a second project in your /docs directory (there should be a Project.toml in there).

There may be more but try that and see what error you get.

8

I also see there is no docstring, try this:

# src/test.jl
"""
    test(x)

Multiplies x by 2.
"""
function test(x) 
    return 2*x 
end

Edit:

Another thing is you need a docs/src/index.md file. Create one (including the new docs/src/ directory), and put this in it:

# Test_Module
```@contents
```

## Documentation
```@meta
CurrentModule = Test_Module
```

```@autodocs
Modules = [Test_Module]
```

## Index
```@index
```