Basic setup for documentation

New to Julia
1

I’m trying to follow the Guide to set up a basic documentation. I used pkg> generate Example in order to generate an example package and then DocumenterTools.generate as suggested. I then created an empty index.md file in /docs/src and ran the automatically generated make.jl file. I then get the following output:

[ Info: SetupBuildDirectory: setting up build directory.
[ 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.

which is slightly different from what I expected, but no other problems so far.
I then add a function func with associated docstring exactly as described in the guide.
When I re-run make.jl, I get

┌ Warning: 1 docstring potentially missing:
│
│     Example.func :: Tuple{Any}
└ @ Documenter.DocChecks ~/.julia/packages/Documenter/msPrq/src/DocChecks.jl:62

which indicates that the function was found but there is no corresponding documentation.
I then add an entry to index.md. But upon re-running make.jl, I get

┌ Warning: duplicate docs found for 'func(x)' in `@docs` block in src/index.md:3-5
│ ```@docs
│ func(x)
│ ```
└ @ Documenter.Expanders ~/.julia/packages/Documenter/msPrq/src/Expanders.jl:301

and the build html file has a missing docstring warning.
Now I don’t understand what this is trying to tell me; as far as I’m aware there is only one docstring for the function in question. I could be missing a step that ensures that the docstring is read correctly.

But how do I set up this example correctly?

2 Likes
2

The “docstring potentially missing” missing warning means that an existing docstring was not included in the manual (with an at-docs or at-autodocs block). “duplicate docs found” means that the same docstring is included multiple times (in different at-docs or at-autodocs blocks).

Without seeing that actual code it’s hard to say anything more, but I would suspect that you have multiple at-docs blocks? Or, possibly, an at-docs block and an at-autodocs block that also includes the same docstring?

If you want a minimal working example of setup you can check out Example.jl. Comparing with that might help to nail down the issue.

1 Like
3

Thanks! I will check it out and come back later!

4

Unfortunately the same error occurs with the Example.jl that you linked. Maybe there is something wrong with my setup. I will try on a different machine.