Custom sidebar entries and overriding group abstracts

[agentk]

What is the general consensus on adding custom sidebar content?

Jazzy covers almost everything I need for project docs. The only remaining items are documentation that falls between API docs and the README. Ie, extra installation instructions, troubleshooting, etc. Those items are typically going into a Jekyll powered site.

I understand the reluctance to make the sidebar content even longer, but with the theme changes the sidebar scrolling is no longer an issue.

Also helpful when using custom categories, is being able to insert content into the abstract section of the group page.

I have the changes working in a fork: https://github.com/agentk/jazzy/tree/integrated-markdown

I've added two new config items (JSON example):

{"documentation_glob": "docs/*.md", "abstract_glob": "docs/abstracts/*.md"}

Documentation glob looks for any files that match the glob, and adds them to the sourcekitten results and a 'Guide'' type. If found they are grouped under a heading of 'Guides' and can be overridden or reordered using custom_categories. They are also indexable with Dash.

The abstracts glob, looks for any file that matches a group name and renders the file as that groups abstract. This allows for more descriptive group pages.

BEWARE. I'm not a ruby developer. My changes are pretty rough.

The example code in use can be seen at: http://reduxkit.github.io/ReduxKit/api/
The Stores page is using a custom abstract: http://reduxkit.github.io/ReduxKit/api/Stores.html

[jpsim]

The docs glob is certainly useful, and something I support! We've been tracking this as #221.

The abstracts glob, looks for any file that matches a group name and renders the file as that groups abstract. This allows for more descriptive group pages.

This I have more difficulty understanding. Why not have that abstract in the doc comment for Stores?

[agentk]

Whew. I was really unsure how the guides support would be taken 😀.

I'm not proud of, and don't like what I did to get the custom abstract content inserted. It feels like the wrong way and is hard to understand.

I only did it as I couldn't work out where / how to put doc comments in the code that would show under the custom heading sections. Ie, there is not class or file called middleware for the section content to be placed under, but the middleware section abstract feel like the right place for documentation to be placed.

If I have missed something or it can be done another way, that would be great.

[jpsim]

Ah, I see. There's no way to provide abstract docs at the moment, so that makes sense.

Can you please make a PR towards jazzy so we can get this in? I'm sure we'll have thoughts on the implementation, but there's no doubt that the functionality is super useful 😄

[agentk]

Guides and custom abstracts are all bundled together in #437 at the moment. Would it be best if I seperate both of them and create new pull requests?

[jpsim]

Right, sorry I forgot you had already made a PR. No need to split it.