Update docs outline generation

[dylan-asmar]

This addresses #565.

This maintains the structure as before where we have subsections for each part of then the outline. The current way @contents is structured, it only accepts a list (link to documentation) for the Pages variable. If you pass the same structure we generate for makedocs you get:

ERROR: LoadError: MethodError: Cannot convert an object of type Pair{String, Vector{String}} to an object of type String
The function convert exists, but no method is defined for this combination of argument types.

This version appends the outline to the bottom of index.md, generates the docs, and then restores the original index.md file.

With that being said...we don't have to maintain the layout as we currently have it.

[dylan-asmar]

Docs preview: https://juliapomdp.github.io/POMDPs.jl/previews/PR566

[zsunberg]

Writing to a file like this seems a bit complex and hard to maintain. What if we just do something like this:

julia> page_order = ["A" => ["a1.md", "a2.md"],
                     "B" => ["b1.md"]]
2-element Vector{Pair{String, Vector{String}}}:
 "A" => ["a1.md", "a2.md"]
 "B" => ["b1.md"]

julia> contents_pages = reduce(vcat, map(last, page_order))
3-element Vector{String}:
 "a1.md"
 "a2.md"
 "b1.md"

Then we can use Pages = contents_pages in the index.md file I think.

[dylan-asmar]

Yeah, that would work, we would just lose the grouping of pages. If we are ok with changing the layout, then we could do it this way. Writing the file was the only way I could think of doing it while maintaining the current layout.

[dylan-asmar]

I'm not quite sure if many people even use the outline at the bottom of the page when a similar structure exists on the left sidebar. Perhaps we could just remove this section?

Here is a comparison of what it would look like keeping the groupings vs not.

[zsunberg]

True. I think the number one goal is to keep it easy to maintain. Let's either (1) keep the outline without the headers or (2) get rid of the outline

I lean slightly towards (1), but am totally good with (2) if you prefer

[dylan-asmar]

I decided to go with option 1. The preview of the docs is updated.

[dylan-asmar]

@zsunberg Are we good to merge?

[zsunberg]

Awesome! Thank you!

[zsunberg]

Looks good - I am a bit surprised taht you can execute that complex julia code in the @contents block - it might have been better to put it in make.jl, but it seems to work. Hopefully it will keep working.