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

Modularize and unify code documentation plugins #232

Open
cjbrooks12 opened this issue Feb 22, 2019 · 0 comments

Comments

@cjbrooks12
Copy link
Member

commented Feb 22, 2019

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

  • 1. Get all languages currently supported by Orchid moved to the model used in the copper-leaf/dokka-json project
  • 1.1. Java
  • 1.2. Kotlin
  • 1.3. Groovy
  • 1.4. Swift
  • 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
  • 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)
  • 4. Deprecate and remove existing code doc plugins, in favor of using the unified and modularized approach above.

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
1 participant
You can’t perform that action at this time.