Troubles with Documenter


#1

Hi,

I’ve been fighting with Documenter for a while but can’t understand why it does what it does. The problem starts, and this is probably a good symptom of the root issue, with the fact that in my index.mb file the instruction ```@index ``` does not generate any index. So I had to go for the solution of creating @docs blocks for each function that I want documented. And here comes the puzzling part. I have > 80 functions and methods to pick up but Documenter only accepts with ~40. For the remaining it prints

Documenter: expanding markdown templates.
 !! No docs found for 'filter1d(cmd0::String="", arg1=[], kwargs...)'. [src\index.md]
 !! No docs found for 'fitcircle(cmd0::String="", arg1=[], kwargs...)'. [src\index.md]
...

and later

 > checking for missing docstrings.
 !! 45 docstrings potentially missing:

    GMT.sample1d :: Union{Tuple{}, Tuple{String}, Tuple{String,Any}}
    GMT.gmtselect :: Union{Tuple{}, Tuple{String}, Tuple{String,Any}}
    GMT.gmtconnect :: Union{Tuple{}, Tuple{String}, Tuple{String,Any}}
    GMT.grid_type :: Union{Tuple{Any}, Tuple{Any,Any}}
    GMT.grdfft :: Union{Tuple{}, Tuple{String}, Tuple{String,Any}, Tuple{String,Any,Any}}
    GMT.grdfilter :: Union{Tuple{}, Tuple{String}, Tuple{String,Any}}
...

but I can’t see any difference between the docstrings that it accepts and those the it ignores (what’s wrong in, for example, filter1d?). In fact, for testing, I even renamed one that it accepts to one it ignores and and this latter was then ignored. This proves that the refusal is not based on the docstrings contents.

The full list of indexed files can be seen here and the ensemble of all that should be indexed in here.

I really can’t figure out why some are considered good, and indexed, while others are stubbornly ignored.

Thanks for any help to fix this.