This is an automated email from the ASF dual-hosted git repository.
opwvhk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/avro.git
The following commit(s) were added to refs/heads/main by this push:
new 2b968e6e38 AVRO-3951: Document IDE support (#3366)
2b968e6e38 is described below
commit 2b968e6e38744771b555c7124b4744e32ba7dbbb
Author: Oscar Westra van Holthe - Kind <[email protected]>
AuthorDate: Thu May 1 21:34:45 2025 +0200
AVRO-3951: Document IDE support (#3366)
* AVRO-3951: Document IDE support
Move the IDL plugins to a separate page, and also document IDE/editor
extensions that work with other Avro related files.
* Update doc/content/en/docs/++version++/Editor Support/_index.md
Co-authored-by: Martin Grigorov <[email protected]>
---------
Co-authored-by: Martin Grigorov <[email protected]>
---
.../en/docs/++version++/Editor Support/_index.md | 175 +++++++++++++++++++++
.../Editor Support/eclipseAvroclipse.png | Bin 0 -> 6419 bytes
.../jetbrainsAvroAndParquetViewer.svg | 6 +
.../jetbrainsAvroIdlSchemaSupport.svg | 21 +++
.../Editor Support/jetbrainsBigDataFileViewer.svg | 13 ++
.../Editor Support/visualStudioAvroIdl.png | Bin 0 -> 29293 bytes
.../Editor Support/visualStudioAvroTools.png | Bin 0 -> 7092 bytes
.../Editor Support/visualStudioAvroViewer.png | Bin 0 -> 113909 bytes
.../en/docs/++version++/IDL Language/_index.md | 57 -------
share/editors/README.txt | 5 +
10 files changed, 220 insertions(+), 57 deletions(-)
diff --git a/doc/content/en/docs/++version++/Editor Support/_index.md
b/doc/content/en/docs/++version++/Editor Support/_index.md
new file mode 100644
index 0000000000..7296027923
--- /dev/null
+++ b/doc/content/en/docs/++version++/Editor Support/_index.md
@@ -0,0 +1,175 @@
+---
+title: "Editor Support"
+linkTitle: "Editor Support"
+weight: 209
+---
+
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ https://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+
+## Overview
+
+When editing an Avro schema, everyone has a preferred editor. Some use an IDE,
like IntelliJ, PyCharm, RustRover or
+Visual Studio, while others prefer a more humble text editor like Atom/Pulsar,
Emacs or Vim.
+
+Most provide help when working with Avro via JSON support (for JSON schemata)
by offering syntax highlighting and
+formatting. Some provide more help, for example syntax highlighting for IDL
schemata, code completion, error
+highlighting and more.
+
+The IDEs and editors that we know to support Avro better than just editing
schemata as JSON files are listed below in
+alphabetical order.
+
+## Eclipse
+
+Eclipse is a free IDE that provides extensions via the [Eclipse
Marketplace](https://marketplace.eclipse.org/).
+
+### Avroclipse
+
+<img style="float: right; object-fit: contain; width: 160px; height: 160px;"
src="eclipseAvroclipse.png"/>[Extension](https://marketplace.eclipse.org/content/avroclipse)
([source](https://github.com/dvdkruk/avroclipse))
+
+Released in 2015, this plugin received its last update in December 2019.
+
+Features for IDL files:
+
+* Syntax Highlighting
+* Code Completion
+* Error Highlighting
+
+## Emacs
+
+Sometimes ridiculed as an operating system, Emacs is a rich text editor. Many
packages are available
+via one of the three main package archives: [GNU ELPA](https://elpa.gnu.org/),
[non-GNU ELPA](https://elpa.nongnu.org/)
+or [MELPA](https://melpa.org/).
+
+### emacs-avro
+
+[Package source](https://github.com/logc/emacs-avro)
+
+Originally released elsewhere in 2013, the last update was in March 2021.
+
+This package is not available via the main package archives.
+
+Provides syntax highlighting for IDL schemata.
+
+## JetBrains IDE family
+
+JetBrains features an entire line of IDEs. They include IntelliJ IDEA,
PyCharm, PhpStorm, GoLand, Rider, CLion,
+RustRover, WebStorm, RubyMine,
+DataGrip, DataSpell, ReSharper, Fleet, and Aqua.
+
+All of them use the [Plugin Marketplace](https://plugins.jetbrains.com/) to
load extensions from.
+
+### Apache Avro IDL Schema Support
+
+<img style="float: right; object-fit: contain; width: 160px; height: 160px;"
src="jetbrainsAvroIdlSchemaSupport.svg"/>[Plugin](https://plugins.jetbrains.com/plugin/15728-apache-avro-idl-schema-support)
([source](https://github.com/opwvhk/avro-schema-support?tab=readme-ov-file#intellij-plugin-for-apache-avro-idl))
+
+Released in 2021, this plugin received its last update in November 2023.
+
+Features for Avro schema & protocol definitions:
+
+* Syntax Highlighting
+* Code Completion
+* Code Formatting
+* Error Highlighting
+* Inspections & quick fixes (IDL only)
+* New file templates
+
+The plugin supports all JetBrains products.
+
+### Avro and Parquet Viewer
+
+<img style="float: right; object-fit: contain; width: 160px; height: 160px;"
src="jetbrainsAvroAndParquetViewer.svg"/>[Plugin](https://plugins.jetbrains.com/plugin/12281-avro-and-parquet-viewer)
([source](https://github.com/benwatson528/intellij-avro-parquet-plugin))]
+
+Released in 2021, this plugin received its last update in November 2022.
+
+Allows previewing `.avro` files, and shows its schema in an editor tab.
+
+### Big Data File Viewer
+
+<img style="float: right; object-fit: contain; width: 160px; height: 160px;"
src="jetbrainsBigDataFileViewer.svg"/>[Plugin](https://plugins.jetbrains.com/plugin/21701-big-data-file-viewer)
(
+part of the [Big Data
Tools](https://plugins.jetbrains.com/bundles/8-big-data-tools))
+
+Released in 2023, this plugin is actively developed by JetBrains.
+
+Allows previewing `.avro` files, and shows its schema in the structure tool
window.
+
+## Pulsar/Atom
+
+Though the Atom.io editor has been sunset late 2022, the public fork
[Pulsar](https://pulsar-edit.dev/) has taken its
+place. Extensions can be found in its [Package
Repository](https://web.pulsar-edit.dev/).
+
+### atom-language-avro
+
+[Package](https://web.pulsar-edit.dev/packages/atom-language-avro)
([source](https://github.com/jonesetc/atom-language-avro))
+
+Released in 2015, this package provides syntax highlighting for IDL schemata.
+
+## Vim
+
+### vim-avro
+
+[Plugin
source](https://github.com/gurpreetatwal/vim-avro?tab=readme-ov-file#vim-avro)
+
+Released in December 2016, this plugin has received no updates since.
+
+Features syntax highlighting for IDL schemata,
+
+### avro-idl.vim
+
+[Plugin
source](https://github.com/apache/avro/blob/main/share/editors/avro-idl.vim)
+
+Featured in the Avro repository `share/editors` directory. Introduced in 2010,
this plugin received its last update in
+June 2019.
+
+Features syntax highlighting for IDL schemata,
+
+## Visual Studio Code:
+
+Being a Microsoft product, Visual Studio Code provides extensions via
+a [Plugin Marketplace](https://marketplace.visualstudio.com/).
+
+### avro-idl
+
+<img style="float: right; object-fit: contain; width: 160px; height: 160px;"
src="visualStudioAvroIdl.png"/>[Plugin](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.avro)
([source](https://github.com/streetsidesoftware/vscode-avro-ext?tab=readme-ov-file#avro-syntax-highlighter))
+
+Released in 2017, this plugin received its last update in June 2021,
+
+It provides syntax highlighting for IDL and JSON schemata.
+
+### avro-tools
+
+<img style="float: right; object-fit: contain; width: 160px; height: 160px;"
src="visualStudioAvroTools.png"/>[Plugin](https://marketplace.visualstudio.com/items?itemName=tomaszbartoszewski.avro-tools)
([source](https://github.com/tomaszbartoszewski/vscode-avro-tools?tab=readme-ov-file#avro-tools))
+
+Released in 2020, this plugin has not received updates after its release day.
+
+It does provide more features than most plugins:
+
+* syntax highlighting for `.avsc` files
+* formatting
+* snippets for fields with types.
+
+### avro-viewer
+
+<img style="float: right; object-fit: contain; width: 160px; height: 160px;"
src="visualStudioAvroViewer.png"/>[Plugin](https://marketplace.visualstudio.com/items?itemName=yasunari89.avro-viewer)
([source](https://github.com/yasunari89/avro-viewer?tab=readme-ov-file#avro-viewer-readme))
+
+Released in 2023, this plugin received its last update in June 2023.
+
+It allows you to preview `.avro` files (uncompressed only), with its schema.
diff --git a/doc/content/en/docs/++version++/Editor
Support/eclipseAvroclipse.png b/doc/content/en/docs/++version++/Editor
Support/eclipseAvroclipse.png
new file mode 100644
index 0000000000..1c52d56d22
Binary files /dev/null and b/doc/content/en/docs/++version++/Editor
Support/eclipseAvroclipse.png differ
diff --git a/doc/content/en/docs/++version++/Editor
Support/jetbrainsAvroAndParquetViewer.svg
b/doc/content/en/docs/++version++/Editor
Support/jetbrainsAvroAndParquetViewer.svg
new file mode 100644
index 0000000000..8683ac6a64
--- /dev/null
+++ b/doc/content/en/docs/++version++/Editor
Support/jetbrainsAvroAndParquetViewer.svg
@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="utf-8"?>
+<svg width="40px" height="40px" viewBox="0 0 24 24" fill="none"
xmlns="http://www.w3.org/2000/svg";>
+ <path d="M15.75 13C15.75 12.5858 15.4142 12.25 15 12.25H9C8.58579 12.25 8.25
12.5858 8.25 13C8.25 13.4142 8.58579 13.75 9 13.75H15C15.4142 13.75 15.75
13.4142 15.75 13Z" style="fill: rgb(110, 110, 110);"/>
+ <path d="M15.75 17C15.75 16.5858 15.4142 16.25 15 16.25H9C8.58579 16.25 8.25
16.5858 8.25 17C8.25 17.4142 8.58579 17.75 9 17.75H15C15.4142 17.75 15.75
17.4142 15.75 17Z" style="fill: rgb(110, 110, 110);"/>
+ <path fill-rule="evenodd" clip-rule="evenodd" d="M7 2.25C5.48122 2.25 4.25
3.48122 4.25 5V19C4.25 20.5188 5.48122 21.75 7 21.75H17C18.5188 21.75 19.75
20.5188 19.75 19V7.96766C19.75 7.58689 19.6258 7.21651 19.3963 6.9127L16.3985
2.94504C16.0677 2.5073 15.5509 2.25 15.0022 2.25H7ZM5.75 5C5.75 4.30964 6.30964
3.75 7 3.75H14.25V8.14705C14.25 8.56126 14.5858 8.89705 15
8.89705H18.25V19C18.25 19.6904 17.6904 20.25 17 20.25H7C6.30964 20.25 5.75
19.6904 5.75 19V5Z" style="fill: rgb(110, 110, [...]
+</svg>
diff --git a/doc/content/en/docs/++version++/Editor
Support/jetbrainsAvroIdlSchemaSupport.svg
b/doc/content/en/docs/++version++/Editor
Support/jetbrainsAvroIdlSchemaSupport.svg
new file mode 100644
index 0000000000..9aff5371a6
--- /dev/null
+++ b/doc/content/en/docs/++version++/Editor
Support/jetbrainsAvroIdlSchemaSupport.svg
@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg xmlns="http://www.w3.org/2000/svg"; version="1.1" width="40" height="40"
viewBox="0 0 64 64">
+ <!--<rect fill="#f7f8fa" x="0" y="0" width="64" height="64"/>-->
+ <!-- Pigeon v3.1, 64x64, 4px border -->
+ <path id="body" fill="#999999" d="M 31.840348,14.449415
25.321254,56.989232 50.422312,37.398761 Z m 0,0" style="stroke-width:1.27326" />
+ <path id="body-outline" fill="none" stroke="#3b3b3b" d="M
31.835904,14.449415 25.316288,56.989232 50.41797,37.398761 Z m 0,0"
stroke-width="1.77778" stroke-linecap="square" stroke-linejoin="round" />
+ <path id="tail" fill="#666666" d="m 27.279529,44.222194
-16.55748,-0.497847 14.597932,13.061162 z m 0,0" style="stroke-width:1.27326" />
+ <path id="tail-outline" fill="none" stroke="#3b3b3b" d="M
27.270173,44.232672 10.72253,43.729145 25.312626,56.939324 Z m 0,0"
stroke-width="1.78737" stroke-linecap="square" stroke-linejoin="round" />
+ <path id="wing-light" fill="#cccccc" d="M 31,15 L 6,8 L 28,34 Z"
style="stroke-width:1.27326"/>
+ <path id="wing-dark-3" fill="none" stroke="#666666" d="M
22.242179,12.34598 20.263138,24.710666" stroke-width="1.77778"
stroke-linecap="square" stroke-linejoin="round" />
+ <path id="wing-dark-2" fill="none" stroke="#666666" d="m
18.57664,11.166935 -1.491904,9.429808" stroke-width="1.77778"
stroke-linecap="square" stroke-linejoin="round" />
+ <path id="wing-dark-1a" fill="#666666" d="M 8.9764091,10.555768 C
8.1411502,9.5358815 7.3402693,8.4561519 7.3606415,8.4357797 7.4001126,8.3963084
11.05055,9.3958222 11.130766,9.476038 c 0.04966,0.044564 -0.422723,3.018914
-0.408717,3.113135 0.03947,0.224095 -0.9103811,-1.014793 -1.7456399,-2.033405 z
m 0,0" style="stroke-width:1.27326" />
+ <path id="wing-dark-1b" fill="none" stroke="#666666" d="m
12.026492,9.4111014 -0.59269,3.9343916" stroke-width="1.77778"
stroke-linecap="square" stroke-linejoin="round" />
+ <path id="wing-outline" fill="none" stroke="#3b3b3b" d="M
28.563383,35.697678 31.825731,14.430316 4.8887463,6.809819 Z m 0,0"
stroke-width="1.77778" stroke-linecap="square" stroke-linejoin="round" />
+ <path id="neck-purple" fill="#8b72b9" d="m 39.430254,22.203605
1.860233,-1.776206 8.683637,10.216686 0.159157,4.630869"
style="stroke-width:1.27326" />
+ <path id="neck-green" fill="#1cac81" d="m 41.64318,20.831024 c
-0.0051,-0.02547 2.86993,-2.840656 4.506069,-4.307459 l 3.169146,-2.849569
0.07894,0.770326 c 0.203722,2.024493 0.516944,16.737082 0.516944,16.737082 C
49.63671,30.952216 41.64318,20.831024 41.64318,20.831024 Z m 0,0"
style="stroke-width:1.27326" />
+ <path id="neck-outline" fill="none" stroke="#3b3b3b" d="m
38.754891,22.362763 11.264981,-10.489165 0.358665,18.068918 0.138632,7.281808 z
m 0,0" stroke-width="1.77778" stroke-linecap="square" stroke-linejoin="round" />
+ <path id="head-green" fill="#1cac81" d="m 50.74572,18.647373 c
0,-1.129387 -0.06494,-2.894134 -0.03056,-3.540953 l 0.08531,-1.666705
2.084327,1.103922 2.173456,1.473168 -0.369245,1.774933 -0.227914,1.920085
-1.432418,0.516946 -2.277863,0.890013 z m 0,0" style="stroke-width:1.27326" />
+ <path id="beak" fill="none" stroke="#ffd944" d="m
56.395775,19.080283 -1.278239,-3.024006 0.075,3.511667 2.014642,-1.398046"
stroke-width="1.92921" stroke-linecap="square" stroke-linejoin="round" />
+ <path id="head-outline" fill="none" stroke="#3b3b3b" d="m
50.019872,11.868505 0.198412,10.095726 8.892935,-3.759955 z m 0,0"
stroke-width="1.77778" stroke-linecap="square" stroke-linejoin="round" />
+</svg>
diff --git a/doc/content/en/docs/++version++/Editor
Support/jetbrainsBigDataFileViewer.svg b/doc/content/en/docs/++version++/Editor
Support/jetbrainsBigDataFileViewer.svg
new file mode 100644
index 0000000000..675b3e7be8
--- /dev/null
+++ b/doc/content/en/docs/++version++/Editor
Support/jetbrainsBigDataFileViewer.svg
@@ -0,0 +1,13 @@
+<svg width="40" height="40" viewBox="0 0 40 40" fill="none"
xmlns="http://www.w3.org/2000/svg";>
+ <path fill-rule="evenodd" clip-rule="evenodd" d="M7 26H0V40H6.99934H7C10.85
40 14 36.85 14 33C14 29.15 10.85 26 7 26"
+ fill="url(#paint0_linear_3419_204)"/>
+ <path fill-rule="evenodd" clip-rule="evenodd"
+ d="M7 5C4.79086 5 3 6.79086 3 9V24H6V15H13V26.3029C14.8393 27.9531 16
30.3461 16 33C16 33.6869 15.9222 34.3564 15.7751 35H33C35.2091 35 37 33.2091 37
31V9C37 6.79086 35.2091 5 33 5H7ZM24 8H16V12H24V8ZM13 8V12H6V9C6 8.44772
6.44772 8 7 8H13ZM24 15H16V32H24V15ZM27 32V15H34V31C34 31.5523 33.5523 32 33
32H27ZM34 9V12H27V8H33C33.5523 8 34 8.44772 34 9Z"
+ fill="#6C707E"/>
+ <defs>
+ <linearGradient id="paint0_linear_3419_204" x1="-6.79883" y1="27.9631"
x2="1.0516" y2="39.8599" gradientUnits="userSpaceOnUse">
+ <stop stop-color="#FF45ED"/>
+ <stop offset="1" stop-color="#6B57FF"/>
+ </linearGradient>
+ </defs>
+</svg>
diff --git a/doc/content/en/docs/++version++/Editor
Support/visualStudioAvroIdl.png b/doc/content/en/docs/++version++/Editor
Support/visualStudioAvroIdl.png
new file mode 100644
index 0000000000..3525834e21
Binary files /dev/null and b/doc/content/en/docs/++version++/Editor
Support/visualStudioAvroIdl.png differ
diff --git a/doc/content/en/docs/++version++/Editor
Support/visualStudioAvroTools.png b/doc/content/en/docs/++version++/Editor
Support/visualStudioAvroTools.png
new file mode 100644
index 0000000000..ebe675d7ec
Binary files /dev/null and b/doc/content/en/docs/++version++/Editor
Support/visualStudioAvroTools.png differ
diff --git a/doc/content/en/docs/++version++/Editor
Support/visualStudioAvroViewer.png b/doc/content/en/docs/++version++/Editor
Support/visualStudioAvroViewer.png
new file mode 100644
index 0000000000..0c06035f11
Binary files /dev/null and b/doc/content/en/docs/++version++/Editor
Support/visualStudioAvroViewer.png differ
diff --git a/doc/content/en/docs/++version++/IDL Language/_index.md
b/doc/content/en/docs/++version++/IDL Language/_index.md
index 920d12d4d9..448035e5fe 100644
--- a/doc/content/en/docs/++version++/IDL Language/_index.md
+++ b/doc/content/en/docs/++version++/IDL Language/_index.md
@@ -454,60 +454,3 @@ protocol Simple {
```
Additional examples may be found in the Avro source tree under the
`src/test/idl/input` directory.
-
-## IDE support
-
-There are several editors and IDEs that support Avro IDL files, usually via
plugins.
-
-### JetBrains
-
-Apache Avro IDL Schema Support 203.1.2 was released in 9 December 2021.
-
-Features:
-* Syntax Highlighting
-* Code Completion
-* Code Formatting
-* Error Highlighting
-* Inspections & quick fixes
-* JSON schemas for .avpr and .avsc files
-
-It's available via the [JetBrains
Marketplace](https://plugins.jetbrains.com/plugin/15728-apache-avro-idl-schema-support)
-and on [GitHub](https://github.com/opwvhk/avro-schema-support).
-
-The plugin supports almost the all JetBrains products: IntelliJ IDEA, PyCharm,
WebStorm, Android Studio, AppCode, GoLand, Rider, CLion, RubyMine, PhpStorm,
DataGrip, DataSpell, MPS, Code With Me Guest and JetBrains Client.
-
-Only JetBrains Gateway does not support this plugin directly. But the backend
(JetBrains) IDE that it connects to does.
-
-### Eclipse
-
-Avroclipse 0.0.11 was released on 4 December 2019.
-
-Features:
-* Syntax Highlighting
-* Error Highlighting
-* Code Completion
-
-It is available on the [Eclipse
Marketplace](https://marketplace.eclipse.org/content/avroclipse)
-and [GitHub](https://github.com/dvdkruk/avroclipse).
-
-### Visual Studio Code
-
-avro-idl 0.5.0 was released on 16 June 2021. It provides syntax highlighting.
-
-It is available on the [VisualStudio
Marketplace](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.avro)
-and [GitHub](https://github.com/Jason3S/vscode-avro-ext)
-
-### Atom.io
-
-atom-language-avro 0.0.13 was released on 14 August 2015. It provides syntax
highlighting.
-
-It is available as [Atom.io
package](https://atom.io/packages/atom-language-avro)
-and [GitHub](https://github.com/jonesetc/atom-language-avro)
-
-### Vim
-
-A `.avdl` detecting plugin by Gurpreet Atwal on
[GitHub](https://github.com/gurpreetatwal/vim-avro) (Last change in December
2016)
-
-[avro-idl.vim](https://github.com/apache/avro/blob/main/share/editors/avro-idl.vim)
in the Avro repository `share/editors` directory (last change in September
2010)
-
-Both provide syntax highlighting.
diff --git a/share/editors/README.txt b/share/editors/README.txt
index 70dd312569..e3da24377f 100644
--- a/share/editors/README.txt
+++ b/share/editors/README.txt
@@ -1 +1,6 @@
Syntax highlighting and config files for working with Avro files in various
text editors.
+
+Some, like Microsoft Visual Studio and the various JetBrains IDEs, have their
own plugin
+marketplace to offer/provide plugins to handle Avro files.
+
+Full information is available in the documentation:
https://avro.apache.org/docs/current/editor-support/
