Respect the :section metadata when generating help HTML

[blahah]

When generating HMTL it would be ideal if all methods/types/etc. annotated with a particular section were grouped into a section in the HTML.

For example:

@doc """
Markdown formatted text appears here...
""" {
    # metadata section
    :section => "Main section"
    } ->
function myfunc(x, y)
    # ...
end

@doc """
Different Markdown formatted text appears here...
""" {
    # metadata section
    :section => "Next section"
    } ->
function anotherfunc(x, y)
    # ...
end

Should produce something like...

Main section

• myfunc(...)

  Next section

• anotherfunc(...)

[MichaelHatherly]

Yes, this was my original intention for the :section metadata. So far I've been undecided about how the different sections would be organised. Presumably the sections should appear in alphabetical order and across sections the types, functions, macros, etc subsections should retain the same ordering.

I'd ideally like this all to be customisable via something like a doc/build.jl script.

[MichaelHatherly]

Separate pages for each section might be nice as well.

[blahah]

At the moment I'm building BioJulia docs with a tiny script, makedocs.jl:

using Lexicon, Bio

save("index.html", Bio)
save("phylo.html", Bio.Phylo)

This generates a simple two-page documentation. I was thinking of doing a more structured version manually at first by using queries to pull out methods related to a particular type:

using Lexicon, Bio
phynode_help = query("PhyNode", Bio.Phylo)
save("PhyNode.html", phynode_help)

Any thoughts on the fastest route to getting this to work?

[MichaelHatherly]

At the moment using query (or @query) would be the quickest for something custom like that. It's also probably the most flexible since it's got the full use of Julia to manipulate it however you'd like.

I think that standardising on a particular way of doing this would be great.

There's Mustache.jl if you need some template files. It might be worth leveraging more packages that are already available now that it won't have an impact of Docile load times.

[MichaelHatherly]

Also query returns an Entries object and save doesn't handle that, so you'd have to dig into some of the internals of render.jl currently. Improvements to that file are definitely needed at this point.

[blahah]

Thanks, I'm just exploring internals to make a save_sectioned that collects the entries by :section metadata. Would you like a PR?

[MichaelHatherly]

Yes please, that would be great.

[peter1000]

I would like to plan something like that from the start in the new Lexicon.

1. Question: does Docile extract the :section meta tag like the numbers or is Lexicon doing this ;)
2. I would propose something a bit like MkDocs. If someone uses the :section meta one can expect that they are planning things a bit more than just the autoextraction.

So I would propose something like this:

Config

user_sections = Dict( [
                                  ( "SpecialCalculations.md", [:Section1, :Section2]),
                                  ( "Extras.md", [:Section1, :Section2])
                                ])

In the docstrings not sure what to do???

 :section   (Extras.m, :Section2)

[MichaelHatherly]

My thinking is that additional metadata embedded in the docstring should be extracted by the parsedocs(::Format, raw, obj, mod) methods.

Since it's passed the obj and mod all of the cached data for the module is available to it with getmeta, getpackage, and getmodule.

Some syntax for embedded metadata fields is needed, definitely. What do other languages use?

[peter1000]

No Idea what others do: but a thought would it be helpful if we define it like an expression than one does not have to do much except parse it - or I'm mistaken

"""

meta:  :(:section, "Calculation.md", :Section1)

"""

need to extract the line which start with meta or whatever strip all white space and parse it or just a delimited string and split the items?

[peter1000]

• defined_sections (default: []) defined_sections is a Vector{Tuple{UTF8String, Vector{Symbol}}}

  The format is a Vectore of Tuples ("Filename", [:SectionNames])

  Example:

  defined_sections = ([("file1.md", [:Section1, :Section2]),
                    ("file2.md", [:ManualDefined, :ErrorCodes])
                    ("file3.md", [:Calculations, :ErrorCodes])
                  ])

  The final output will keep the order of the sections as well as the order of the files. e.g. in the Index

  To fill pages and Sections with documentation of objects the docstrings need to use the meta tag :section

  TODO: define if and how any _categoryorder, _mdstylesection or _includeinternal option effect this.

[peter1000]

The advantage I see in this format that automatically the order is also defined by the user. Very flexible to easily move a Section to somewhere else - even to an other file somewhere in the middle.

For any documented objects added to a Section it is more difficult to decide how to order them.

At the moment I would think to make it user defined in the :section meta or ordered.

something like: meta :section :("firstfile.md", :ErrorSection, 1) where the last Integer is the order of the obj in the Section. This would allow a complete user defined output order of all docstrings over multiple files - would also allow easily mixing of documented objects of multiple modules in common sections.

Personally I feel if someone does not want to use the automatic thing - probably they want to customize it an do not shy away from a bit extra work.

[peter1000]

I think this could be closed with the new document(...)

[MichaelHatherly]

Yes, filtering base of metadata will resolve this once we move to lexicon-next.