[Plugin Proposal] Snippets

cjbrooks12 commented 5 years ago

A very common desire (and rarely done due to the difficulty of it) is to include snippets of code or other things in the documentation sites. This new plugin would add a standard way of registering "snippets" with Orchid that could be embedded anywhere as a TemplateTag.

Something like this was implemented already for Strikt, but that was very ad-hoc and crafted for that Orchid site. This would need to be a more general solution that can be very easily set up and used by anyone.

Requirements

A new plugin, OrchidSnippets, with 2 ways of creating Snippets:

As static content files (Markdown or otherwise) in the snippets/ resource directory
parsed as the text between comments/markers in ordinary text files in specified directories (such as from unit tests or class declarations)

Features

SnippetsGenerator: A generator that produces no pages, but indexes site resources and other directories to find available snippets
SnippetTag: A TemplateTag to display an indexed snippet by its ID inline in arbitrary content
SnippetComponent: An OrchidComponent to display an indexed snippet by its ID in the list of page components, in the sidebar, etc.
This will be included in the OrchidDocs bundle.

Dependencies

Nothing is blocking work from being started on this feature. It should be fairly easy to implement and would be a good candidate for someone looking to get started contributing to Orchid, as it introduces some of the main concepts around plugin creation and indexing.

cjbrooks12 commented 4 years ago

Inspiration for this feature:

tomb50 commented 4 years ago

For what it is worth, it is very possible to use AsciiDoc plugin and then use the include directive to achieve most of what is functionally described.

Got it working to load source files (java) extracting snippets into a file, works great, it is dependent on this small MR getting through though: #347 to enable the include directive.

happy to provide more details if needed.

cjbrooks12 commented 4 years ago

I didn't realize that the AsciiDoc includes could handle portions of a file instead of the whole thing. Really cool!

This plugin proposal is intended to work across all markup languages and so can't rely on AsciiDoc's native functionality, but it should definitely still work for migrating existing AD content to Orchid. I'll get your PR merged in shortly.

tomb50 commented 4 years ago

Awesome, thanks for your hard work! and yeah it would be amazing to have a general-purpose approach eventually.

DevSrSouza commented 4 years ago

Could be nice if supports multi languages snippets like in Kotlin docs, Android docs and Gradle docs, this could be great for iOS libraries that have samples wrote in Swift and Objective-C.

A developer from Gradle wrote a blog post about it, is built manually, you can check it here

Samples:

Kotlin docs

Android docs

Gradle docs

orchidhq / Orchid