Ah February, a month to celebrate love in all of its meanings: Valentines Day to celebrate love with your significant other, Black History Month to love and celebrate those different from us, and for Orchid, hippie love with new support for the Groovy programming language.
This is a monthly newsletter around Orchid, the newest and best static site generator for the JVM. There is a growing need to keep the community up-to-date on all the happenings around Orchid, and here I will share Orchid's progress during the previous month! Follow along with this series to stay on top of Orchid's newest features, track adoption on Github, and see who's using Orchid!
Build and deploy beautiful documentation sites that grow with you
Quick-Start • Documentation • Tutorials • Showcase • Support
Quick-Start
Documentation
Orchid's User Manual will walk you through the main features of Orchid and give you a deeper understanding of each topic and feature.
Tutorials
There are several tutorials designed to walk you through building an Orchid site from scratch. The source for all tutorials can also be found in the OrchidTutorials repository.
Showcase
View the Showcase to see Orchid in action.
Support
Contributors
This project exists thanks to all the people who contribute. To get involved, please see CONTRIBUTING.md
Backers
Thank you to all our backers!
Sponsors
Support this project by becoming a sponsor. Your logo will show up here with a link to your website.
License
Orchid is open-source software licensed under the GNU Lesser General Public License (LGPL-3.0). Please see License.md
Contact
…
On Github
As of the time of writing, Orchid is at 157 stars on Github. This was a really great month, with Orchid's new features and a blog post here garnering quite a bit of attention. Thanks for all the support!
In The Media
After releasing 0.16.0, I published a post here on Dev.to detailing how to use Orchid to document Kotlin projects from beginning-to-end. It got quite a bit of attention and is definitely the best place to start if you're wanting t get started using Orchid for any of your projects. Be sure to check it out if you haven't already!
What's New?
Orchid is now at version 0.16.1, a bugfix version after 0.16.0, which brought with it a ton of cool new features that I teased with last month's entry. All of these features have been released and are ready for you to use!
New theme: Copper
The theme I built for my own site, now you can use for yours! Based on Bulma, this theme is great for showcasing the best projects for your portfolio, but is equally good for documentation.
For examples of Orchid sites using this new theme, checkout caseyjbrooks.com or the Trellis docs and JSON Documentation Formatters docs.
New bundle: Orchid Docs
After setting up many of my other library projects with Orchid documentation, I've noticed myself adding the same plugins over and over to each project. To make it easier for others to get started with Orchid as a documentation tool, I've created a new Bundle, OrchidDocs, which contains the following plugins:
-
OrchidCore: The core Orchid framework -
OrchidEditorial: A default theme (subject to change in a later version) -
OrchidPages: Static pages to hold changelogs, contact forms, project license, etc. -
OrchidWiki: The full wiki documentation for the site -
OrchidForms: Easily add contact or bug report forms -
OrchidChangelog: Manage project versions, and update Github releases automatically on deploy -
OrchidSearch: Enable full-text search of your docs -
OrchidDiagrams: Describe your project with diagrams and flow charts -
OrchidSyntaxHighlighter: Your choice of either server-side or Javascript-based highlighting
New plugin: Groovydoc
Delivered by request, Groovy will be an officially-supported language for Orchid code documentation. The Groovy plugin allows you to easily document your Groovy and Java source code and embed it in any Orchid theme you like.
Coming Soon
Orchid is currently in the aftermath of releasing a major version, which typically means focusing on bugfixes, tests, and documentation. You can expect increasing stability and theme improvements over the next few weeks/months.
In addition, adding the Groovydoc plugin helped me understand better how Orchid should handle code documentation, and work is underway to greatly improve this for all languages. Work is underway that will make it significantly easier to add additional programming languages that Orchid can work with, and also make it easier and more flexible for you to document your projects. You can follow the work toward this goal in the following issue on Github.
Modularize and unify code documentation plugins
#232
This is the beginning of a major reworking of how Orchid handles code documentation. These changes are mostly structural, and I expect only minor changes to be needed by end-users when it is complete.
Abstract
Instead of having separate plugins which each provide their own generators/templates/menu items/etc., Orchid should have a single plugin that does the work of configuring and generating all the Orchid stuff needed. The language plugins then just need to provide adapters to that common "code documentation" model to work.
Specifically, the copper-leaf/dokka-json will provide a common interface and configuration strategy that the main Orchid plugin will work with, and the individual languages in that repo each provide the adapters needed to work with it.
By including the main code documentation plugin and the individual language adapters needed, no additional Orchid-specific work needs to be done to support new languages. All that would be required is creating a language model that conforms to the copper-leaf/dokka-json common interface, which is tool-agnostic.
Requirements
- [x] 1. Get all languages currently supported by Orchid moved to the model used in the copper-leaf/kodiak project
- [X] 1.1. Java
- [X] 1.2. Kotlin
- [X] 1.3. Groovy
- [x] 1.4. Swift
- [x] 2. Create a common interface in the copper-leaf/dokka-json project that Orchid will eventually read. Make all supported languages conform to this common specification
- [x] 3. Create a common "code doc" plugin in Orchid that reads the abstract model and can generate anything code it needs. It should have a way to register the individual language extensions (potentially using Java Service Locators for Orchid-independence)
- [x] 3.1. Generate doc pages similar to existing plugins (but namespaced)
- [x] 3.2. Allow multiple modules for each source type, each with multiple source dirs
- [x] 3.3. Landing pages with
READMEpage content for each module - [x] 3.4. Menu items
- [x] 3.4.1. Page links (link to IDs on a single page)
- [x] 3.4.2. Module pages (link to subpages of a single module)
- [x] 3.4.3. Modules (link to homepages of each module)
- [x] 3.5. Collections
- [x] 3.5.1. Pages by node-kind for each module
- [x] 3.5.2. All doc pages each module
- [x] 3.5.3. Landing pages for all modules
- [x] 4. Deprecate and remove existing code doc plugins, in favor of using the unified and modularized approach above.
- [x] 4.1. Deprecate existing plugins, but keep around for 0.18.0 release
- [ ] 4.2. Completely remove existing plugins in 0.19.0 release
New Code Documentation Approach
Currently, each code documentation plugin takes multiple source directories and creates a single "documentation module" per-language. This might cause an issue where code that is separated into multiple modules would be displayed in Orchid as if they were not. Furthermore, code docs from different languges don't necessarily play well together.
Instead of having a separate generator for each language, there will be a single generator. The configuration for that generator specifies a list of "code modules". Each module is given its source language(s), and it will generate the pages for each module in isolation. But it will also create a "module index" and related menu items, etc. You could, for example, create separate modules in your Orchid docs for each Gradle module in the project, where each module is processed separately, even though they have the same source language.
This will also provide a better system for putting code API at subdirectories of your site, while still being able to index and reference external API docs. This will involve publishing a registry of your sites modules in meta/code-modules.json (or something like that), and at runtime reading an external site's code-modules.json file, using that to index the pages rendered by each module, and then the page lookups performed when rendering its own site will look in the metadata of those individual modules rather than relying on a specific folder structure of the external site.
Are you interested in getting started with Orchid? There simply is no better way to manage all the documentation for your project, and I'd love to help you get set up!
If you have an open-source project that needs docs, are building a new portfolio, or are building any other kind of static site, I want to work with you to get you set up with Orchid! Comment on this post, send me a PM here on Dev.to, or contact me here and I will be with you every step of the way.
And as always, let me know if you start using Orchid so I can feature you in next month's update!
Top comments (0)