From db3ed815dc2b3513494a8fdb54a883722befca7c Mon Sep 17 00:00:00 2001 From: Karol Lewandowski Date: Fri, 15 Nov 2024 09:54:44 +0100 Subject: [PATCH] IJPL-116409: Plugin.xml documentation provider - Add schema GitOrigin-RevId: 536a0b26ddcc1af529ce50e77f355d97a829eb12 --- .../resources/intellij.devkit.core.xml | 1 + .../messages/DevKitBundle.properties | 4 +- .../descriptor-documentation-schema.json | 174 ++++++++++++++++++ ...rDocumentationYamlSchemaProviderFactory.kt | 36 ++++ 4 files changed, 214 insertions(+), 1 deletion(-) create mode 100644 plugins/devkit/devkit-core/resources/schemas/descriptor-documentation-schema.json create mode 100644 plugins/devkit/devkit-core/src/documentation/DescriptorDocumentationYamlSchemaProviderFactory.kt diff --git a/plugins/devkit/devkit-core/resources/intellij.devkit.core.xml b/plugins/devkit/devkit-core/resources/intellij.devkit.core.xml index f24272017209..862b42672910 100644 --- a/plugins/devkit/devkit-core/resources/intellij.devkit.core.xml +++ b/plugins/devkit/devkit-core/resources/intellij.devkit.core.xml @@ -675,6 +675,7 @@ + diff --git a/plugins/devkit/devkit-core/resources/messages/DevKitBundle.properties b/plugins/devkit/devkit-core/resources/messages/DevKitBundle.properties index 5e283b97e645..4efe68f11f77 100644 --- a/plugins/devkit/devkit-core/resources/messages/DevKitBundle.properties +++ b/plugins/devkit/devkit-core/resources/messages/DevKitBundle.properties @@ -714,4 +714,6 @@ inspection.can.be.dumb.aware.quickfix.add.to.ignore=Ignore ''{0}'' inspections.check.return.value=Return value must be checked # {0} is the identifier of the inspection. It's a relatively short ASCII string. -inspection.message.return.value.must.be.checked=[{0}] Return value must be checked \ No newline at end of file +inspection.message.return.value.must.be.checked=[{0}] Return value must be checked + +descriptor.documentation.yaml.schema.display.name=Descriptor Documentation diff --git a/plugins/devkit/devkit-core/resources/schemas/descriptor-documentation-schema.json b/plugins/devkit/devkit-core/resources/schemas/descriptor-documentation-schema.json new file mode 100644 index 000000000000..2b85f2aa95c4 --- /dev/null +++ b/plugins/devkit/devkit-core/resources/schemas/descriptor-documentation-schema.json @@ -0,0 +1,174 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "Descriptor Documentation Schema", + "type": "object", + "properties": { + "baseUrl": { + "type": "string", + "description": "Base URL for the SDK documentation page." + }, + "elements": { + "type": "array", + "description": "Array of elements defined in the descriptor file.", + "items": { + "$ref": "#/definitions/ElementWrapper" + } + } + }, + "definitions": { + "ElementWrapper": { + "type": "object", + "description": "Element object wrapper.", + "properties": { + "element": { + "$ref": "#/definitions/Element" + } + }, + "additionalProperties": false + }, + "Element": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the element." + }, + "sdkDocsFixedPath": { + "type": "array", + "description": "Fixed path to this element used for the section ID on the SDK documentation page. It should be used in cases, when the same element is a child of multiple elements and we want to render it only once.", + "items": { + "type": "string" + } + }, + "since": { + "type": "string", + "description": "Version since the element is available." + }, + "until": { + "type": "string", + "description": "Version until the element is available." + }, + "deprecatedSince": { + "type": "string", + "description": "Version since the element is deprecated." + }, + "deprecationNote": { + "type": "string", + "description": "Deprecation note for the element. Supports Writerside Markdown format." + }, + "description": { + "type": "string", + "description": "Description of the element. Supports Writerside Markdown format." + }, + "sdkDocsSupportDetails": { + "type": "string", + "description": "Support details. It is rendered only in SDK documentation. Use it when additional information about support is needed. Supports Writerside Markdown format." + }, + "attributes": { + "type": "array", + "description": "Array of attributes associated with the element.", + "items": { + "$ref": "#/definitions/AttributeWrapper" + } + }, + "containsItself": { + "type": "boolean", + "description": "Flag indicating whether the element can contain itself." + }, + "childrenDescription": { + "type": "string", + "description": "Description of child elements. Use it when children elements can't be included in the descriptor documentation (for example, they are dynamic), or additional information is needed. Supports Writerside Markdown format." + }, + "children": { + "type": "array", + "description": "Array of child elements.", + "items": { + "$ref": "#/definitions/ElementWrapper" + } + }, + "references": { + "type": "array", + "description": "Array of reference page links associated with the element. Supports Writerside Markdown format.", + "items": { + "type": "string" + } + }, + "requirement": { + "$ref": "#/definitions/Requirement" + }, + "defaultValue": { + "type": "string", + "description": "Default value for the element, if applicable. Supports Writerside Markdown format." + }, + "examples": { + "type": "array", + "description": "Examples for the element. Supports Writerside Markdown format.", + "items": { + "type": "string" + } + } + }, + "required": ["name"], + "additionalProperties": false + }, + "Requirement": { + "type": "object", + "properties": { + "required": { + "type": "string", + "description": "Element requirement.", + "enum": ["yes", "no", "yes_for_paid", "unknown"] + }, + "details": { + "type": "array", + "description": "Additional details about the requirement. Supports Writerside Markdown format.", + "items": { + "type": "string" + } + } + }, + "additionalProperties": false + }, + "AttributeWrapper": { + "type": "object", + "properties": { + "attribute": { + "$ref": "#/definitions/Attribute" + } + }, + "additionalProperties": false + }, + "Attribute": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the attribute." + }, + "since": { + "type": "string", + "description": "Version since the attribute is available." + }, + "until": { + "type": "string", + "description": "Version until the attribute is available." + }, + "requirement": { + "$ref": "#/definitions/Requirement" + }, + "description": { + "type": "string", + "description": "Description of the attribute. Supports Writerside Markdown format." + }, + "defaultValue": { + "type": "string", + "description": "Default value for the attribute, if applicable. Supports Writerside Markdown format." + } + }, + "required": ["name"], + "additionalProperties": false + } + }, + "required": ["elements"], + "additionalProperties": false +} diff --git a/plugins/devkit/devkit-core/src/documentation/DescriptorDocumentationYamlSchemaProviderFactory.kt b/plugins/devkit/devkit-core/src/documentation/DescriptorDocumentationYamlSchemaProviderFactory.kt new file mode 100644 index 000000000000..ab00d03bc177 --- /dev/null +++ b/plugins/devkit/devkit-core/src/documentation/DescriptorDocumentationYamlSchemaProviderFactory.kt @@ -0,0 +1,36 @@ +// Copyright 2000-2024 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. +package org.jetbrains.idea.devkit.documentation + +import com.intellij.openapi.project.DumbAware +import com.intellij.openapi.project.Project +import com.intellij.openapi.vfs.VirtualFile +import com.jetbrains.jsonSchema.extension.JsonSchemaFileProvider +import com.jetbrains.jsonSchema.extension.JsonSchemaProviderFactory +import com.jetbrains.jsonSchema.extension.SchemaType +import org.jetbrains.idea.devkit.DevKitBundle + +internal class DescriptorDocumentationYamlSchemaProviderFactory : JsonSchemaProviderFactory, DumbAware { + override fun getProviders(project: Project): List { + return listOf(DescriptorDocumentationYamlSchemaProvider(project)) + } + + class DescriptorDocumentationYamlSchemaProvider(val project: Project) : JsonSchemaFileProvider { + override fun getName(): String = DevKitBundle.message("descriptor.documentation.yaml.schema.display.name") + + override fun getSchemaType(): SchemaType = SchemaType.embeddedSchema + + override fun isAvailable(file: VirtualFile): Boolean { + return isDescriptorDocumentationFile(file) + } + + private fun isDescriptorDocumentationFile(file: VirtualFile): Boolean { + return file.extension == "yaml" && file.parent?.path?.endsWith("devkit-core/resources/documentation") == true + } + + override fun getSchemaFile(): VirtualFile? { + return JsonSchemaProviderFactory.getResourceFile( + DescriptorDocumentationYamlSchemaProviderFactory::class.java, "/schemas/descriptor-documentation-schema.json" + ) + } + } +}