Documenter - @autodocs example evaluation - functions order

General Usage
, ,
1

I have two questions regarding @autodocs in Documenter.

  • How can I evaluate the examples in the docstrings when I use @autodocs?

  • The order of functions that appear when I use @index and @autodocs is based on alphabet, while I want it to be in the order that the functions appear in the code. Is this a known issue?
    For instance for my MatLang package:
    Functions List · MatLang

2

You can not. The at-blocks generally on work on the Markdown pages. My view is that docstrings need to stay readable in the REPL, so you shouldn’t have generated content there (unless you have some DocStringExtensions-like solution).

I am not sure if “order in which they appear in the code” is completely well-defined. But if I remember correctly, the docstrings do get stored in order in which they are parsed, so the information is there. Feel free to open an issue to discuss this further – we could potentially have some sort of a Sort option for at-autodocs. The sorting of the autodocs docstrings appears to be happening here.

On the other hand, I have a feeling that if you do really care about the order in which the docstrings appear, you should probably be curating that manually with at-docs blocks.

2 Likes
3

I have created the issue two weeks ago.
https://github.com/JuliaDocs/Documenter.jl/issues/1127

I tried to solve the issue myself but disabling this section of the code doesn’t seem to have any effect on document creation. Also, the debugger skips the breakpoints. How can I debug a doc creation in Documenter?
There is a similar code also in https://github.com/JuliaDocs/Documenter.jl/blob/6a409bbfd394352bfd33148f1acc24ce2fa1024b/src/Documents.jl#L405-L418 which seem to sort some index links.