Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
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.
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.
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