search

JuliaDocs / Documenter.jl

A documentation generator for Julia.
https://documenter.juliadocs.org
MIT License
814 stars 482 forks source link

@autosummary block #1672

Open goerz opened 3 years ago

goerz commented 3 years ago

I would love to have an @autosummary block that takes the same arguments/filtering options as @autodocs, but only shows the name of the function and the first line or sentence of its docstring, linking to the full documentation elsewhere. Basically, something that renders as a markdown list

* [`function`](@ref) - summary

Alternatively (or in addition) add an option to @index to filter with the same options as @autodocs, specifically a variation of Pages that filters by source (jl) file, not by md file, and additional public/private filtering

A third option would be the one proposed in #1393

In all cases, the intent is to have structured summaries of the routines in a module or source file, without the full detail of the entire docstring. I'm aiming for something like the Summary/Reference layout in the API docs of the krotov Python package (which I'm currently porting to Julia)

goerz commented 3 years ago

As an aside, I also just wanted to say that I'm quite impressed with Documenter.jl in general. It's a very clean design, compared to something like Sphinx! Thank you for your work!

mortenpi commented 3 years ago

I would suggest trying to implement a proof-of-concept version externally as a plugin. It should be a separate ExpanderPipeline step.

goerz commented 3 years ago

I might actually try my hand at that at some point, if I have time...

Incidentally, is there some more documentation about the internal structure of Documenter.jl? What I mean is how the various pieces in the "Internals" section fit together. What actually happens when Documenter.jl processes a .md file? I assume it parses the markdown into an internal representation, and then uses one of the Writers to write that representation to html/pdf output. But how is that internal representation structured?

I did see your Juliacon 2019 talk, but it wasn't nearly as "under the hood" as I had hoped ;-)

I can probably figure out some details by going through the package with a debugger and just spending more time looking at the code, but more documentation about the internal structure could be very helpful (also for others who may want to work on or extend Documenter.jl)