Integrated markdown parsing and guide support

[agentk]

Fixes: #435
Rebases: #437

Adds two configuration options:

--documentation: A glob for extra documentation to be injected similar to readmes, but also listed in the sidebar.
--abstract: A glob for injecting extra content into matching Abstract group sections.

This is a rough commit. I have no idea what to test in ruby. Would love some suggestions on what to look at next,

[agentk]

I think I also need to separate this into smaller testable chunks to be submitted separately as PR's.

[jpsim]

Integration specs are failing with the following stack trace:

ROOT/lib/jazzy/source_document.rb:32:in `block in fallback_readme': undefined local variable or method `config' for #<Jazzy::SourceDocument:0x007fdcd0d857c0> (NameError)
 from ROOT/lib/jazzy/source_document.rb:31:in `each'
 from ROOT/lib/jazzy/source_document.rb:31:in `fallback_readme'
 from ROOT/lib/jazzy/source_document.rb:23:in `readme_content'
 from ROOT/lib/jazzy/source_document.rb:18:in `content'
 from ROOT/lib/jazzy/doc_builder.rb:249:in `document_markdown'
 from ROOT/lib/jazzy/doc_builder.rb:354:in `document'
 from ROOT/lib/jazzy/doc_builder.rb:83:in `block (2 levels) in build_docs'
 from ROOT/lib/jazzy/doc_builder.rb:82:in `open'
 from ROOT/lib/jazzy/doc_builder.rb:82:in `open'
 from ROOT/lib/jazzy/doc_builder.rb:82:in `block in build_docs'
 from ROOT/lib/jazzy/doc_builder.rb:93:in `call'
 from ROOT/lib/jazzy/doc_builder.rb:93:in `block in each_doc'
 from ROOT/lib/jazzy/doc_builder.rb:89:in `each'
 from ROOT/lib/jazzy/doc_builder.rb:89:in `each_doc'
 from ROOT/lib/jazzy/doc_builder.rb:78:in `build_docs'
 from ROOT/lib/jazzy/doc_builder.rb:118:in `build_site'
 from ROOT/lib/jazzy/doc_builder.rb:146:in `build_docs_for_sourcekitten_output'
 from ROOT/lib/jazzy/doc_builder.rb:69:in `build'
 from ROOT/bin/jazzy:15:in `<main>'

[agentk]

Yeah 😳. I missed a couple of things in the process of rebasing. This PR could do with a WIP label. I mainly wanted to show some progress to guilt myself into getting it finished.

[jpsim]

No guilt needed! Let me know if/how I can help.

[agentk]

Woot. I'm finally rebased AND passing tests.

[lumaxis]

Do you think it would make sense to filter files named index.* here too?

[agentk]

I probably wouldn't hurt, but I'm not sure if it's necessary there. Without it, it makes it possible to override the readme and have it included in the Dash Guides section.

[jpsim]

It'd be good to add a basic test for this in the misc_jazzy_features fixture

Also, some basic documentation describing how to use this in jazzy's readme would be nice.

[agentk]

Good catch. Will do. 👍

[JanC]

Hi,
did you have the chance to review this? It would be great to have this feature merged

[jpsim]

@JanC still waiting on:

• basic test for this in the misc_jazzy_features fixture
• basic documentation describing how to use this in jazzy's readme
• merge conflicts being addressed

[agentk]

Hey @jpsim, my first attempt at fixtures and Readme are in. The fixture tests are passing, but they are pointed at my fork until they are ok to merge in (realm/jazzy-integration-specs#18). Once they are the fixtures are right to merge, I'll point the submodule back to realm and we can merge this.

[jpsim]

This is super great! Love the feature, love the docs you added 😄

I've merged realm/jazzy-integration-specs#18 and given you commit access to jazzy repos to simplify this in the future.

I think the only thing this is missing now is a changelog entry. Could you make a new PR for that? I'll merge this one right away.

[JanC]

This was merged but not yet released, correct?

[agentk]

Correct. Looks like it will probably go out with #569 :-)