Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Plugin Proposal] Snippets #293

Open
cjbrooks12 opened this issue Jul 31, 2019 · 5 comments
Open

[Plugin Proposal] Snippets #293

cjbrooks12 opened this issue Jul 31, 2019 · 5 comments

Comments

@cjbrooks12
Copy link
Contributor

@cjbrooks12 cjbrooks12 commented Jul 31, 2019

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

This comment has been minimized.

Copy link
Contributor Author

@cjbrooks12 cjbrooks12 commented Dec 20, 2019

@tomb50

This comment has been minimized.

Copy link

@tomb50 tomb50 commented Jan 8, 2020

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

This comment has been minimized.

Copy link
Contributor Author

@cjbrooks12 cjbrooks12 commented Jan 14, 2020

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

This comment has been minimized.

Copy link

@tomb50 tomb50 commented Jan 18, 2020

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

@DevSrSouza

This comment has been minimized.

Copy link

@DevSrSouza DevSrSouza commented Feb 14, 2020

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

@cjbrooks12 cjbrooks12 moved this from Triage to In Progress in Backlog Feb 23, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
Backlog
  
In Progress
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
3 participants
You can’t perform that action at this time.