From 4e802980f25ca0c23e63c8f8c05b07ec6d373b27 Mon Sep 17 00:00:00 2001 From: Jakub Chrzanowski Date: Thu, 14 Jan 2021 16:07:39 +0100 Subject: [PATCH] Webhelp migration (#347) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * [webhelp] Fixes for TXP00152, TXP00002, test build 27 Jul 22:26 * [webhelp] Fixes for Part #4 TXP00010, EXCEPT decimal numbers in section titles * [webhelp] Fixes for Part #5 TXP00017 * [webhelp] Fixes for Part #4 TXP00010 - removed numbers from page section titles in "Custom Language Support Tutorial" and "Testing a Custom Language Plugin". * [webhelp] Removed numbers from page section titles in rest of project *.md files. * [new webhelp] Build #44 changes * [new webhelp] Maintenance merge from master * [new webhelp] Add placeholder file for webhelp import. * [webhelp] Correct redirects for file name changes * [webhelp] TOC not needed in webhelp * [format] {:toc} not needed for webhelp * add {:disable-links} to ensure demo links are not interpreted as real links. * Put all badges on the same line to simplify composition. * formatter.md: fix upsource link * fix some links * api_changes_list.md: remove note * migrate to webhelp - initial * fix GH edit URL * remove sdkdocs-template setup in VCS config * remove recently_updated.md * restore COC/CONTRIBUTING.md * api_changes_list.md: remove note * useful_links.md: IPE Co-authored-by: JohnHake Co-authored-by: Yann Cébron --- .github/workflows/build-test.yml | 29 +- .gitmodules | 3 - .idea/vcs.xml | 3 +- CONTRIBUTING.md | 7 +- Dockerfile | 35 -- Gemfile | 1 - Gemfile.lock | 106 ------ Rakefile | 24 -- _SUMMARY.md | 292 --------------- _config.yml | 22 -- appendix/glossary.md | 93 ----- basics/plugin_structure.md | 18 - basics/settings.md | 11 - basics/templates.md | 10 - .../messaging}/connection.puml | 0 .../messaging}/nested_config.puml | 0 .../messaging}/parent_child_broadcast.puml | 0 .../img => buildUML/messaging}/publish.puml | 0 .../messaging}/standard_hierarchy.puml | 0 .../img => buildUML/messaging}/subscribe.puml | 0 .../img => buildUML/messaging}/topic.puml | 0 cfg/build-script.xml | 11 + cfg/buildprofiles.xml | 34 ++ cfg/platforms.xml | 14 + config.json | 8 - container_settings.json | 8 - ijs.tree | 354 ++++++++++++++++++ .../deploying_plugin/img/jar_location.png | Bin .../img/jar_saved_notification.png | Bin .../img/prepare_plugin_for_deployment.png | Bin .../getting_started/img/add_sourcepath.png | Bin .../img/community_sources_directory.png | Bin .../img/create_intellij_idea_sdk.png | Bin .../img/intellij_platform_plugin_module.png | Bin .../getting_started/img/new_action_page.png | Bin .../img/new_action_template.png | Bin .../img/new_project_wizard.png | Bin .../getting_started/img/php_prj_libs.png | Bin .../getting_started/img/plugins-sandbox.png | Bin .../getting_started/img/sample_menu.jpg | Bin .../img/set_home_directory.png | Bin .../getting_started/img/set_idea_jdk.png | Bin .../getting_started/img/set_java_sdk.png | Bin .../img/set_plugin_module_sdk.png | Bin .../basics}/img/ant_build_xml.png | Bin .../basics}/img/check_out_community.png | Bin {basics => images/basics}/img/classes.png | Bin .../basics}/img/configure_sdk.png | Bin {basics => images/basics}/img/create-1.png | Bin {basics => images/basics}/img/create-2.png | Bin {basics => images/basics}/img/create-3.png | Bin .../basics}/img/idea_run_configuration.png | Bin {basics => images/basics}/img/tools_jar.png | Bin .../plugin_structure/img/circle_logo.png | Bin .../basics}/plugin_structure/img/dark_bad.png | Bin .../plugin_structure/img/dark_good.png | Bin .../plugin_structure/img/icon_size.png | Bin .../plugin_structure/img/keymap_logo.png | Bin .../plugin_structure/img/light_version.png | Bin .../plugin_structure/img/plugin_prefs.png | Bin .../img/rectangle_horizontal.png | Bin .../img/rectangle_vertical.png | Bin .../img/resource_directory_structure.png | Bin .../plugin_structure/img/square_logo.png | Bin .../basics}/plugin_structure/img/yt_logo.png | Bin .../img/IntelliJIDEA_ProjectStructure.png | Bin images/info | 1 + .../products}/img/android_studio_build.png | Bin .../products}/img/phpstorm_build.png | Bin .../img/PsiBuilder.gif | Bin .../img/xml_dom_api/booleancontrol.gif | Bin .../img/xml_dom_api/collectioncontrol.gif | Bin .../img/xml_dom_api/combocontrol.gif | Bin .../img/xml_dom_api/psiclasscontrol.gif | Bin .../reference_guide}/img/bus.png | Bin .../reference_guide}/img/configurable.png | Bin .../reference_guide}/img/connection.svg | 0 .../img/data-node-example.png | Bin .../reference_guide}/img/data-node.png | Bin .../reference_guide}/img/import.png | Bin .../reference_guide}/img/nested_config.svg | 0 .../img/parent_child_broadcast.svg | 0 .../reference_guide}/img/publish.svg | 0 .../img/standard_hierarchy.svg | 0 .../reference_guide}/img/subscribe.svg | 0 .../img/toolWindowStructure.png | Bin .../img/toolWindowStructure@2x.png | Bin .../img/toolWindowStructure@2x_dark.png | Bin .../img/toolWindowStructure_dark.png | Bin .../reference_guide}/img/topic.png | Bin .../reference_guide}/img/topic.svg | 0 .../img/internal_lafd_win.png | Bin .../img/internal_uii_icon_info.png | Bin .../ui_themes/img/devkit_wiz_action.png | Bin .../ui_themes/img/devkit_wiz_dialog.png | Bin .../ui_themes/img/keys-naming.png | Bin .../img/theme_colorpalette_popup.png | Bin .../ui_themes/img/theme_components.png | Bin .../ui_themes/img/uit_control_complete.png | Bin .../action_system/img/action_never_used.png | Bin .../action_system/img/action_performed.png | Bin .../img/dynamic_action_group.png | Bin .../action_system/img/editor_popup_menu.png | Bin .../action_system/img/find_action.png | Bin .../action_system/img/grouped_action.png | Bin .../action_system/img/new_action.png | Bin .../action_system/img/register_action.png | Bin .../action_system/img/register_group.png | Bin .../img/tools_menu_item_action.png | Bin .../img/gradle_tasks_in_tool_window.png | Bin .../img/step1_new_gradle_project.png | Bin .../custom_language_support/img/annotator.png | Bin .../img/code_style_settings.png | Bin .../img/color_settings_page.png | Bin .../custom_language_support/img/commenter.png | Bin .../img/completion.png | Bin .../img/file_type_factory.png | Bin .../img/find_usages.png | Bin .../custom_language_support/img/folding.png | Bin .../custom_language_support/img/formatter.png | Bin .../img/generated_parser.png | Bin .../img/go_to_symbol.png | Bin .../img/in_place_rename.png | Bin .../img/line_marker.png | Bin .../img/line_marker_location.png | Bin .../img/new_property.png | Bin .../img/psi_elements.png | Bin .../custom_language_support/img/quick_fix.png | Bin .../img/reference_contributor.png | Bin .../custom_language_support/img/rename.png | Bin .../img/structure_view.png | Bin .../img/syntax_highlighter.png | Bin .../img/unresolved_property.png | Bin .../tutorials}/editor_basics/img/basics.png | Bin .../editor_basics/img/caret_col_pos_block.png | Bin .../editor_basics/img/caret_offset_l2.png | Bin .../editor_basics/img/editor_coords.png | Bin .../editor_basics/img/logical_pos_folded.png | Bin .../editor_basics/img/vis_pos_soft_wrap.png | Bin .../framework/img/custom_framework.png | Bin .../tutorials}/img/IntentionsList.png | Bin .../tutorials}/img/TernaryOperator.png | Bin .../tutorials}/img/comparingReferences.png | Bin .../img/comparingReferences_options.png | Bin .../tutorials}/img/settings_defaults.png | Bin .../tutorials}/img/settings_persisted.png | Bin .../live_templates/img/applied_titleCase.png | Bin .../live_templates/img/invoke_titleCase.png | Bin .../project_wizard/img/empty_project.png | Bin .../project_wizard/img/extra_step.png | Bin .../module_types/img/new_module_type.png | Bin .../img/new_run_configuration.png | Bin .../run_configurations/img/ui_form.png | Bin .../tree_structure_view/img/text_only.png | Bin .../img/plugin_copy_psi.png | Bin .../img/sample_calendar.png | Bin intro/content_updates.md | 88 ----- products/idea.md | 11 - project.ihp | 15 + reference_guide/api_changes_list.md | 30 +- .../api_changes_list_2016.md | 10 +- .../api_changes_list_2017.md | 13 +- .../api_changes_list_2018.md | 15 +- .../api_changes_list_2019.md | 17 +- .../api_changes_list_2020.md | 32 +- .../api_changes_list_2021.md | 14 +- reference_guide/custom_language_support.md | 40 -- reference_guide/project_model/build_system.md | 6 - sdkdocs-template | 1 - topics/CODE_OF_CONDUCT.md | 7 + topics/CONTRIBUTING.md | 129 +++++++ topics/appendix/glossary.md | 89 +++++ .../appendix}/plugin_repository_obsolete.md | 22 +- .../appendix}/resources/consulting.md | 11 +- .../resources/extension_point_list.md | 37 +- .../appendix}/resources/marketing.md | 19 +- .../appendix}/resources/useful_links.md | 16 +- {basics => topics/basics}/analyzing.md | 9 +- .../architectural_overview/documents.md | 11 +- .../file_view_providers.md | 7 +- .../basics}/architectural_overview/files.md | 9 +- .../general_threading_rules.md | 19 +- .../architectural_overview/modifying_psi.md | 10 +- .../architectural_overview/navigating_psi.md | 8 +- .../basics}/architectural_overview/psi.md | 15 +- .../architectural_overview/psi_elements.md | 7 +- .../architectural_overview/psi_files.md | 9 +- .../architectural_overview/psi_references.md | 15 +- .../architectural_overview/virtual_file.md | 19 +- .../basics/basic_action_system.md | 44 ++- .../basics/basic_run_configurations.md | 13 +- {basics => topics/basics}/basics.md | 11 +- {basics => topics/basics}/disposers.md | 37 +- {basics => topics/basics}/editing.md | 9 +- {basics => topics/basics}/faq.md | 13 +- {basics => topics/basics}/getting_started.md | 33 +- .../getting_started/build_number_ranges.md | 29 +- .../creating_plugin_project.md | 19 +- .../getting_started/deploying_plugin.md | 13 +- .../getting_started/plugin_compatibility.md | 50 +-- .../getting_started/publishing_plugin.md | 13 +- .../running_and_debugging_a_plugin.md | 9 +- .../getting_started/setting_up_environment.md | 27 +- .../getting_started/update_plugins_format.md | 15 +- .../basics}/getting_started/using_dev_kit.md | 13 +- .../basics}/ide_development_instance.md | 29 +- .../basics}/indexing_and_psi_stubs.md | 15 +- .../file_based_indexes.md | 23 +- .../indexing_and_psi_stubs/stub_indexes.md | 15 +- .../basics}/intellij_coding_guidelines.md | 7 +- {basics => topics/basics}/persistence.md | 11 +- .../basics}/persisting_sensitive_data.md | 7 +- .../basics}/persisting_state_of_components.md | 23 +- .../basics}/platform_contributions.md | 11 +- topics/basics/plugin_structure.md | 17 + .../plugin_structure/dynamic_plugins.md | 19 +- .../plugin_structure/plugin_actions.md | 7 +- .../plugin_structure/plugin_class_loaders.md | 7 +- .../plugin_structure/plugin_components.md | 15 +- .../plugin_configuration_file.md | 11 +- .../plugin_structure/plugin_content.md | 9 +- .../plugin_structure/plugin_dependencies.md | 58 +-- .../plugin_extension_points.md | 17 +- .../plugin_structure/plugin_extensions.md | 24 +- .../plugin_structure/plugin_icon_file.md | 35 +- .../plugin_structure/plugin_listeners.md | 17 +- .../plugin_structure/plugin_services.md | 25 +- .../basics}/project_structure.md | 22 +- {basics => topics/basics}/project_view.md | 7 +- {basics => topics/basics}/psi_cookbook.md | 13 +- .../run_configuration_execution.md | 7 +- .../run_configuration_management.md | 16 +- topics/basics/settings.md | 10 + topics/basics/templates.md | 9 + .../testing_plugins/light_and_heavy_tests.md | 24 +- .../test_project_and_testdata_directories.md | 25 +- .../testing_plugins/testing_highlighting.md | 9 +- .../testing_plugins/testing_plugins.md | 9 +- .../testing_plugins/tests_and_fixtures.md | 7 +- .../basics}/testing_plugins/writing_tests.md | 7 +- {basics => topics/basics}/types_of_plugins.md | 11 +- .../basics}/virtual_file_system.md | 21 +- topics/info | 1 + ...ellij-sdk-docs-original_CODE_OF_CONDUCT.md | 8 + ...intellij-sdk-docs-original_CONTRIBUTING.md | 150 ++++++++ {intro => topics/intro}/about.md | 33 +- topics/intro/content_updates.md | 86 +++++ {intro => topics/intro}/getting_help.md | 11 +- {intro => topics/intro}/intellij_platform.md | 16 +- {intro => topics/intro}/key_topics.md | 23 +- .../intro}/sdk_code_guidelines.md | 32 +- {intro => topics/intro}/sdk_style.md | 122 ++---- {intro => topics/intro}/welcome.md | 30 +- {platform => topics/platform}/fundamentals.md | 14 +- .../products}/android_studio.md | 24 +- {products => topics/products}/app_code.md | 27 +- {products => topics/products}/clion.md | 19 +- {products => topics/products}/data_grip.md | 29 +- .../products}/dev_alternate_products.md | 40 +- {products => topics/products}/goland.md | 21 +- topics/products/idea.md | 12 + .../products}/phpstorm/existing_plugins.md | 9 +- .../products}/phpstorm/php_open_api.md | 9 +- .../phpstorm/php_open_api_breaking_changes.md | 5 +- .../php_open_api_breaking_changes_202.md | 7 +- .../php_open_api_breaking_changes_203.md | 5 +- .../products}/phpstorm/phpstorm.md | 23 +- {products => topics/products}/pycharm.md | 11 +- {products => topics/products}/rider.md | 15 +- {products => topics/products}/rubymine.md | 21 +- {products => topics/products}/webstorm.md | 25 +- topics/recently_updated.md | 5 + .../api_notable/api_notable.md | 11 +- .../api_notable/api_notable_list_2018.md | 7 +- .../api_notable/api_notable_list_2019.md | 19 +- .../api_notable/api_notable_list_2020.md | 23 +- .../api_notable/api_notable_list_2021.md | 7 +- .../color_scheme_management.md | 11 +- .../custom_language_support.md | 39 ++ .../additional_minor_features.md | 22 +- .../code_completion.md | 18 +- .../code_formatting.md | 11 +- .../code_inspections_and_intentions.md | 12 +- .../declarations_and_references.md | 15 +- .../custom_language_support/documentation.md | 7 +- .../custom_language_support/find_usages.md | 11 +- .../go_to_class_and_go_to_symbol.md | 13 +- .../implementing_lexer.md | 13 +- .../implementing_parser_and_psi.md | 15 +- .../custom_language_support/navigation.md | 13 +- .../references_and_resolve.md | 28 +- .../registering_file_type.md | 13 +- .../rename_refactoring.md | 10 +- .../safe_delete_refactoring.md | 8 +- .../custom_language_support/structure_view.md | 10 +- .../custom_language_support/surround_with.md | 7 +- .../custom_language_support/symbols.md | 12 +- ...tax_highlighting_and_error_highlighting.md | 23 +- .../reference_guide}/editors.md | 9 +- .../external_builder_api.md | 16 +- .../external_system_integration.md | 28 +- .../spring_api.md | 33 +- .../xml_dom_api.md | 33 +- .../reference_guide}/intellij_artifacts.md | 13 +- .../internal_actions/enabling_internal.md | 7 +- .../internal_actions/interal_actions_menu.md | 11 + .../internal_actions_intro.md | 13 +- .../internal_actions/internal_ui_inspector.md | 23 +- .../internal_ui_laf_defaults.md | 11 +- .../internal_actions/internal_ui_sub.md | 11 +- .../reference_guide}/jcef.md | 18 +- .../reference_guide}/localization_guide.md | 11 +- .../messaging_infrastructure.md | 28 +- .../reference_guide}/multiple_carets.md | 11 +- .../performance/performance.md | 17 +- .../project_model/build_system.md | 5 + .../reference_guide}/project_model/facet.md | 7 +- .../reference_guide}/project_model/library.md | 14 +- .../reference_guide}/project_model/module.md | 17 +- .../reference_guide}/project_model/project.md | 13 +- .../reference_guide}/project_model/sdk.md | 9 +- .../reference_guide}/project_wizard.md | 13 +- .../reference_guide}/settings_groups.md | 21 +- .../reference_guide}/settings_guide.md | 36 +- .../reference_guide}/tomcat_integration.md | 7 +- .../reference_guide}/ui_themes/themes.md | 28 +- .../ui_themes/themes_customize.md | 33 +- .../ui_themes/themes_extras.md | 13 +- .../ui_themes/themes_intro.md | 13 +- .../ui_themes/themes_metadata.md | 42 +-- .../vcs_integration_for_plugins.md | 11 +- .../work_with_icons_and_images.md | 40 +- .../tutorials}/action_system.md | 12 +- .../action_system/grouping_action.md | 28 +- .../working_with_custom_actions.md | 44 +-- .../tutorials}/build_system/deployment.md | 27 +- .../tutorials}/build_system/gradle_guide.md | 60 +-- .../build_system/gradle_prerequisites.md | 51 ++- .../tutorials}/code_inspections.md | 18 +- .../tutorials}/code_intentions.md | 17 +- .../custom_language_support/annotator.md | 34 +- .../code_style_settings.md | 30 +- .../custom_language_support/commenter.md | 20 +- .../completion_contributor.md | 22 +- .../find_usages_provider.md | 20 +- .../folding_builder.md | 24 +- .../custom_language_support/formatter.md | 24 +- .../go_to_symbol_contributor.md | 24 +- .../grammar_and_parser.md | 28 +- .../language_and_filetype.md | 40 +- .../lexer_and_parser_definition.md | 42 +-- .../line_marker_provider.md | 26 +- .../custom_language_support/prerequisites.md | 19 +- .../psi_helper_and_utilities.md | 18 +- .../custom_language_support/quick_fix.md | 34 +- .../reference_contributor.md | 52 ++- .../structure_view_factory.md | 28 +- ...tax_highlighter_and_color_settings_page.md | 38 +- .../custom_language_support_tutorial.md | 32 ++ .../tutorials}/editor_basics.md | 17 +- .../editor_basics/coordinates_system.md | 34 +- .../tutorials}/editor_basics/editor_events.md | 17 +- .../editor_basics/working_with_text.md | 28 +- {tutorials => topics/tutorials}/framework.md | 15 +- .../tutorials}/github_template.md | 9 +- topics/tutorials/gradle_build_system.md | 32 ++ .../tutorials/intro_project_wizard.md | 11 +- {tutorials => topics/tutorials}/kotlin.md | 35 +- .../tutorials}/live_templates.md | 11 +- .../tutorials}/live_templates/new_macros.md | 14 +- .../live_templates/template_support.md | 22 +- .../project_wizard/adding_new_steps.md | 24 +- .../tutorials}/project_wizard/module_types.md | 29 +- .../tutorials}/run_configurations.md | 27 +- .../tutorials}/settings_tutorial.md | 42 +-- .../tutorials}/tree_structure_view.md | 24 +- topics/tutorials/writing_tests_for_plugins.md | 24 ++ .../annotator_test.md | 17 +- .../commenter_test.md | 13 +- .../completion_test.md | 19 +- .../find_usages_test.md | 19 +- .../writing_tests_for_plugins/folding_test.md | 21 +- .../formatter_test.md | 17 +- .../writing_tests_for_plugins/parsing_test.md | 29 +- .../reference_test.md | 17 +- .../writing_tests_for_plugins/rename_test.md | 25 +- .../tests_prerequisites.md | 11 +- .../dialog_wrapper.md | 11 +- .../editor_components.md | 7 +- .../file_and_class_choosers.md | 7 +- .../kotlin_ui_dsl.md | 20 +- .../lists_and_trees.md | 7 +- .../misc_swing_components.md | 7 +- .../notifications.md | 11 +- .../user_interface_components}/popups.md | 11 +- .../tool_windows.md | 11 +- .../user_interface_components.md | 34 ++ tutorials/build_system.md | 25 -- tutorials/custom_language_support_tutorial.md | 31 -- tutorials/writing_tests_for_plugins.md | 23 -- .../user_interface_components.md | 31 -- 401 files changed, 3122 insertions(+), 3146 deletions(-) delete mode 100644 .gitmodules delete mode 100644 Dockerfile delete mode 100644 Gemfile delete mode 100644 Gemfile.lock delete mode 100644 Rakefile delete mode 100644 _SUMMARY.md delete mode 100644 _config.yml delete mode 100644 appendix/glossary.md delete mode 100644 basics/plugin_structure.md delete mode 100644 basics/settings.md delete mode 100644 basics/templates.md rename {reference_guide/img => buildUML/messaging}/connection.puml (100%) rename {reference_guide/img => buildUML/messaging}/nested_config.puml (100%) rename {reference_guide/img => buildUML/messaging}/parent_child_broadcast.puml (100%) rename {reference_guide/img => buildUML/messaging}/publish.puml (100%) rename {reference_guide/img => buildUML/messaging}/standard_hierarchy.puml (100%) rename {reference_guide/img => buildUML/messaging}/subscribe.puml (100%) rename {reference_guide/img => buildUML/messaging}/topic.puml (100%) create mode 100644 cfg/build-script.xml create mode 100644 cfg/buildprofiles.xml create mode 100644 cfg/platforms.xml delete mode 100644 config.json delete mode 100644 container_settings.json create mode 100644 ijs.tree rename {basics => images/basics}/getting_started/deploying_plugin/img/jar_location.png (100%) rename {basics => images/basics}/getting_started/deploying_plugin/img/jar_saved_notification.png (100%) rename {basics => images/basics}/getting_started/deploying_plugin/img/prepare_plugin_for_deployment.png (100%) rename {basics => images/basics}/getting_started/img/add_sourcepath.png (100%) rename {basics => images/basics}/getting_started/img/community_sources_directory.png (100%) rename {basics => images/basics}/getting_started/img/create_intellij_idea_sdk.png (100%) rename {basics => images/basics}/getting_started/img/intellij_platform_plugin_module.png (100%) rename {basics => images/basics}/getting_started/img/new_action_page.png (100%) rename {basics => images/basics}/getting_started/img/new_action_template.png (100%) rename {basics => images/basics}/getting_started/img/new_project_wizard.png (100%) rename {basics => images/basics}/getting_started/img/php_prj_libs.png (100%) rename {basics => images/basics}/getting_started/img/plugins-sandbox.png (100%) rename {basics => images/basics}/getting_started/img/sample_menu.jpg (100%) rename {basics => images/basics}/getting_started/img/set_home_directory.png (100%) rename {basics => images/basics}/getting_started/img/set_idea_jdk.png (100%) rename {basics => images/basics}/getting_started/img/set_java_sdk.png (100%) rename {basics => images/basics}/getting_started/img/set_plugin_module_sdk.png (100%) rename {basics => images/basics}/img/ant_build_xml.png (100%) rename {basics => images/basics}/img/check_out_community.png (100%) rename {basics => images/basics}/img/classes.png (100%) rename {basics => images/basics}/img/configure_sdk.png (100%) rename {basics => images/basics}/img/create-1.png (100%) rename {basics => images/basics}/img/create-2.png (100%) rename {basics => images/basics}/img/create-3.png (100%) rename {basics => images/basics}/img/idea_run_configuration.png (100%) rename {basics => images/basics}/img/tools_jar.png (100%) rename {basics => images/basics}/plugin_structure/img/circle_logo.png (100%) rename {basics => images/basics}/plugin_structure/img/dark_bad.png (100%) rename {basics => images/basics}/plugin_structure/img/dark_good.png (100%) rename {basics => images/basics}/plugin_structure/img/icon_size.png (100%) rename {basics => images/basics}/plugin_structure/img/keymap_logo.png (100%) rename {basics => images/basics}/plugin_structure/img/light_version.png (100%) rename {basics => images/basics}/plugin_structure/img/plugin_prefs.png (100%) rename {basics => images/basics}/plugin_structure/img/rectangle_horizontal.png (100%) rename {basics => images/basics}/plugin_structure/img/rectangle_vertical.png (100%) rename {basics => images/basics}/plugin_structure/img/resource_directory_structure.png (100%) rename {basics => images/basics}/plugin_structure/img/square_logo.png (100%) rename {basics => images/basics}/plugin_structure/img/yt_logo.png (100%) rename {basics => images/basics}/project_structure/img/IntelliJIDEA_ProjectStructure.png (100%) create mode 100644 images/info rename {products => images/products}/img/android_studio_build.png (100%) rename {products => images/products}/img/phpstorm_build.png (100%) rename {reference_guide => images/reference_guide}/custom_language_support/img/PsiBuilder.gif (100%) rename {reference_guide => images/reference_guide}/frameworks_and_external_apis/img/xml_dom_api/booleancontrol.gif (100%) rename {reference_guide => images/reference_guide}/frameworks_and_external_apis/img/xml_dom_api/collectioncontrol.gif (100%) rename {reference_guide => images/reference_guide}/frameworks_and_external_apis/img/xml_dom_api/combocontrol.gif (100%) rename {reference_guide => images/reference_guide}/frameworks_and_external_apis/img/xml_dom_api/psiclasscontrol.gif (100%) rename {reference_guide => images/reference_guide}/img/bus.png (100%) rename {reference_guide => images/reference_guide}/img/configurable.png (100%) rename {reference_guide => images/reference_guide}/img/connection.svg (100%) rename {reference_guide => images/reference_guide}/img/data-node-example.png (100%) rename {reference_guide => images/reference_guide}/img/data-node.png (100%) rename {reference_guide => images/reference_guide}/img/import.png (100%) rename {reference_guide => images/reference_guide}/img/nested_config.svg (100%) rename {reference_guide => images/reference_guide}/img/parent_child_broadcast.svg (100%) rename {reference_guide => images/reference_guide}/img/publish.svg (100%) rename {reference_guide => images/reference_guide}/img/standard_hierarchy.svg (100%) rename {reference_guide => images/reference_guide}/img/subscribe.svg (100%) rename {reference_guide => images/reference_guide}/img/toolWindowStructure.png (100%) rename {reference_guide => images/reference_guide}/img/toolWindowStructure@2x.png (100%) rename {reference_guide => images/reference_guide}/img/toolWindowStructure@2x_dark.png (100%) rename {reference_guide => images/reference_guide}/img/toolWindowStructure_dark.png (100%) rename {reference_guide => images/reference_guide}/img/topic.png (100%) rename {reference_guide => images/reference_guide}/img/topic.svg (100%) rename {reference_guide => images/reference_guide}/internal_actions/img/internal_lafd_win.png (100%) rename {reference_guide => images/reference_guide}/internal_actions/img/internal_uii_icon_info.png (100%) rename {reference_guide => images/reference_guide}/ui_themes/img/devkit_wiz_action.png (100%) rename {reference_guide => images/reference_guide}/ui_themes/img/devkit_wiz_dialog.png (100%) rename {reference_guide => images/reference_guide}/ui_themes/img/keys-naming.png (100%) rename {reference_guide => images/reference_guide}/ui_themes/img/theme_colorpalette_popup.png (100%) rename {reference_guide => images/reference_guide}/ui_themes/img/theme_components.png (100%) rename {reference_guide => images/reference_guide}/ui_themes/img/uit_control_complete.png (100%) rename {tutorials => images/tutorials}/action_system/img/action_never_used.png (100%) rename {tutorials => images/tutorials}/action_system/img/action_performed.png (100%) rename {tutorials => images/tutorials}/action_system/img/dynamic_action_group.png (100%) rename {tutorials => images/tutorials}/action_system/img/editor_popup_menu.png (100%) rename {tutorials => images/tutorials}/action_system/img/find_action.png (100%) rename {tutorials => images/tutorials}/action_system/img/grouped_action.png (100%) rename {tutorials => images/tutorials}/action_system/img/new_action.png (100%) rename {tutorials => images/tutorials}/action_system/img/register_action.png (100%) rename {tutorials => images/tutorials}/action_system/img/register_group.png (100%) rename {tutorials => images/tutorials}/action_system/img/tools_menu_item_action.png (100%) rename {tutorials => images/tutorials}/build_system/img/gradle_tasks_in_tool_window.png (100%) rename {tutorials => images/tutorials}/build_system/img/step1_new_gradle_project.png (100%) rename {tutorials => images/tutorials}/custom_language_support/img/annotator.png (100%) rename {tutorials => images/tutorials}/custom_language_support/img/code_style_settings.png (100%) rename {tutorials => images/tutorials}/custom_language_support/img/color_settings_page.png (100%) rename {tutorials => images/tutorials}/custom_language_support/img/commenter.png (100%) rename {tutorials => images/tutorials}/custom_language_support/img/completion.png (100%) rename {tutorials => images/tutorials}/custom_language_support/img/file_type_factory.png (100%) rename {tutorials => images/tutorials}/custom_language_support/img/find_usages.png (100%) rename {tutorials => images/tutorials}/custom_language_support/img/folding.png (100%) rename {tutorials => images/tutorials}/custom_language_support/img/formatter.png (100%) rename {tutorials => images/tutorials}/custom_language_support/img/generated_parser.png (100%) rename {tutorials => images/tutorials}/custom_language_support/img/go_to_symbol.png (100%) rename {tutorials => images/tutorials}/custom_language_support/img/in_place_rename.png (100%) rename {tutorials => images/tutorials}/custom_language_support/img/line_marker.png (100%) rename {tutorials => images/tutorials}/custom_language_support/img/line_marker_location.png (100%) rename {tutorials => images/tutorials}/custom_language_support/img/new_property.png (100%) rename {tutorials => images/tutorials}/custom_language_support/img/psi_elements.png (100%) rename {tutorials => images/tutorials}/custom_language_support/img/quick_fix.png (100%) rename {tutorials => images/tutorials}/custom_language_support/img/reference_contributor.png (100%) rename {tutorials => images/tutorials}/custom_language_support/img/rename.png (100%) rename {tutorials => images/tutorials}/custom_language_support/img/structure_view.png (100%) rename {tutorials => images/tutorials}/custom_language_support/img/syntax_highlighter.png (100%) rename {tutorials => images/tutorials}/custom_language_support/img/unresolved_property.png (100%) rename {tutorials => images/tutorials}/editor_basics/img/basics.png (100%) rename {tutorials => images/tutorials}/editor_basics/img/caret_col_pos_block.png (100%) rename {tutorials => images/tutorials}/editor_basics/img/caret_offset_l2.png (100%) rename {tutorials => images/tutorials}/editor_basics/img/editor_coords.png (100%) rename {tutorials => images/tutorials}/editor_basics/img/logical_pos_folded.png (100%) rename {tutorials => images/tutorials}/editor_basics/img/vis_pos_soft_wrap.png (100%) rename {tutorials => images/tutorials}/framework/img/custom_framework.png (100%) rename {tutorials => images/tutorials}/img/IntentionsList.png (100%) rename {tutorials => images/tutorials}/img/TernaryOperator.png (100%) rename {tutorials => images/tutorials}/img/comparingReferences.png (100%) rename {tutorials => images/tutorials}/img/comparingReferences_options.png (100%) rename {tutorials => images/tutorials}/img/settings_defaults.png (100%) rename {tutorials => images/tutorials}/img/settings_persisted.png (100%) rename {tutorials => images/tutorials}/live_templates/img/applied_titleCase.png (100%) rename {tutorials => images/tutorials}/live_templates/img/invoke_titleCase.png (100%) rename {tutorials => images/tutorials}/project_wizard/img/empty_project.png (100%) rename {tutorials => images/tutorials}/project_wizard/img/extra_step.png (100%) rename {tutorials => images/tutorials}/project_wizard/module_types/img/new_module_type.png (100%) rename {tutorials => images/tutorials}/run_configurations/img/new_run_configuration.png (100%) rename {tutorials => images/tutorials}/run_configurations/img/ui_form.png (100%) rename {tutorials => images/tutorials}/tree_structure_view/img/text_only.png (100%) rename {tutorials => images/tutorials}/writing_tests_for_plugins/img/plugin_copy_psi.png (100%) rename {user_interface_components => images/user_interface_components}/img/sample_calendar.png (100%) delete mode 100644 intro/content_updates.md delete mode 100644 products/idea.md create mode 100644 project.ihp rename reference_guide/{api_changes => }/api_changes_list_2016.md (87%) rename reference_guide/{api_changes => }/api_changes_list_2017.md (88%) rename reference_guide/{api_changes => }/api_changes_list_2018.md (96%) rename reference_guide/{api_changes => }/api_changes_list_2019.md (97%) rename reference_guide/{api_changes => }/api_changes_list_2020.md (95%) rename reference_guide/{api_changes => }/api_changes_list_2021.md (90%) delete mode 100644 reference_guide/custom_language_support.md delete mode 100644 reference_guide/project_model/build_system.md delete mode 160000 sdkdocs-template create mode 100644 topics/CODE_OF_CONDUCT.md create mode 100644 topics/CONTRIBUTING.md create mode 100644 topics/appendix/glossary.md rename {appendix => topics/appendix}/plugin_repository_obsolete.md (64%) rename {appendix => topics/appendix}/resources/consulting.md (91%) rename {appendix => topics/appendix}/resources/extension_point_list.md (98%) rename {appendix => topics/appendix}/resources/marketing.md (92%) rename {appendix => topics/appendix}/resources/useful_links.md (83%) rename {basics => topics/basics}/analyzing.md (71%) rename {basics => topics/basics}/architectural_overview/documents.md (95%) rename {basics => topics/basics}/architectural_overview/file_view_providers.md (97%) rename {basics => topics/basics}/architectural_overview/files.md (60%) rename {basics => topics/basics}/architectural_overview/general_threading_rules.md (91%) rename {basics => topics/basics}/architectural_overview/modifying_psi.md (99%) rename {basics => topics/basics}/architectural_overview/navigating_psi.md (98%) rename {basics => topics/basics}/architectural_overview/psi.md (52%) rename {basics => topics/basics}/architectural_overview/psi_elements.md (96%) rename {basics => topics/basics}/architectural_overview/psi_files.md (95%) rename {basics => topics/basics}/architectural_overview/psi_references.md (92%) rename {basics => topics/basics}/architectural_overview/virtual_file.md (87%) rename basics/action_system.md => topics/basics/basic_action_system.md (93%) rename basics/run_configurations.md => topics/basics/basic_run_configurations.md (67%) rename {basics => topics/basics}/basics.md (78%) rename {basics => topics/basics}/disposers.md (89%) rename {basics => topics/basics}/editing.md (65%) rename {basics => topics/basics}/faq.md (98%) rename {basics => topics/basics}/getting_started.md (68%) rename {basics => topics/basics}/getting_started/build_number_ranges.md (89%) rename {basics => topics/basics}/getting_started/creating_plugin_project.md (71%) rename {basics => topics/basics}/getting_started/deploying_plugin.md (76%) rename {basics => topics/basics}/getting_started/plugin_compatibility.md (84%) rename {basics => topics/basics}/getting_started/publishing_plugin.md (84%) rename {basics => topics/basics}/getting_started/running_and_debugging_a_plugin.md (84%) rename {basics => topics/basics}/getting_started/setting_up_environment.md (72%) rename {basics => topics/basics}/getting_started/update_plugins_format.md (74%) rename {basics => topics/basics}/getting_started/using_dev_kit.md (72%) rename {basics => topics/basics}/ide_development_instance.md (79%) rename {basics => topics/basics}/indexing_and_psi_stubs.md (86%) rename {basics => topics/basics}/indexing_and_psi_stubs/file_based_indexes.md (87%) rename {basics => topics/basics}/indexing_and_psi_stubs/stub_indexes.md (95%) rename {basics => topics/basics}/intellij_coding_guidelines.md (98%) rename {basics => topics/basics}/persistence.md (52%) rename {basics => topics/basics}/persisting_sensitive_data.md (95%) rename {basics => topics/basics}/persisting_state_of_components.md (94%) rename {basics => topics/basics}/platform_contributions.md (94%) create mode 100644 topics/basics/plugin_structure.md rename {basics => topics/basics}/plugin_structure/dynamic_plugins.md (84%) rename {basics => topics/basics}/plugin_structure/plugin_actions.md (88%) rename {basics => topics/basics}/plugin_structure/plugin_class_loaders.md (97%) rename {basics => topics/basics}/plugin_structure/plugin_components.md (91%) rename {basics => topics/basics}/plugin_structure/plugin_configuration_file.md (96%) rename {basics => topics/basics}/plugin_structure/plugin_content.md (97%) rename {basics => topics/basics}/plugin_structure/plugin_dependencies.md (63%) rename {basics => topics/basics}/plugin_structure/plugin_extension_points.md (91%) rename {basics => topics/basics}/plugin_structure/plugin_extensions.md (89%) rename {basics => topics/basics}/plugin_structure/plugin_icon_file.md (72%) rename {basics => topics/basics}/plugin_structure/plugin_listeners.md (92%) rename {basics => topics/basics}/plugin_structure/plugin_services.md (88%) rename {basics => topics/basics}/project_structure.md (82%) rename {basics => topics/basics}/project_view.md (63%) rename {basics => topics/basics}/psi_cookbook.md (79%) rename {basics => topics/basics}/run_configurations/run_configuration_execution.md (99%) rename {basics => topics/basics}/run_configurations/run_configuration_management.md (97%) create mode 100644 topics/basics/settings.md create mode 100644 topics/basics/templates.md rename {basics => topics/basics}/testing_plugins/light_and_heavy_tests.md (79%) rename {basics => topics/basics}/testing_plugins/test_project_and_testdata_directories.md (77%) rename {basics => topics/basics}/testing_plugins/testing_highlighting.md (96%) rename {basics => topics/basics}/testing_plugins/testing_plugins.md (90%) rename {basics => topics/basics}/testing_plugins/tests_and_fixtures.md (95%) rename {basics => topics/basics}/testing_plugins/writing_tests.md (94%) rename {basics => topics/basics}/types_of_plugins.md (88%) rename {basics => topics/basics}/virtual_file_system.md (90%) create mode 100644 topics/info create mode 100644 topics/intellij-sdk-docs-original_CODE_OF_CONDUCT.md create mode 100644 topics/intellij-sdk-docs-original_CONTRIBUTING.md rename {intro => topics/intro}/about.md (77%) create mode 100644 topics/intro/content_updates.md rename {intro => topics/intro}/getting_help.md (84%) rename {intro => topics/intro}/intellij_platform.md (94%) rename {intro => topics/intro}/key_topics.md (51%) rename {intro => topics/intro}/sdk_code_guidelines.md (87%) rename {intro => topics/intro}/sdk_style.md (73%) rename {intro => topics/intro}/welcome.md (58%) rename {platform => topics/platform}/fundamentals.md (52%) rename {products => topics/products}/android_studio.md (80%) rename {products => topics/products}/app_code.md (61%) rename {products => topics/products}/clion.md (75%) rename {products => topics/products}/data_grip.md (68%) rename {products => topics/products}/dev_alternate_products.md (82%) rename {products => topics/products}/goland.md (76%) create mode 100644 topics/products/idea.md rename {products => topics/products}/phpstorm/existing_plugins.md (98%) rename {products => topics/products}/phpstorm/php_open_api.md (98%) rename {products => topics/products}/phpstorm/php_open_api_breaking_changes.md (86%) rename {products => topics/products}/phpstorm/php_open_api_breaking_changes_202.md (97%) rename {products => topics/products}/phpstorm/php_open_api_breaking_changes_203.md (98%) rename {products => topics/products}/phpstorm/phpstorm.md (78%) rename {products => topics/products}/pycharm.md (93%) rename {products => topics/products}/rider.md (88%) rename {products => topics/products}/rubymine.md (76%) rename {products => topics/products}/webstorm.md (70%) create mode 100644 topics/recently_updated.md rename {reference_guide => topics/reference_guide}/api_notable/api_notable.md (63%) rename {reference_guide => topics/reference_guide}/api_notable/api_notable_list_2018.md (90%) rename {reference_guide => topics/reference_guide}/api_notable/api_notable_list_2019.md (90%) rename {reference_guide => topics/reference_guide}/api_notable/api_notable_list_2020.md (86%) rename {reference_guide => topics/reference_guide}/api_notable/api_notable_list_2021.md (59%) rename {reference_guide => topics/reference_guide}/color_scheme_management.md (97%) create mode 100644 topics/reference_guide/custom_language_support.md rename {reference_guide => topics/reference_guide}/custom_language_support/additional_minor_features.md (94%) rename {reference_guide => topics/reference_guide}/custom_language_support/code_completion.md (91%) rename {reference_guide => topics/reference_guide}/custom_language_support/code_formatting.md (96%) rename {reference_guide => topics/reference_guide}/custom_language_support/code_inspections_and_intentions.md (87%) rename {reference_guide => topics/reference_guide}/custom_language_support/declarations_and_references.md (95%) rename {reference_guide => topics/reference_guide}/custom_language_support/documentation.md (97%) rename {reference_guide => topics/reference_guide}/custom_language_support/find_usages.md (93%) rename {reference_guide => topics/reference_guide}/custom_language_support/go_to_class_and_go_to_symbol.md (72%) rename {reference_guide => topics/reference_guide}/custom_language_support/implementing_lexer.md (93%) rename {reference_guide => topics/reference_guide}/custom_language_support/implementing_parser_and_psi.md (96%) rename {reference_guide => topics/reference_guide}/custom_language_support/navigation.md (92%) rename {reference_guide => topics/reference_guide}/custom_language_support/references_and_resolve.md (84%) rename {reference_guide => topics/reference_guide}/custom_language_support/registering_file_type.md (82%) rename {reference_guide => topics/reference_guide}/custom_language_support/rename_refactoring.md (95%) rename {reference_guide => topics/reference_guide}/custom_language_support/safe_delete_refactoring.md (96%) rename {reference_guide => topics/reference_guide}/custom_language_support/structure_view.md (95%) rename {reference_guide => topics/reference_guide}/custom_language_support/surround_with.md (97%) rename {reference_guide => topics/reference_guide}/custom_language_support/symbols.md (90%) rename {reference_guide => topics/reference_guide}/custom_language_support/syntax_highlighting_and_error_highlighting.md (89%) rename {reference_guide => topics/reference_guide}/editors.md (84%) rename {reference_guide => topics/reference_guide}/frameworks_and_external_apis/external_builder_api.md (96%) rename {reference_guide => topics/reference_guide}/frameworks_and_external_apis/external_system_integration.md (92%) rename {reference_guide => topics/reference_guide}/frameworks_and_external_apis/spring_api.md (91%) rename {reference_guide => topics/reference_guide}/frameworks_and_external_apis/xml_dom_api.md (98%) rename {reference_guide => topics/reference_guide}/intellij_artifacts.md (96%) rename {reference_guide => topics/reference_guide}/internal_actions/enabling_internal.md (94%) create mode 100644 topics/reference_guide/internal_actions/interal_actions_menu.md rename {reference_guide => topics/reference_guide}/internal_actions/internal_actions_intro.md (69%) rename {reference_guide => topics/reference_guide}/internal_actions/internal_ui_inspector.md (83%) rename {reference_guide => topics/reference_guide}/internal_actions/internal_ui_laf_defaults.md (90%) rename {reference_guide => topics/reference_guide}/internal_actions/internal_ui_sub.md (73%) rename {reference_guide => topics/reference_guide}/jcef.md (95%) rename {reference_guide => topics/reference_guide}/localization_guide.md (92%) rename {reference_guide => topics/reference_guide}/messaging_infrastructure.md (94%) rename {reference_guide => topics/reference_guide}/multiple_carets.md (94%) rename {reference_guide => topics/reference_guide}/performance/performance.md (86%) create mode 100644 topics/reference_guide/project_model/build_system.md rename {reference_guide => topics/reference_guide}/project_model/facet.md (84%) rename {reference_guide => topics/reference_guide}/project_model/library.md (95%) rename {reference_guide => topics/reference_guide}/project_model/module.md (95%) rename {reference_guide => topics/reference_guide}/project_model/project.md (94%) rename {reference_guide => topics/reference_guide}/project_model/sdk.md (96%) rename {reference_guide => topics/reference_guide}/project_wizard.md (97%) rename {reference_guide => topics/reference_guide}/settings_groups.md (93%) rename {reference_guide => topics/reference_guide}/settings_guide.md (83%) rename {reference_guide => topics/reference_guide}/tomcat_integration.md (84%) rename {reference_guide => topics/reference_guide}/ui_themes/themes.md (88%) rename {reference_guide => topics/reference_guide}/ui_themes/themes_customize.md (94%) rename {reference_guide => topics/reference_guide}/ui_themes/themes_extras.md (97%) rename {reference_guide => topics/reference_guide}/ui_themes/themes_intro.md (73%) rename {reference_guide => topics/reference_guide}/ui_themes/themes_metadata.md (94%) rename {reference_guide => topics/reference_guide}/vcs_integration_for_plugins.md (97%) rename {reference_guide => topics/reference_guide}/work_with_icons_and_images.md (79%) rename {tutorials => topics/tutorials}/action_system.md (72%) rename {tutorials => topics/tutorials}/action_system/grouping_action.md (93%) rename {tutorials => topics/tutorials}/action_system/working_with_custom_actions.md (86%) rename {tutorials => topics/tutorials}/build_system/deployment.md (87%) rename {tutorials => topics/tutorials}/build_system/gradle_guide.md (81%) rename tutorials/build_system/prerequisites.md => topics/tutorials/build_system/gradle_prerequisites.md (83%) rename {tutorials => topics/tutorials}/code_inspections.md (97%) rename {tutorials => topics/tutorials}/code_intentions.md (91%) rename {tutorials => topics/tutorials}/custom_language_support/annotator.md (63%) rename {tutorials => topics/tutorials}/custom_language_support/code_style_settings.md (72%) rename {tutorials => topics/tutorials}/custom_language_support/commenter.md (71%) rename {tutorials => topics/tutorials}/custom_language_support/completion_contributor.md (72%) rename {tutorials => topics/tutorials}/custom_language_support/find_usages_provider.md (76%) rename {tutorials => topics/tutorials}/custom_language_support/folding_builder.md (80%) rename {tutorials => topics/tutorials}/custom_language_support/formatter.md (78%) rename {tutorials => topics/tutorials}/custom_language_support/go_to_symbol_contributor.md (81%) rename {tutorials => topics/tutorials}/custom_language_support/grammar_and_parser.md (77%) rename {tutorials => topics/tutorials}/custom_language_support/language_and_filetype.md (71%) rename {tutorials => topics/tutorials}/custom_language_support/lexer_and_parser_definition.md (71%) rename {tutorials => topics/tutorials}/custom_language_support/line_marker_provider.md (86%) rename {tutorials => topics/tutorials}/custom_language_support/prerequisites.md (61%) rename {tutorials => topics/tutorials}/custom_language_support/psi_helper_and_utilities.md (85%) rename {tutorials => topics/tutorials}/custom_language_support/quick_fix.md (64%) rename {tutorials => topics/tutorials}/custom_language_support/reference_contributor.md (78%) rename {tutorials => topics/tutorials}/custom_language_support/structure_view_factory.md (77%) rename {tutorials => topics/tutorials}/custom_language_support/syntax_highlighter_and_color_settings_page.md (64%) create mode 100644 topics/tutorials/custom_language_support_tutorial.md rename {tutorials => topics/tutorials}/editor_basics.md (75%) rename {tutorials => topics/tutorials}/editor_basics/coordinates_system.md (94%) rename {tutorials => topics/tutorials}/editor_basics/editor_events.md (96%) rename {tutorials => topics/tutorials}/editor_basics/working_with_text.md (89%) rename {tutorials => topics/tutorials}/framework.md (94%) rename {tutorials => topics/tutorials}/github_template.md (90%) create mode 100644 topics/tutorials/gradle_build_system.md rename tutorials/project_wizard.md => topics/tutorials/intro_project_wizard.md (72%) rename {tutorials => topics/tutorials}/kotlin.md (87%) rename {tutorials => topics/tutorials}/live_templates.md (85%) rename {tutorials => topics/tutorials}/live_templates/new_macros.md (92%) rename {tutorials => topics/tutorials}/live_templates/template_support.md (92%) rename {tutorials => topics/tutorials}/project_wizard/adding_new_steps.md (85%) rename {tutorials => topics/tutorials}/project_wizard/module_types.md (68%) rename {tutorials => topics/tutorials}/run_configurations.md (89%) rename {tutorials => topics/tutorials}/settings_tutorial.md (74%) rename {tutorials => topics/tutorials}/tree_structure_view.md (80%) create mode 100644 topics/tutorials/writing_tests_for_plugins.md rename {tutorials => topics/tutorials}/writing_tests_for_plugins/annotator_test.md (79%) rename {tutorials => topics/tutorials}/writing_tests_for_plugins/commenter_test.md (85%) rename {tutorials => topics/tutorials}/writing_tests_for_plugins/completion_test.md (83%) rename {tutorials => topics/tutorials}/writing_tests_for_plugins/find_usages_test.md (67%) rename {tutorials => topics/tutorials}/writing_tests_for_plugins/folding_test.md (56%) rename {tutorials => topics/tutorials}/writing_tests_for_plugins/formatter_test.md (74%) rename {tutorials => topics/tutorials}/writing_tests_for_plugins/parsing_test.md (73%) rename {tutorials => topics/tutorials}/writing_tests_for_plugins/reference_test.md (76%) rename {tutorials => topics/tutorials}/writing_tests_for_plugins/rename_test.md (65%) rename {tutorials => topics/tutorials}/writing_tests_for_plugins/tests_prerequisites.md (92%) rename {user_interface_components => topics/user_interface_components}/dialog_wrapper.md (95%) rename {user_interface_components => topics/user_interface_components}/editor_components.md (98%) rename {user_interface_components => topics/user_interface_components}/file_and_class_choosers.md (97%) rename {user_interface_components => topics/user_interface_components}/kotlin_ui_dsl.md (94%) rename {user_interface_components => topics/user_interface_components}/lists_and_trees.md (99%) rename {user_interface_components => topics/user_interface_components}/misc_swing_components.md (93%) rename {user_interface_components => topics/user_interface_components}/notifications.md (97%) rename {user_interface_components => topics/user_interface_components}/popups.md (96%) rename {user_interface_components => topics/user_interface_components}/tool_windows.md (96%) create mode 100644 topics/user_interface_components/user_interface_components.md delete mode 100644 tutorials/build_system.md delete mode 100644 tutorials/custom_language_support_tutorial.md delete mode 100644 tutorials/writing_tests_for_plugins.md delete mode 100644 user_interface_components/user_interface_components.md diff --git a/.github/workflows/build-test.yml b/.github/workflows/build-test.yml index b9891aa9b..961afac46 100644 --- a/.github/workflows/build-test.yml +++ b/.github/workflows/build-test.yml @@ -2,34 +2,7 @@ name: Build on: [push, pull_request] jobs: - docs: - name: Docs - runs-on: ubuntu-latest - container: - image: ruby:2.6 - steps: - - name: Fetch Sources - uses: actions/checkout@v2 - - name: Setup Cache - uses: actions/cache@v2 - with: - path: vendor/bundle - key: ${{ runner.os }}-gems-${{ hashFiles('**/Gemfile.lock') }} - restore-keys: | - ${{ runner.os }}-gems- - - name: Install Dependencies - run: | - git submodule update --init --remote - gem install bundler:2.0.1 - bundle install - - name: Build - run: | - dpkg-reconfigure --frontend=noninteractive locales && update-locale LANG=C.UTF-8 - export LC_ALL=C.UTF-8 - export LANG=en_US.UTF-8 - export LANGUAGE=en_US.UTF-8 - rake build - + documentedProblemsPageVerification: name: Documented Problems Page Verification runs-on: ubuntu-latest diff --git a/.gitmodules b/.gitmodules deleted file mode 100644 index 7107ba09c..000000000 --- a/.gitmodules +++ /dev/null @@ -1,3 +0,0 @@ -[submodule "sdkdocs-template"] - path = sdkdocs-template - url = https://github.com/JetBrains/sdkdocs-template.git diff --git a/.idea/vcs.xml b/.idea/vcs.xml index ac84e06ba..44b7e46b8 100644 --- a/.idea/vcs.xml +++ b/.idea/vcs.xml @@ -12,6 +12,5 @@ - - + \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e2de9cbb5..7f59e802c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,10 +8,7 @@ Before you begin contributing content to the SDK, please read this page thorough For information about contributing to the IntelliJ Platform itself, please visit [Contributing to the IntelliJ Platform](/basics/platform_contributions.md). Here are some useful things to know before authoring SDK content and submitting your Pull Request. - -* Dummy list item -{:toc} - + ## Setting Up the Documentation Build Environment This site runs via [Jekyll](https://jekyllrb.com), which is a popular static site generator, written in Ruby. @@ -20,7 +17,7 @@ Once set up, running the site is as easy as calling `rake preview`. Alternatively, the site can also be hosted in a [Docker container](https://www.docker.com). On Mac and Windows, this means the site is hosted in a virtual machine. -Docker maintains this container, building it based on the instructions in the [`Dockerfile`](Dockerfile). +Docker maintains this container, building it based on the instructions in the [`Dockerfile`](https://github.com/JetBrains/intellij-sdk-docs/blob/master/Dockerfile). All dependencies (Ruby, etc.) are automatically installed when building the image, which reduces the manual configuration steps. The Docker image is also used to build the [published site](https://www.jetbrains.org/intellij/sdk/docs/index.html), so it is a known working environment. diff --git a/Dockerfile b/Dockerfile deleted file mode 100644 index 1efbb91c2..000000000 --- a/Dockerfile +++ /dev/null @@ -1,35 +0,0 @@ -FROM ruby:2.2 - -RUN apt-get update - -RUN apt-get --yes install locales -RUN dpkg-reconfigure -f noninteractive locales && \ - locale-gen C.UTF-8 && \ - /usr/sbin/update-locale LANG=C.UTF-8 -RUN echo 'en_US.UTF-8 UTF-8' >> /etc/locale.gen && \ - locale-gen -ENV LANG en_US.UTF-8 -ENV LANGUAGE en_US:en -ENV LC_ALL en_US.UTF-8 - -# Tell anyone who's interested that we're running in docker -ENV DOCKER true - -RUN apt-get --yes install nodejs - -# Add bundle install to Docker image -ADD Gemfile* /tmp/ -ADD Rakefile /tmp/ -ADD _SUMMARY.md /tmp/ -ADD .git /tmp/.git -ADD sdkdocs-template /tmp/sdkdocs-template -WORKDIR /tmp -RUN rake bootstrap --trace - -WORKDIR /usr/src/app - -EXPOSE 4000 - -CMD \ - rake bootstrap --trace && \ - rake preview diff --git a/Gemfile b/Gemfile deleted file mode 100644 index 8d99cdc60..000000000 --- a/Gemfile +++ /dev/null @@ -1 +0,0 @@ -eval File.read('sdkdocs-template/bundler/Gemfile.defaults') diff --git a/Gemfile.lock b/Gemfile.lock deleted file mode 100644 index d05cf28dd..000000000 --- a/Gemfile.lock +++ /dev/null @@ -1,106 +0,0 @@ -GIT - remote: https://github.com/JetBrains/link-checker.git - revision: 3c945617a239d3f96da888c55f6813d39916a41b - branch: multiple_fixes - specs: - link-checker (0.7.2) - anemone (~> 0.7.2) - certified (~> 1.0.0) - colorize (~> 0.7.3) - nokogiri (~> 1.6) - trollop (~> 2.0) - -GIT - remote: https://github.com/citizenmatt/jekyll-git_metadata.git - revision: 03c85b599fe6c52e3f0253450b9790503a3dd742 - branch: caching - specs: - jekyll-git_metadata (0.1.2) - jekyll (~> 3.0) - -GEM - remote: https://rubygems.org/ - specs: - addressable (2.6.0) - public_suffix (>= 2.0.2, < 4.0) - anemone (0.7.2) - nokogiri (>= 1.3.0) - robotex (>= 1.0.0) - certified (1.0.0) - colorator (1.1.0) - colorize (0.7.7) - concurrent-ruby (1.1.4) - em-websocket (0.5.1) - eventmachine (>= 0.12.9) - http_parser.rb (~> 0.6.0) - eventmachine (1.2.7) - eventmachine (1.2.7-x64-mingw32) - ffi (1.10.0) - ffi (1.10.0-x64-mingw32) - forwardable-extended (2.6.0) - http_parser.rb (0.6.0) - i18n (0.9.5) - concurrent-ruby (~> 1.0) - jekyll (3.8.5) - addressable (~> 2.4) - colorator (~> 1.0) - em-websocket (~> 0.5) - i18n (~> 0.7) - jekyll-sass-converter (~> 1.0) - jekyll-watch (~> 2.0) - kramdown (~> 1.14) - liquid (~> 4.0) - mercenary (~> 0.3.3) - pathutil (~> 0.9) - rouge (>= 1.7, < 4) - safe_yaml (~> 1.0) - jekyll-redirect-from (0.14.0) - jekyll (~> 3.3) - jekyll-sass-converter (1.5.2) - sass (~> 3.4) - jekyll-watch (2.1.2) - listen (~> 3.0) - kramdown (1.17.0) - liquid (4.0.1) - listen (3.1.5) - rb-fsevent (~> 0.9, >= 0.9.4) - rb-inotify (~> 0.9, >= 0.9.7) - ruby_dep (~> 1.2) - mercenary (0.3.6) - mini_portile2 (2.4.0) - nokogiri (1.10.8) - mini_portile2 (~> 2.4.0) - nokogiri (1.10.8-x64-mingw32) - mini_portile2 (~> 2.4.0) - pathutil (0.16.2) - forwardable-extended (~> 2.6) - public_suffix (3.0.3) - rake (12.3.3) - rb-fsevent (0.10.3) - rb-inotify (0.10.0) - ffi (~> 1.0) - robotex (1.0.0) - rouge (3.3.0) - ruby_dep (1.5.0) - safe_yaml (1.0.4) - sass (3.7.3) - sass-listen (~> 4.0.0) - sass-listen (4.0.0) - rb-fsevent (~> 0.9, >= 0.9.4) - rb-inotify (~> 0.9, >= 0.9.7) - trollop (2.9.9) - -PLATFORMS - ruby - x64-mingw32 - -DEPENDENCIES - jekyll (~> 3.8.5) - jekyll-git_metadata! - jekyll-redirect-from - link-checker! - rake - rouge - -BUNDLED WITH - 2.0.1 diff --git a/Rakefile b/Rakefile deleted file mode 100644 index 3fd593b12..000000000 --- a/Rakefile +++ /dev/null @@ -1,24 +0,0 @@ -Rake.add_rakelib 'sdkdocs-template/rakelib' - -begin - FileUtils.mkdir_p %w( _includes/code_samples ) - Dir.glob('code_samples/**/*').reject { |e| e.match(/\/(build|gradlew?)(\/|$)/) }.each do |path| - if File.directory? path - FileUtils.mkdir_p "_includes/#{path}" - else - FileUtils.mkdir_p "_includes/#{File.dirname path}" - FileUtils.cp path, "_includes/#{path}" - end - end -rescue - `yes | cp -rf code_samples _includes` -end - -CONFIG = { - :source_dir => __dir__, - :tmp_dir => "#{__dir__}/_tmp", - :build_destination => "_site", - :preview_host => "0.0.0.0", - :preview_port => 4000, - :default_env => 'dev' -} diff --git a/_SUMMARY.md b/_SUMMARY.md deleted file mode 100644 index 52317684f..000000000 --- a/_SUMMARY.md +++ /dev/null @@ -1,292 +0,0 @@ -## Summary - -* [Introduction](intro/welcome.md) -* [The IntelliJ Platform](intro/intellij_platform.md) - * [Contributing to the IntelliJ Platform](basics/platform_contributions.md) - * [IntelliJ Platform Coding Guidelines](basics/intellij_coding_guidelines.md) -* [The IntelliJ Platform SDK](intro/about.md) - * [Key Topics](intro/key_topics.md) - * [Contributing to the SDK](CONTRIBUTING.md) - * [SDK Docs Style Guide](intro/sdk_style.md) - * [SDK Code Sample Guidelines](intro/sdk_code_guidelines.md) - * [Code of Conduct](CODE_OF_CONDUCT.md) -* [Getting Help](intro/getting_help.md) -* [Content Updates](intro/content_updates.md) - * [Recently Updated](recently_updated.md) - -## Part I - Plugins -* [Quick Start Guide](basics/basics.md) - * [Main Types of Plugins](basics/types_of_plugins.md) -* [Code Samples](https://github.com/JetBrains/intellij-sdk-code-samples) -* [Creating Your First Plugin](basics/getting_started.md) - * [Using GitHub Template](tutorials/github_template.md) - * [Using Gradle](tutorials/build_system.md) - * [Getting Started with Gradle](tutorials/build_system/prerequisites.md) - * [Configuring Gradle Projects](tutorials/build_system/gradle_guide.md) - * [Publishing Plugins with Gradle](tutorials/build_system/deployment.md) - * [Using DevKit](basics/getting_started/using_dev_kit.md) - * [Setting Up a Development Environment](basics/getting_started/setting_up_environment.md) - * [Creating a Plugin Project](basics/getting_started/creating_plugin_project.md) - * [Running and Debugging a Plugin](basics/getting_started/running_and_debugging_a_plugin.md) - * [Deploying a Plugin](basics/getting_started/deploying_plugin.md) - * [Publishing a Plugin](basics/getting_started/publishing_plugin.md) -* [IDE Development Instances](basics/ide_development_instance.md) -* [Custom Plugin Repositories](basics/getting_started/update_plugins_format.md) -* [Plugin Structure](basics/plugin_structure.md) - * [Plugin Content](basics/plugin_structure/plugin_content.md) - * [Plugin Class Loaders](basics/plugin_structure/plugin_class_loaders.md) - * [Plugin Actions](basics/plugin_structure/plugin_actions.md) - * [Plugin Extensions](basics/plugin_structure/plugin_extensions.md) - * [Plugin Services](basics/plugin_structure/plugin_services.md) - * [Plugin Listeners](basics/plugin_structure/plugin_listeners.md) - * [Plugin Extension Points](basics/plugin_structure/plugin_extension_points.md) - * [Plugin Components](basics/plugin_structure/plugin_components.md) - * [Plugin Configuration File](basics/plugin_structure/plugin_configuration_file.md) - * [Plugin Logo (Icon)](basics/plugin_structure/plugin_icon_file.md) - * [Plugin Dependencies](basics/plugin_structure/plugin_dependencies.md) -* [Dynamic Plugins](basics/plugin_structure/dynamic_plugins.md) -* [IntelliJ Platform Artifacts Repositories](reference_guide/intellij_artifacts.md) -* [Kotlin for Plugin Developers](tutorials/kotlin.md) -* [Internal Actions Menu](reference_guide/internal_actions/internal_actions_intro.md) - * [Enabling Internal Mode](reference_guide/internal_actions/enabling_internal.md) - * [UI Tools](reference_guide/internal_actions/internal_ui_sub.md) - * [UI Inspector](reference_guide/internal_actions/internal_ui_inspector.md) - * [LaF Defaults](reference_guide/internal_actions/internal_ui_laf_defaults.md) -* [Optimizing Performance](reference_guide/performance/performance.md) -* [Plugin Development FAQ](basics/faq.md) - -## Part II - Base Platform -* [Fundamentals](platform/fundamentals.md) - * Component Model - * [Disposer and Disposable](basics/disposers.md) - * [Threading](basics/architectural_overview/general_threading_rules.md) - * Background Tasks - * [Messaging Infrastructure](reference_guide/messaging_infrastructure.md) - * Queries and Query Executors -* [User Interface Components](user_interface_components/user_interface_components.md) - * [Tool Windows](user_interface_components/tool_windows.md) - * [Dialogs](user_interface_components/dialog_wrapper.md) - * [Popups](user_interface_components/popups.md) - * [Notifications](user_interface_components/notifications.md) - * [File and Class Choosers](user_interface_components/file_and_class_choosers.md) - * [Editor Components](user_interface_components/editor_components.md) - * [List and Tree Controls](user_interface_components/lists_and_trees.md) - * [Miscellaneous Swing Components](user_interface_components/misc_swing_components.md) - * [Icons and Images](reference_guide/work_with_icons_and_images.md) - * [Color Scheme Management](reference_guide/color_scheme_management.md) - * [Kotlin UI DSL](user_interface_components/kotlin_ui_dsl.md) -* [JCEF](reference_guide/jcef.md) -* [UI Themes](reference_guide/ui_themes/themes_intro.md) - * [Creating UI Themes](reference_guide/ui_themes/themes.md) - * [Customizing a UI Theme](reference_guide/ui_themes/themes_customize.md) - * [Adding Schemes and Images](reference_guide/ui_themes/themes_extras.md) - * [Exposing Theme Metadata](reference_guide/ui_themes/themes_metadata.md) -* [Actions](basics/action_system.md) - * [Actions Tutorial](tutorials/action_system.md) - * [Creating Actions](tutorials/action_system/working_with_custom_actions.md) - * [Grouping Actions](tutorials/action_system/grouping_action.md) -* [Persistence](basics/persistence.md) - * [Persisting State of Components](basics/persisting_state_of_components.md) - * [Persisting Sensitive Data](basics/persisting_sensitive_data.md) -* [Settings](basics/settings.md) - * [Settings Guide](reference_guide/settings_guide.md) - * [Custom Groups](reference_guide/settings_groups.md) - * [Settings Tutorial](tutorials/settings_tutorial.md) -* [Files](basics/architectural_overview/files.md) - * [Virtual File System](basics/virtual_file_system.md) - * [Virtual Files](basics/architectural_overview/virtual_file.md) -* [Documents](basics/architectural_overview/documents.md) -* [Editors](reference_guide/editors.md) - * [Editor Basics](tutorials/editor_basics.md) - * [1. Working with Text](tutorials/editor_basics/working_with_text.md) - * [2. Editor Coordinates System. Positions and Offsets](tutorials/editor_basics/coordinates_system.md) - * [3. Handling Editor Events](tutorials/editor_basics/editor_events.md) - * [Multiple Carets](reference_guide/multiple_carets.md) -* [Run Configurations](basics/run_configurations.md) - * [Run Configuration Management](basics/run_configurations/run_configuration_management.md) - * [Execution](basics/run_configurations/run_configuration_execution.md) - * [Run Configurations Tutorial](tutorials/run_configurations.md) -* [Version Control Systems](reference_guide/vcs_integration_for_plugins.md) - * Diff - * Local History -* Tasks and Contexts -* [Localization Guide](reference_guide/localization_guide.md) -* Diagrams - -## Part III - Project Model -* [Introduction](basics/project_structure.md) -* [Project](reference_guide/project_model/project.md) - * [Project Wizard](reference_guide/project_wizard.md) - * [Project Wizard Tutorial](tutorials/project_wizard.md) - * [Adding New Steps to Project Wizard](tutorials/project_wizard/adding_new_steps.md) - * [Supporting Module Types](tutorials/project_wizard/module_types.md) - * [Frameworks](tutorials/framework.md) -* [Module](reference_guide/project_model/module.md) -* [SDK](reference_guide/project_model/sdk.md) -* [Library](reference_guide/project_model/library.md) -* [Facet](reference_guide/project_model/facet.md) -* [External System Integration](reference_guide/frameworks_and_external_apis/external_system_integration.md) - -## Part IV - PSI -* [What Is the PSI?](basics/architectural_overview/psi.md) -* [PSI Files](basics/architectural_overview/psi_files.md) -* [File View Providers](basics/architectural_overview/file_view_providers.md) -* [PSI Elements](basics/architectural_overview/psi_elements.md) -* [Navigating the PSI](basics/architectural_overview/navigating_psi.md) -* [References](basics/architectural_overview/psi_references.md) -* [Modifying the PSI](basics/architectural_overview/modifying_psi.md) -* [PSI Cookbook](basics/psi_cookbook.md) -* [Indexing and PSI Stubs](basics/indexing_and_psi_stubs.md) - * [File-Based Indexes](basics/indexing_and_psi_stubs/file_based_indexes.md) - * [Stub Indexes](basics/indexing_and_psi_stubs/stub_indexes.md) -* Element Patterns -* Unified AST -* [XML DOM API](reference_guide/frameworks_and_external_apis/xml_dom_api.md) - -## Part V - Features -* Navigation - * Go To Symbol -* [Editing](basics/editing.md) - * Code Completion - * [Templates](basics/templates.md) - * [Live Templates](tutorials/live_templates.md) - * [Adding Live Templates to a Plugin](tutorials/live_templates/template_support.md) - * [Creating New Functions for Live Templates](tutorials/live_templates/new_macros.md) - * Surround Templates - * File Templates - * QuickDoc - * [Intentions](tutorials/code_intentions.md) -* [Analysing](basics/analyzing.md) - * Annotator - * [Inspections](tutorials/code_inspections.md) - * Profiles - * Scopes - * Suppressing Highlights - * Structural Search -* Refactoring -* [Project View](basics/project_view.md) - * [Modifying Project View Structure](tutorials/tree_structure_view.md) -* Unit Testing -* [Build System](reference_guide/project_model/build_system.md) - * [External Builder API and Plugins](reference_guide/frameworks_and_external_apis/external_builder_api.md) - -## Part VI - Testing - -* [Testing Plugins](basics/testing_plugins/testing_plugins.md) -* [Tests and Fixtures](basics/testing_plugins/tests_and_fixtures.md) -* [Light and Heavy Tests](basics/testing_plugins/light_and_heavy_tests.md) -* [Test Project and Testdata Directories](basics/testing_plugins/test_project_and_testdata_directories.md) -* [Writing Tests](basics/testing_plugins/writing_tests.md) -* [Testing Highlighting](basics/testing_plugins/testing_highlighting.md) - -## Part VII - Custom Languages -* [Custom Language Support](reference_guide/custom_language_support.md) - * [Registering File Type](reference_guide/custom_language_support/registering_file_type.md) - * [Implementing Lexer](reference_guide/custom_language_support/implementing_lexer.md) - * [Implementing Parser and PSI](reference_guide/custom_language_support/implementing_parser_and_psi.md) - * [Syntax Highlighting and Error Highlighting](reference_guide/custom_language_support/syntax_highlighting_and_error_highlighting.md) - * [References and Resolve](reference_guide/custom_language_support/references_and_resolve.md) - * [Symbols](reference_guide/custom_language_support/symbols.md) - * [Declarations and References](reference_guide/custom_language_support/declarations_and_references.md) - * [Navigation](reference_guide/custom_language_support/navigation.md) - * [Code Completion](reference_guide/custom_language_support/code_completion.md) - * [Find Usages](reference_guide/custom_language_support/find_usages.md) - * [Rename Refactoring](reference_guide/custom_language_support/rename_refactoring.md) - * [Safe Delete Refactoring](reference_guide/custom_language_support/safe_delete_refactoring.md) - * [Code Formatter](reference_guide/custom_language_support/code_formatting.md) - * [Code Inspections and Intentions](reference_guide/custom_language_support/code_inspections_and_intentions.md) - * [Structure View](reference_guide/custom_language_support/structure_view.md) - * [Surround With](reference_guide/custom_language_support/surround_with.md) - * [Go to Class and Go to Symbol](reference_guide/custom_language_support/go_to_class_and_go_to_symbol.md) - * [Documentation](reference_guide/custom_language_support/documentation.md) - * [Additional Minor Features](reference_guide/custom_language_support/additional_minor_features.md) - * Parameter Info - * Parameter Hints -* [Custom Language Support Tutorial](tutorials/custom_language_support_tutorial.md) - * [1. Prerequisites](tutorials/custom_language_support/prerequisites.md) - * [2. Language and File Type](tutorials/custom_language_support/language_and_filetype.md) - * [3. Grammar and Parser](tutorials/custom_language_support/grammar_and_parser.md) - * [4. Lexer and Parser Definition](tutorials/custom_language_support/lexer_and_parser_definition.md) - * [5. Syntax Highlighter and Color Settings Page](tutorials/custom_language_support/syntax_highlighter_and_color_settings_page.md) - * [6. PSI Helpers and Utilities](tutorials/custom_language_support/psi_helper_and_utilities.md) - * [7. Annotator](tutorials/custom_language_support/annotator.md) - * [8. Line Marker Provider](tutorials/custom_language_support/line_marker_provider.md) - * [9. Completion Contributor](tutorials/custom_language_support/completion_contributor.md) - * [10. Reference Contributor](tutorials/custom_language_support/reference_contributor.md) - * [11. Find Usages Provider](tutorials/custom_language_support/find_usages_provider.md) - * [12. Folding Builder](tutorials/custom_language_support/folding_builder.md) - * [13. Go To Symbol Contributor](tutorials/custom_language_support/go_to_symbol_contributor.md) - * [14. Structure View Factory](tutorials/custom_language_support/structure_view_factory.md) - * [15. Formatter](tutorials/custom_language_support/formatter.md) - * [16. Code Style Settings](tutorials/custom_language_support/code_style_settings.md) - * [17. Commenter](tutorials/custom_language_support/commenter.md) - * [18. Quick Fix](tutorials/custom_language_support/quick_fix.md) -* [Testing a Custom Language Plugin](tutorials/writing_tests_for_plugins.md) - * [1. Tests Prerequisites](tutorials/writing_tests_for_plugins/tests_prerequisites.md) - * [2. Parsing Test](tutorials/writing_tests_for_plugins/parsing_test.md) - * [3. Completion Test](tutorials/writing_tests_for_plugins/completion_test.md) - * [4. Annotator Test](tutorials/writing_tests_for_plugins/annotator_test.md) - * [5. Formatter Test](tutorials/writing_tests_for_plugins/formatter_test.md) - * [6. Rename Test](tutorials/writing_tests_for_plugins/rename_test.md) - * [7. Folding Test](tutorials/writing_tests_for_plugins/folding_test.md) - * [8. Find Usages Test](tutorials/writing_tests_for_plugins/find_usages_test.md) - * [9. Commenter Test](tutorials/writing_tests_for_plugins/commenter_test.md) - * [10. Reference Test](tutorials/writing_tests_for_plugins/reference_test.md) -* Injected Languages -* Build System -* Compiler -* Debugger - -## Part VIII - Product Specific -* [Build Number Ranges](basics/getting_started/build_number_ranges.md) -* [Developing for Multiple Products](products/dev_alternate_products.md) -* [Compatibility with Multiple Products](basics/getting_started/plugin_compatibility.md) -* [Android Studio](products/android_studio.md) -* [AppCode](products/app_code.md) -* [CLion](products/clion.md) -* [DataGrip](products/data_grip.md) -* [GoLand](products/goland.md) -* [IntelliJ IDEA](products/idea.md) - * [Tomcat Integration](reference_guide/tomcat_integration.md) - * [Spring API](reference_guide/frameworks_and_external_apis/spring_api.md) -* [PhpStorm](products/phpstorm/phpstorm.md) - * [Working with the PHP Open API](products/phpstorm/php_open_api.md) - * [Breaking Changes](products/phpstorm/php_open_api_breaking_changes.md) - * [2020.3](products/phpstorm/php_open_api_breaking_changes_203.md) - * [2020.2](products/phpstorm/php_open_api_breaking_changes_202.md) - * [Existing Third Party Plugins](products/phpstorm/existing_plugins.md) -* [PyCharm](products/pycharm.md) -* [Rider](products/rider.md) -* [RubyMine](products/rubymine.md) -* [WebStorm](products/webstorm.md) - -## Part IX - Custom IDEs -* Build Your Own IDE -* Licensing - -## Part X - Plugin Repository \[moved] -* [Overview](appendix/plugin_repository_obsolete.md) - -## Appendix I - Resources - -* [Glossary](appendix/glossary.md) -* [Extension Point List](appendix/resources/extension_point_list.md) -* [Useful Links](appendix/resources/useful_links.md) -* [Marketing](appendix/resources/marketing.md) -* [Consulting](appendix/resources/consulting.md) - -## Appendix II - API Changes - -* [Incompatible API Changes](reference_guide/api_changes_list.md) - * [2021.*](reference_guide/api_changes/api_changes_list_2021.md) - * [2020.*](reference_guide/api_changes/api_changes_list_2020.md) - * [2019.*](reference_guide/api_changes/api_changes_list_2019.md) - * [2018.*](reference_guide/api_changes/api_changes_list_2018.md) - * [2017.*](reference_guide/api_changes/api_changes_list_2017.md) - * [2016.*](reference_guide/api_changes/api_changes_list_2016.md) - -* [Notable API Changes](reference_guide/api_notable/api_notable.md) - * [2021.*](reference_guide/api_notable/api_notable_list_2021.md) - * [2020.*](reference_guide/api_notable/api_notable_list_2020.md) - * [2019.*](reference_guide/api_notable/api_notable_list_2019.md) - * [2018.*](reference_guide/api_notable/api_notable_list_2018.md) diff --git a/_config.yml b/_config.yml deleted file mode 100644 index 9c72b43ce..000000000 --- a/_config.yml +++ /dev/null @@ -1,22 +0,0 @@ ---- -product_name: IntelliJ Platform SDK -product_version: -product_type: DevGuide - -url: https://www.jetbrains.org -baseurl: /intellij/sdk/docs/ - -description: Documentation for working with and extending the IntelliJ Platform SDK - -# 2020.3 -upsource: - server: upsource.jetbrains.com - repo: idea-ce - commit: 4b94ba01122752d7576eb9d69638b6e89d1671b7 - tag: 203.5981.155 - -github_repo: JetBrains/intellij-sdk-docs -youtrack_project: IJSDK - -exclude: - - code_samples diff --git a/appendix/glossary.md b/appendix/glossary.md deleted file mode 100644 index 4d34796d4..000000000 --- a/appendix/glossary.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: Glossary ---- - - -## A - -Abstract Syntax Tree _(AST)_ -: The [Abstract Syntax Tree](/reference_guide/custom_language_support/implementing_parser_and_psi.md) represents the structure of source input files. -→ _Program Structure Interface_ - -Annotator -: Provides [semantic highlighting](/reference_guide/custom_language_support/syntax_highlighting_and_error_highlighting.md) based on underlying → _Program Structure Interface_ elements. -→ _Inspection_ - -## D - -Document Object Model _(DOM)_ -: [DOM API](/reference_guide/frameworks_and_external_apis/xml_dom_api.md) abstracts working with XML files based on a custom semantic model. - -## E -Event Dispatch Thread _(EDT)_ -: The [Event Dispatch Thread](https://docs.oracle.com/javase/tutorial/uiswing/concurrency/dispatch.html) handles all Swing events. See also [General Threading Rules](/basics/architectural_overview/general_threading_rules.md). - -Extension Point _(EP)_ -: Most functionality is provided by [Using Extension Points](/basics/plugin_structure/plugin_extensions.md) provided by the platform or plugins. Plugins can also [define their own](/basics/plugin_structure/plugin_extension_points.md) to allow extensibility. - -External System _(ES)_ -: [External System](/reference_guide/frameworks_and_external_apis/external_system_integration.md) allows integrating external project management systems. - -## F - -File Based Index _(FBI)_ -: [File Based Index](/basics/indexing_and_psi_stubs/file_based_indexes.md) allows storing key-value information based on the project's files. - - -## I - -Inspection -: Supports configurable [semantic highlighting](/reference_guide/custom_language_support/code_inspections_and_intentions.md). -→ _Annotator_ - -Intention -: Provides an [automated fix](/reference_guide/custom_language_support/code_inspections_and_intentions.md) for commonly encountered code problems. - -## L - -Local History _(LVCS)_ -: A builtin → _Version Control System_ tracking all changes in the project [locally](https://www.jetbrains.com/help/idea/local-history.html). - -## J - -JetBrains Project System _(JPS)_ -: Represents the project model in [External Build](/reference_guide/frameworks_and_external_apis/external_builder_api.md#accessing-project-model-and-configuration-from-external-build) process. - -JetBrains Runtime _(JBR)_ -: The [JetBrains Runtime](/basics/ide_development_instance.md#using-a-jetbrains-runtime-for-the-development-instance) is the default bundled runtime for all IntelliJ Platform-based IDEs by JetBrains. - - -## P -Program Structure Interface _(PSI)_ -: The [Program Structure Interface](/basics/architectural_overview/psi.md) represents a syntactic and semantic code model of the source input files. → _Abstract Syntax Tree_ → _Stubs_ - -## R - -Read Action -: Allows accessing code-related data structures for reading purposes. See also [General Threading Rules](/basics/architectural_overview/general_threading_rules.md). -→ _Write Action_ - -Run Configuration _(RC)_ -: A [Run Configuration](/basics/run_configurations.md) allows running external processes from within the IDE. - -## S - -Stubs -: A subset of a → _Program Structure Interface_ tree in a binary serialized compact format, see [Stub Indexes](/basics/indexing_and_psi_stubs/stub_indexes.md). - -## V -Version Control System _(VCS)_ -: The API for [Version Control System](/reference_guide/vcs_integration_for_plugins.md) allows accessing builtin as well as adding custom implementations. - -Virtual File _(VF)_ -: A [Virtual File](/basics/architectural_overview/virtual_file.md) represents a file in a → _Virtual File System_. - -Virtual File System _(VFS)_ -: A [Virtual File System](/basics/virtual_file_system.md) provides a unified API for working with files represented as → _Virtual File_. - - -## W - -Write Action -: Allows accessing code-related data structures for writing purposes. See also [General Threading Rules](/basics/architectural_overview/general_threading_rules.md). -→ _Read Action_ diff --git a/basics/plugin_structure.md b/basics/plugin_structure.md deleted file mode 100644 index b620d184b..000000000 --- a/basics/plugin_structure.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Plugin Structure ---- - - -Click the following topics to learn more about the plugin system structure and plugin lifecycles: - -* [Plugin Content](plugin_structure/plugin_content.md) -* [Plugin Class Loaders](plugin_structure/plugin_class_loaders.md) -* [Plugin Actions](plugin_structure/plugin_actions.md) -* [Plugin Extensions](plugin_structure/plugin_extensions.md) -* [Plugin Services](plugin_structure/plugin_services.md) -* [Plugin Listeners](plugin_structure/plugin_listeners.md) -* [Plugin Extension Points](plugin_structure/plugin_extension_points.md) -* [Plugin Components](plugin_structure/plugin_components.md) -* [Plugin Configuration File](plugin_structure/plugin_configuration_file.md) -* [Plugin Logo (Icon)](plugin_structure/plugin_icon_file.md) -* [Plugin Dependencies](plugin_structure/plugin_dependencies.md) diff --git a/basics/settings.md b/basics/settings.md deleted file mode 100644 index bd96b859f..000000000 --- a/basics/settings.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Settings ---- - - -## Introduction to Settings -[Settings](https://www.jetbrains.com/help/idea/configuring-project-and-ide-settings.html) are but one application of the IntelliJ Platform [Persistence Model](/basics/persistence.md). -For more information, see: -* [Settings Guide](/reference_guide/settings_guide.md) for information about Settings Extension Points and implementations. -* [Custom Settings Groups](/reference_guide/settings_groups.md) for information about creating custom Settings groups and parent-child relationships. -* [Settings Tutorial](/tutorials/settings_tutorial.md) for step-by-step instructions for creating a simple set of custom Settings. diff --git a/basics/templates.md b/basics/templates.md deleted file mode 100644 index c5a66ab20..000000000 --- a/basics/templates.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Templates ---- - - -* [Live Templates](/tutorials/live_templates.md) - * [Adding Live Templates to a Plugin](/tutorials/live_templates/template_support.md) - * [Creating New Functions for Live Templates](/tutorials/live_templates/new_macros.md) - * Surround Templates -* File Templates diff --git a/reference_guide/img/connection.puml b/buildUML/messaging/connection.puml similarity index 100% rename from reference_guide/img/connection.puml rename to buildUML/messaging/connection.puml diff --git a/reference_guide/img/nested_config.puml b/buildUML/messaging/nested_config.puml similarity index 100% rename from reference_guide/img/nested_config.puml rename to buildUML/messaging/nested_config.puml diff --git a/reference_guide/img/parent_child_broadcast.puml b/buildUML/messaging/parent_child_broadcast.puml similarity index 100% rename from reference_guide/img/parent_child_broadcast.puml rename to buildUML/messaging/parent_child_broadcast.puml diff --git a/reference_guide/img/publish.puml b/buildUML/messaging/publish.puml similarity index 100% rename from reference_guide/img/publish.puml rename to buildUML/messaging/publish.puml diff --git a/reference_guide/img/standard_hierarchy.puml b/buildUML/messaging/standard_hierarchy.puml similarity index 100% rename from reference_guide/img/standard_hierarchy.puml rename to buildUML/messaging/standard_hierarchy.puml diff --git a/reference_guide/img/subscribe.puml b/buildUML/messaging/subscribe.puml similarity index 100% rename from reference_guide/img/subscribe.puml rename to buildUML/messaging/subscribe.puml diff --git a/reference_guide/img/topic.puml b/buildUML/messaging/topic.puml similarity index 100% rename from reference_guide/img/topic.puml rename to buildUML/messaging/topic.puml diff --git a/cfg/build-script.xml b/cfg/build-script.xml new file mode 100644 index 000000000..d0510639b --- /dev/null +++ b/cfg/build-script.xml @@ -0,0 +1,11 @@ + + + + + + + + + diff --git a/cfg/buildprofiles.xml b/cfg/buildprofiles.xml new file mode 100644 index 000000000..4e8017d0a --- /dev/null +++ b/cfg/buildprofiles.xml @@ -0,0 +1,34 @@ + + + + + https://plugins.jetbrains.com/docs + Developer Community:http://www.jetbrains.net/devnet/community/idea/kb + + + + https://plugins.jetbrains.com/docs/intellij/ + false + true + false + https://data.services.jetbrains.com/feedback + true + true + https://plugins.jetbrains.com/docs/intellij/getting-help.html + https://www.jetbrains.com/support/ + true + https://data.services.jetbrains.com/search/ + @JBPlatform + https://resources.jetbrains.com/storage/products/jetbrains/img/meta/preview.png + true + https://github.com/JetBrains/intellij-sdk-docs/edit/master/ + images/ + 4b94ba01122752d7576eb9d69638b6e89d1671b7 + idea-ce + upsource.jetbrains.com + + + + + + diff --git a/cfg/platforms.xml b/cfg/platforms.xml new file mode 100644 index 000000000..72b8ba675 --- /dev/null +++ b/cfg/platforms.xml @@ -0,0 +1,14 @@ + + + + + + keymap-%currentId%.xml + ctrl:Ctrl;control:Ctrl;alt:Alt;shift:Shift;command:⌘;meta:⌘ + \ + + + keymap-%currentId%.xml + ctrl:^;control:Control;alt:⌥;shift:⇧;command:⌘;meta:⌘ + / + + diff --git a/config.json b/config.json deleted file mode 100644 index e66d8f1bc..000000000 --- a/config.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "productName": "IntelliJ Platform SDK", - "searchScope": "intellij-sdk-docs", - "searchService": "https://data.services.jetbrains.com/search/", - "disqusID": "", - "showDisqus": false, - "useSideblocks": false -} diff --git a/container_settings.json b/container_settings.json deleted file mode 100644 index b94628e94..000000000 --- a/container_settings.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "_comment": "FOR DETAILED FORMAT LOOK AT https://docs.docker.com/reference/api/docker_remote_api_v1.16/#create-a-container", - "AttachStdin": true, - "OpenStdin": true, - "HostConfig": { - "PortBindings":{ "8080/tcp": [{ "HostIp": "0.0.0.0", "HostPort": "18080" }] } - } -} \ No newline at end of file diff --git a/ijs.tree b/ijs.tree new file mode 100644 index 000000000..85fe90059 --- /dev/null +++ b/ijs.tree @@ -0,0 +1,354 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/basics/getting_started/deploying_plugin/img/jar_location.png b/images/basics/getting_started/deploying_plugin/img/jar_location.png similarity index 100% rename from basics/getting_started/deploying_plugin/img/jar_location.png rename to images/basics/getting_started/deploying_plugin/img/jar_location.png diff --git a/basics/getting_started/deploying_plugin/img/jar_saved_notification.png b/images/basics/getting_started/deploying_plugin/img/jar_saved_notification.png similarity index 100% rename from basics/getting_started/deploying_plugin/img/jar_saved_notification.png rename to images/basics/getting_started/deploying_plugin/img/jar_saved_notification.png diff --git a/basics/getting_started/deploying_plugin/img/prepare_plugin_for_deployment.png b/images/basics/getting_started/deploying_plugin/img/prepare_plugin_for_deployment.png similarity index 100% rename from basics/getting_started/deploying_plugin/img/prepare_plugin_for_deployment.png rename to images/basics/getting_started/deploying_plugin/img/prepare_plugin_for_deployment.png diff --git a/basics/getting_started/img/add_sourcepath.png b/images/basics/getting_started/img/add_sourcepath.png similarity index 100% rename from basics/getting_started/img/add_sourcepath.png rename to images/basics/getting_started/img/add_sourcepath.png diff --git a/basics/getting_started/img/community_sources_directory.png b/images/basics/getting_started/img/community_sources_directory.png similarity index 100% rename from basics/getting_started/img/community_sources_directory.png rename to images/basics/getting_started/img/community_sources_directory.png diff --git a/basics/getting_started/img/create_intellij_idea_sdk.png b/images/basics/getting_started/img/create_intellij_idea_sdk.png similarity index 100% rename from basics/getting_started/img/create_intellij_idea_sdk.png rename to images/basics/getting_started/img/create_intellij_idea_sdk.png diff --git a/basics/getting_started/img/intellij_platform_plugin_module.png b/images/basics/getting_started/img/intellij_platform_plugin_module.png similarity index 100% rename from basics/getting_started/img/intellij_platform_plugin_module.png rename to images/basics/getting_started/img/intellij_platform_plugin_module.png diff --git a/basics/getting_started/img/new_action_page.png b/images/basics/getting_started/img/new_action_page.png similarity index 100% rename from basics/getting_started/img/new_action_page.png rename to images/basics/getting_started/img/new_action_page.png diff --git a/basics/getting_started/img/new_action_template.png b/images/basics/getting_started/img/new_action_template.png similarity index 100% rename from basics/getting_started/img/new_action_template.png rename to images/basics/getting_started/img/new_action_template.png diff --git a/basics/getting_started/img/new_project_wizard.png b/images/basics/getting_started/img/new_project_wizard.png similarity index 100% rename from basics/getting_started/img/new_project_wizard.png rename to images/basics/getting_started/img/new_project_wizard.png diff --git a/basics/getting_started/img/php_prj_libs.png b/images/basics/getting_started/img/php_prj_libs.png similarity index 100% rename from basics/getting_started/img/php_prj_libs.png rename to images/basics/getting_started/img/php_prj_libs.png diff --git a/basics/getting_started/img/plugins-sandbox.png b/images/basics/getting_started/img/plugins-sandbox.png similarity index 100% rename from basics/getting_started/img/plugins-sandbox.png rename to images/basics/getting_started/img/plugins-sandbox.png diff --git a/basics/getting_started/img/sample_menu.jpg b/images/basics/getting_started/img/sample_menu.jpg similarity index 100% rename from basics/getting_started/img/sample_menu.jpg rename to images/basics/getting_started/img/sample_menu.jpg diff --git a/basics/getting_started/img/set_home_directory.png b/images/basics/getting_started/img/set_home_directory.png similarity index 100% rename from basics/getting_started/img/set_home_directory.png rename to images/basics/getting_started/img/set_home_directory.png diff --git a/basics/getting_started/img/set_idea_jdk.png b/images/basics/getting_started/img/set_idea_jdk.png similarity index 100% rename from basics/getting_started/img/set_idea_jdk.png rename to images/basics/getting_started/img/set_idea_jdk.png diff --git a/basics/getting_started/img/set_java_sdk.png b/images/basics/getting_started/img/set_java_sdk.png similarity index 100% rename from basics/getting_started/img/set_java_sdk.png rename to images/basics/getting_started/img/set_java_sdk.png diff --git a/basics/getting_started/img/set_plugin_module_sdk.png b/images/basics/getting_started/img/set_plugin_module_sdk.png similarity index 100% rename from basics/getting_started/img/set_plugin_module_sdk.png rename to images/basics/getting_started/img/set_plugin_module_sdk.png diff --git a/basics/img/ant_build_xml.png b/images/basics/img/ant_build_xml.png similarity index 100% rename from basics/img/ant_build_xml.png rename to images/basics/img/ant_build_xml.png diff --git a/basics/img/check_out_community.png b/images/basics/img/check_out_community.png similarity index 100% rename from basics/img/check_out_community.png rename to images/basics/img/check_out_community.png diff --git a/basics/img/classes.png b/images/basics/img/classes.png similarity index 100% rename from basics/img/classes.png rename to images/basics/img/classes.png diff --git a/basics/img/configure_sdk.png b/images/basics/img/configure_sdk.png similarity index 100% rename from basics/img/configure_sdk.png rename to images/basics/img/configure_sdk.png diff --git a/basics/img/create-1.png b/images/basics/img/create-1.png similarity index 100% rename from basics/img/create-1.png rename to images/basics/img/create-1.png diff --git a/basics/img/create-2.png b/images/basics/img/create-2.png similarity index 100% rename from basics/img/create-2.png rename to images/basics/img/create-2.png diff --git a/basics/img/create-3.png b/images/basics/img/create-3.png similarity index 100% rename from basics/img/create-3.png rename to images/basics/img/create-3.png diff --git a/basics/img/idea_run_configuration.png b/images/basics/img/idea_run_configuration.png similarity index 100% rename from basics/img/idea_run_configuration.png rename to images/basics/img/idea_run_configuration.png diff --git a/basics/img/tools_jar.png b/images/basics/img/tools_jar.png similarity index 100% rename from basics/img/tools_jar.png rename to images/basics/img/tools_jar.png diff --git a/basics/plugin_structure/img/circle_logo.png b/images/basics/plugin_structure/img/circle_logo.png similarity index 100% rename from basics/plugin_structure/img/circle_logo.png rename to images/basics/plugin_structure/img/circle_logo.png diff --git a/basics/plugin_structure/img/dark_bad.png b/images/basics/plugin_structure/img/dark_bad.png similarity index 100% rename from basics/plugin_structure/img/dark_bad.png rename to images/basics/plugin_structure/img/dark_bad.png diff --git a/basics/plugin_structure/img/dark_good.png b/images/basics/plugin_structure/img/dark_good.png similarity index 100% rename from basics/plugin_structure/img/dark_good.png rename to images/basics/plugin_structure/img/dark_good.png diff --git a/basics/plugin_structure/img/icon_size.png b/images/basics/plugin_structure/img/icon_size.png similarity index 100% rename from basics/plugin_structure/img/icon_size.png rename to images/basics/plugin_structure/img/icon_size.png diff --git a/basics/plugin_structure/img/keymap_logo.png b/images/basics/plugin_structure/img/keymap_logo.png similarity index 100% rename from basics/plugin_structure/img/keymap_logo.png rename to images/basics/plugin_structure/img/keymap_logo.png diff --git a/basics/plugin_structure/img/light_version.png b/images/basics/plugin_structure/img/light_version.png similarity index 100% rename from basics/plugin_structure/img/light_version.png rename to images/basics/plugin_structure/img/light_version.png diff --git a/basics/plugin_structure/img/plugin_prefs.png b/images/basics/plugin_structure/img/plugin_prefs.png similarity index 100% rename from basics/plugin_structure/img/plugin_prefs.png rename to images/basics/plugin_structure/img/plugin_prefs.png diff --git a/basics/plugin_structure/img/rectangle_horizontal.png b/images/basics/plugin_structure/img/rectangle_horizontal.png similarity index 100% rename from basics/plugin_structure/img/rectangle_horizontal.png rename to images/basics/plugin_structure/img/rectangle_horizontal.png diff --git a/basics/plugin_structure/img/rectangle_vertical.png b/images/basics/plugin_structure/img/rectangle_vertical.png similarity index 100% rename from basics/plugin_structure/img/rectangle_vertical.png rename to images/basics/plugin_structure/img/rectangle_vertical.png diff --git a/basics/plugin_structure/img/resource_directory_structure.png b/images/basics/plugin_structure/img/resource_directory_structure.png similarity index 100% rename from basics/plugin_structure/img/resource_directory_structure.png rename to images/basics/plugin_structure/img/resource_directory_structure.png diff --git a/basics/plugin_structure/img/square_logo.png b/images/basics/plugin_structure/img/square_logo.png similarity index 100% rename from basics/plugin_structure/img/square_logo.png rename to images/basics/plugin_structure/img/square_logo.png diff --git a/basics/plugin_structure/img/yt_logo.png b/images/basics/plugin_structure/img/yt_logo.png similarity index 100% rename from basics/plugin_structure/img/yt_logo.png rename to images/basics/plugin_structure/img/yt_logo.png diff --git a/basics/project_structure/img/IntelliJIDEA_ProjectStructure.png b/images/basics/project_structure/img/IntelliJIDEA_ProjectStructure.png similarity index 100% rename from basics/project_structure/img/IntelliJIDEA_ProjectStructure.png rename to images/basics/project_structure/img/IntelliJIDEA_ProjectStructure.png diff --git a/images/info b/images/info new file mode 100644 index 000000000..dd201bc8a --- /dev/null +++ b/images/info @@ -0,0 +1 @@ +Store your code snippets here \ No newline at end of file diff --git a/products/img/android_studio_build.png b/images/products/img/android_studio_build.png similarity index 100% rename from products/img/android_studio_build.png rename to images/products/img/android_studio_build.png diff --git a/products/img/phpstorm_build.png b/images/products/img/phpstorm_build.png similarity index 100% rename from products/img/phpstorm_build.png rename to images/products/img/phpstorm_build.png diff --git a/reference_guide/custom_language_support/img/PsiBuilder.gif b/images/reference_guide/custom_language_support/img/PsiBuilder.gif similarity index 100% rename from reference_guide/custom_language_support/img/PsiBuilder.gif rename to images/reference_guide/custom_language_support/img/PsiBuilder.gif diff --git a/reference_guide/frameworks_and_external_apis/img/xml_dom_api/booleancontrol.gif b/images/reference_guide/frameworks_and_external_apis/img/xml_dom_api/booleancontrol.gif similarity index 100% rename from reference_guide/frameworks_and_external_apis/img/xml_dom_api/booleancontrol.gif rename to images/reference_guide/frameworks_and_external_apis/img/xml_dom_api/booleancontrol.gif diff --git a/reference_guide/frameworks_and_external_apis/img/xml_dom_api/collectioncontrol.gif b/images/reference_guide/frameworks_and_external_apis/img/xml_dom_api/collectioncontrol.gif similarity index 100% rename from reference_guide/frameworks_and_external_apis/img/xml_dom_api/collectioncontrol.gif rename to images/reference_guide/frameworks_and_external_apis/img/xml_dom_api/collectioncontrol.gif diff --git a/reference_guide/frameworks_and_external_apis/img/xml_dom_api/combocontrol.gif b/images/reference_guide/frameworks_and_external_apis/img/xml_dom_api/combocontrol.gif similarity index 100% rename from reference_guide/frameworks_and_external_apis/img/xml_dom_api/combocontrol.gif rename to images/reference_guide/frameworks_and_external_apis/img/xml_dom_api/combocontrol.gif diff --git a/reference_guide/frameworks_and_external_apis/img/xml_dom_api/psiclasscontrol.gif b/images/reference_guide/frameworks_and_external_apis/img/xml_dom_api/psiclasscontrol.gif similarity index 100% rename from reference_guide/frameworks_and_external_apis/img/xml_dom_api/psiclasscontrol.gif rename to images/reference_guide/frameworks_and_external_apis/img/xml_dom_api/psiclasscontrol.gif diff --git a/reference_guide/img/bus.png b/images/reference_guide/img/bus.png similarity index 100% rename from reference_guide/img/bus.png rename to images/reference_guide/img/bus.png diff --git a/reference_guide/img/configurable.png b/images/reference_guide/img/configurable.png similarity index 100% rename from reference_guide/img/configurable.png rename to images/reference_guide/img/configurable.png diff --git a/reference_guide/img/connection.svg b/images/reference_guide/img/connection.svg similarity index 100% rename from reference_guide/img/connection.svg rename to images/reference_guide/img/connection.svg diff --git a/reference_guide/img/data-node-example.png b/images/reference_guide/img/data-node-example.png similarity index 100% rename from reference_guide/img/data-node-example.png rename to images/reference_guide/img/data-node-example.png diff --git a/reference_guide/img/data-node.png b/images/reference_guide/img/data-node.png similarity index 100% rename from reference_guide/img/data-node.png rename to images/reference_guide/img/data-node.png diff --git a/reference_guide/img/import.png b/images/reference_guide/img/import.png similarity index 100% rename from reference_guide/img/import.png rename to images/reference_guide/img/import.png diff --git a/reference_guide/img/nested_config.svg b/images/reference_guide/img/nested_config.svg similarity index 100% rename from reference_guide/img/nested_config.svg rename to images/reference_guide/img/nested_config.svg diff --git a/reference_guide/img/parent_child_broadcast.svg b/images/reference_guide/img/parent_child_broadcast.svg similarity index 100% rename from reference_guide/img/parent_child_broadcast.svg rename to images/reference_guide/img/parent_child_broadcast.svg diff --git a/reference_guide/img/publish.svg b/images/reference_guide/img/publish.svg similarity index 100% rename from reference_guide/img/publish.svg rename to images/reference_guide/img/publish.svg diff --git a/reference_guide/img/standard_hierarchy.svg b/images/reference_guide/img/standard_hierarchy.svg similarity index 100% rename from reference_guide/img/standard_hierarchy.svg rename to images/reference_guide/img/standard_hierarchy.svg diff --git a/reference_guide/img/subscribe.svg b/images/reference_guide/img/subscribe.svg similarity index 100% rename from reference_guide/img/subscribe.svg rename to images/reference_guide/img/subscribe.svg diff --git a/reference_guide/img/toolWindowStructure.png b/images/reference_guide/img/toolWindowStructure.png similarity index 100% rename from reference_guide/img/toolWindowStructure.png rename to images/reference_guide/img/toolWindowStructure.png diff --git a/reference_guide/img/toolWindowStructure@2x.png b/images/reference_guide/img/toolWindowStructure@2x.png similarity index 100% rename from reference_guide/img/toolWindowStructure@2x.png rename to images/reference_guide/img/toolWindowStructure@2x.png diff --git a/reference_guide/img/toolWindowStructure@2x_dark.png b/images/reference_guide/img/toolWindowStructure@2x_dark.png similarity index 100% rename from reference_guide/img/toolWindowStructure@2x_dark.png rename to images/reference_guide/img/toolWindowStructure@2x_dark.png diff --git a/reference_guide/img/toolWindowStructure_dark.png b/images/reference_guide/img/toolWindowStructure_dark.png similarity index 100% rename from reference_guide/img/toolWindowStructure_dark.png rename to images/reference_guide/img/toolWindowStructure_dark.png diff --git a/reference_guide/img/topic.png b/images/reference_guide/img/topic.png similarity index 100% rename from reference_guide/img/topic.png rename to images/reference_guide/img/topic.png diff --git a/reference_guide/img/topic.svg b/images/reference_guide/img/topic.svg similarity index 100% rename from reference_guide/img/topic.svg rename to images/reference_guide/img/topic.svg diff --git a/reference_guide/internal_actions/img/internal_lafd_win.png b/images/reference_guide/internal_actions/img/internal_lafd_win.png similarity index 100% rename from reference_guide/internal_actions/img/internal_lafd_win.png rename to images/reference_guide/internal_actions/img/internal_lafd_win.png diff --git a/reference_guide/internal_actions/img/internal_uii_icon_info.png b/images/reference_guide/internal_actions/img/internal_uii_icon_info.png similarity index 100% rename from reference_guide/internal_actions/img/internal_uii_icon_info.png rename to images/reference_guide/internal_actions/img/internal_uii_icon_info.png diff --git a/reference_guide/ui_themes/img/devkit_wiz_action.png b/images/reference_guide/ui_themes/img/devkit_wiz_action.png similarity index 100% rename from reference_guide/ui_themes/img/devkit_wiz_action.png rename to images/reference_guide/ui_themes/img/devkit_wiz_action.png diff --git a/reference_guide/ui_themes/img/devkit_wiz_dialog.png b/images/reference_guide/ui_themes/img/devkit_wiz_dialog.png similarity index 100% rename from reference_guide/ui_themes/img/devkit_wiz_dialog.png rename to images/reference_guide/ui_themes/img/devkit_wiz_dialog.png diff --git a/reference_guide/ui_themes/img/keys-naming.png b/images/reference_guide/ui_themes/img/keys-naming.png similarity index 100% rename from reference_guide/ui_themes/img/keys-naming.png rename to images/reference_guide/ui_themes/img/keys-naming.png diff --git a/reference_guide/ui_themes/img/theme_colorpalette_popup.png b/images/reference_guide/ui_themes/img/theme_colorpalette_popup.png similarity index 100% rename from reference_guide/ui_themes/img/theme_colorpalette_popup.png rename to images/reference_guide/ui_themes/img/theme_colorpalette_popup.png diff --git a/reference_guide/ui_themes/img/theme_components.png b/images/reference_guide/ui_themes/img/theme_components.png similarity index 100% rename from reference_guide/ui_themes/img/theme_components.png rename to images/reference_guide/ui_themes/img/theme_components.png diff --git a/reference_guide/ui_themes/img/uit_control_complete.png b/images/reference_guide/ui_themes/img/uit_control_complete.png similarity index 100% rename from reference_guide/ui_themes/img/uit_control_complete.png rename to images/reference_guide/ui_themes/img/uit_control_complete.png diff --git a/tutorials/action_system/img/action_never_used.png b/images/tutorials/action_system/img/action_never_used.png similarity index 100% rename from tutorials/action_system/img/action_never_used.png rename to images/tutorials/action_system/img/action_never_used.png diff --git a/tutorials/action_system/img/action_performed.png b/images/tutorials/action_system/img/action_performed.png similarity index 100% rename from tutorials/action_system/img/action_performed.png rename to images/tutorials/action_system/img/action_performed.png diff --git a/tutorials/action_system/img/dynamic_action_group.png b/images/tutorials/action_system/img/dynamic_action_group.png similarity index 100% rename from tutorials/action_system/img/dynamic_action_group.png rename to images/tutorials/action_system/img/dynamic_action_group.png diff --git a/tutorials/action_system/img/editor_popup_menu.png b/images/tutorials/action_system/img/editor_popup_menu.png similarity index 100% rename from tutorials/action_system/img/editor_popup_menu.png rename to images/tutorials/action_system/img/editor_popup_menu.png diff --git a/tutorials/action_system/img/find_action.png b/images/tutorials/action_system/img/find_action.png similarity index 100% rename from tutorials/action_system/img/find_action.png rename to images/tutorials/action_system/img/find_action.png diff --git a/tutorials/action_system/img/grouped_action.png b/images/tutorials/action_system/img/grouped_action.png similarity index 100% rename from tutorials/action_system/img/grouped_action.png rename to images/tutorials/action_system/img/grouped_action.png diff --git a/tutorials/action_system/img/new_action.png b/images/tutorials/action_system/img/new_action.png similarity index 100% rename from tutorials/action_system/img/new_action.png rename to images/tutorials/action_system/img/new_action.png diff --git a/tutorials/action_system/img/register_action.png b/images/tutorials/action_system/img/register_action.png similarity index 100% rename from tutorials/action_system/img/register_action.png rename to images/tutorials/action_system/img/register_action.png diff --git a/tutorials/action_system/img/register_group.png b/images/tutorials/action_system/img/register_group.png similarity index 100% rename from tutorials/action_system/img/register_group.png rename to images/tutorials/action_system/img/register_group.png diff --git a/tutorials/action_system/img/tools_menu_item_action.png b/images/tutorials/action_system/img/tools_menu_item_action.png similarity index 100% rename from tutorials/action_system/img/tools_menu_item_action.png rename to images/tutorials/action_system/img/tools_menu_item_action.png diff --git a/tutorials/build_system/img/gradle_tasks_in_tool_window.png b/images/tutorials/build_system/img/gradle_tasks_in_tool_window.png similarity index 100% rename from tutorials/build_system/img/gradle_tasks_in_tool_window.png rename to images/tutorials/build_system/img/gradle_tasks_in_tool_window.png diff --git a/tutorials/build_system/img/step1_new_gradle_project.png b/images/tutorials/build_system/img/step1_new_gradle_project.png similarity index 100% rename from tutorials/build_system/img/step1_new_gradle_project.png rename to images/tutorials/build_system/img/step1_new_gradle_project.png diff --git a/tutorials/custom_language_support/img/annotator.png b/images/tutorials/custom_language_support/img/annotator.png similarity index 100% rename from tutorials/custom_language_support/img/annotator.png rename to images/tutorials/custom_language_support/img/annotator.png diff --git a/tutorials/custom_language_support/img/code_style_settings.png b/images/tutorials/custom_language_support/img/code_style_settings.png similarity index 100% rename from tutorials/custom_language_support/img/code_style_settings.png rename to images/tutorials/custom_language_support/img/code_style_settings.png diff --git a/tutorials/custom_language_support/img/color_settings_page.png b/images/tutorials/custom_language_support/img/color_settings_page.png similarity index 100% rename from tutorials/custom_language_support/img/color_settings_page.png rename to images/tutorials/custom_language_support/img/color_settings_page.png diff --git a/tutorials/custom_language_support/img/commenter.png b/images/tutorials/custom_language_support/img/commenter.png similarity index 100% rename from tutorials/custom_language_support/img/commenter.png rename to images/tutorials/custom_language_support/img/commenter.png diff --git a/tutorials/custom_language_support/img/completion.png b/images/tutorials/custom_language_support/img/completion.png similarity index 100% rename from tutorials/custom_language_support/img/completion.png rename to images/tutorials/custom_language_support/img/completion.png diff --git a/tutorials/custom_language_support/img/file_type_factory.png b/images/tutorials/custom_language_support/img/file_type_factory.png similarity index 100% rename from tutorials/custom_language_support/img/file_type_factory.png rename to images/tutorials/custom_language_support/img/file_type_factory.png diff --git a/tutorials/custom_language_support/img/find_usages.png b/images/tutorials/custom_language_support/img/find_usages.png similarity index 100% rename from tutorials/custom_language_support/img/find_usages.png rename to images/tutorials/custom_language_support/img/find_usages.png diff --git a/tutorials/custom_language_support/img/folding.png b/images/tutorials/custom_language_support/img/folding.png similarity index 100% rename from tutorials/custom_language_support/img/folding.png rename to images/tutorials/custom_language_support/img/folding.png diff --git a/tutorials/custom_language_support/img/formatter.png b/images/tutorials/custom_language_support/img/formatter.png similarity index 100% rename from tutorials/custom_language_support/img/formatter.png rename to images/tutorials/custom_language_support/img/formatter.png diff --git a/tutorials/custom_language_support/img/generated_parser.png b/images/tutorials/custom_language_support/img/generated_parser.png similarity index 100% rename from tutorials/custom_language_support/img/generated_parser.png rename to images/tutorials/custom_language_support/img/generated_parser.png diff --git a/tutorials/custom_language_support/img/go_to_symbol.png b/images/tutorials/custom_language_support/img/go_to_symbol.png similarity index 100% rename from tutorials/custom_language_support/img/go_to_symbol.png rename to images/tutorials/custom_language_support/img/go_to_symbol.png diff --git a/tutorials/custom_language_support/img/in_place_rename.png b/images/tutorials/custom_language_support/img/in_place_rename.png similarity index 100% rename from tutorials/custom_language_support/img/in_place_rename.png rename to images/tutorials/custom_language_support/img/in_place_rename.png diff --git a/tutorials/custom_language_support/img/line_marker.png b/images/tutorials/custom_language_support/img/line_marker.png similarity index 100% rename from tutorials/custom_language_support/img/line_marker.png rename to images/tutorials/custom_language_support/img/line_marker.png diff --git a/tutorials/custom_language_support/img/line_marker_location.png b/images/tutorials/custom_language_support/img/line_marker_location.png similarity index 100% rename from tutorials/custom_language_support/img/line_marker_location.png rename to images/tutorials/custom_language_support/img/line_marker_location.png diff --git a/tutorials/custom_language_support/img/new_property.png b/images/tutorials/custom_language_support/img/new_property.png similarity index 100% rename from tutorials/custom_language_support/img/new_property.png rename to images/tutorials/custom_language_support/img/new_property.png diff --git a/tutorials/custom_language_support/img/psi_elements.png b/images/tutorials/custom_language_support/img/psi_elements.png similarity index 100% rename from tutorials/custom_language_support/img/psi_elements.png rename to images/tutorials/custom_language_support/img/psi_elements.png diff --git a/tutorials/custom_language_support/img/quick_fix.png b/images/tutorials/custom_language_support/img/quick_fix.png similarity index 100% rename from tutorials/custom_language_support/img/quick_fix.png rename to images/tutorials/custom_language_support/img/quick_fix.png diff --git a/tutorials/custom_language_support/img/reference_contributor.png b/images/tutorials/custom_language_support/img/reference_contributor.png similarity index 100% rename from tutorials/custom_language_support/img/reference_contributor.png rename to images/tutorials/custom_language_support/img/reference_contributor.png diff --git a/tutorials/custom_language_support/img/rename.png b/images/tutorials/custom_language_support/img/rename.png similarity index 100% rename from tutorials/custom_language_support/img/rename.png rename to images/tutorials/custom_language_support/img/rename.png diff --git a/tutorials/custom_language_support/img/structure_view.png b/images/tutorials/custom_language_support/img/structure_view.png similarity index 100% rename from tutorials/custom_language_support/img/structure_view.png rename to images/tutorials/custom_language_support/img/structure_view.png diff --git a/tutorials/custom_language_support/img/syntax_highlighter.png b/images/tutorials/custom_language_support/img/syntax_highlighter.png similarity index 100% rename from tutorials/custom_language_support/img/syntax_highlighter.png rename to images/tutorials/custom_language_support/img/syntax_highlighter.png diff --git a/tutorials/custom_language_support/img/unresolved_property.png b/images/tutorials/custom_language_support/img/unresolved_property.png similarity index 100% rename from tutorials/custom_language_support/img/unresolved_property.png rename to images/tutorials/custom_language_support/img/unresolved_property.png diff --git a/tutorials/editor_basics/img/basics.png b/images/tutorials/editor_basics/img/basics.png similarity index 100% rename from tutorials/editor_basics/img/basics.png rename to images/tutorials/editor_basics/img/basics.png diff --git a/tutorials/editor_basics/img/caret_col_pos_block.png b/images/tutorials/editor_basics/img/caret_col_pos_block.png similarity index 100% rename from tutorials/editor_basics/img/caret_col_pos_block.png rename to images/tutorials/editor_basics/img/caret_col_pos_block.png diff --git a/tutorials/editor_basics/img/caret_offset_l2.png b/images/tutorials/editor_basics/img/caret_offset_l2.png similarity index 100% rename from tutorials/editor_basics/img/caret_offset_l2.png rename to images/tutorials/editor_basics/img/caret_offset_l2.png diff --git a/tutorials/editor_basics/img/editor_coords.png b/images/tutorials/editor_basics/img/editor_coords.png similarity index 100% rename from tutorials/editor_basics/img/editor_coords.png rename to images/tutorials/editor_basics/img/editor_coords.png diff --git a/tutorials/editor_basics/img/logical_pos_folded.png b/images/tutorials/editor_basics/img/logical_pos_folded.png similarity index 100% rename from tutorials/editor_basics/img/logical_pos_folded.png rename to images/tutorials/editor_basics/img/logical_pos_folded.png diff --git a/tutorials/editor_basics/img/vis_pos_soft_wrap.png b/images/tutorials/editor_basics/img/vis_pos_soft_wrap.png similarity index 100% rename from tutorials/editor_basics/img/vis_pos_soft_wrap.png rename to images/tutorials/editor_basics/img/vis_pos_soft_wrap.png diff --git a/tutorials/framework/img/custom_framework.png b/images/tutorials/framework/img/custom_framework.png similarity index 100% rename from tutorials/framework/img/custom_framework.png rename to images/tutorials/framework/img/custom_framework.png diff --git a/tutorials/img/IntentionsList.png b/images/tutorials/img/IntentionsList.png similarity index 100% rename from tutorials/img/IntentionsList.png rename to images/tutorials/img/IntentionsList.png diff --git a/tutorials/img/TernaryOperator.png b/images/tutorials/img/TernaryOperator.png similarity index 100% rename from tutorials/img/TernaryOperator.png rename to images/tutorials/img/TernaryOperator.png diff --git a/tutorials/img/comparingReferences.png b/images/tutorials/img/comparingReferences.png similarity index 100% rename from tutorials/img/comparingReferences.png rename to images/tutorials/img/comparingReferences.png diff --git a/tutorials/img/comparingReferences_options.png b/images/tutorials/img/comparingReferences_options.png similarity index 100% rename from tutorials/img/comparingReferences_options.png rename to images/tutorials/img/comparingReferences_options.png diff --git a/tutorials/img/settings_defaults.png b/images/tutorials/img/settings_defaults.png similarity index 100% rename from tutorials/img/settings_defaults.png rename to images/tutorials/img/settings_defaults.png diff --git a/tutorials/img/settings_persisted.png b/images/tutorials/img/settings_persisted.png similarity index 100% rename from tutorials/img/settings_persisted.png rename to images/tutorials/img/settings_persisted.png diff --git a/tutorials/live_templates/img/applied_titleCase.png b/images/tutorials/live_templates/img/applied_titleCase.png similarity index 100% rename from tutorials/live_templates/img/applied_titleCase.png rename to images/tutorials/live_templates/img/applied_titleCase.png diff --git a/tutorials/live_templates/img/invoke_titleCase.png b/images/tutorials/live_templates/img/invoke_titleCase.png similarity index 100% rename from tutorials/live_templates/img/invoke_titleCase.png rename to images/tutorials/live_templates/img/invoke_titleCase.png diff --git a/tutorials/project_wizard/img/empty_project.png b/images/tutorials/project_wizard/img/empty_project.png similarity index 100% rename from tutorials/project_wizard/img/empty_project.png rename to images/tutorials/project_wizard/img/empty_project.png diff --git a/tutorials/project_wizard/img/extra_step.png b/images/tutorials/project_wizard/img/extra_step.png similarity index 100% rename from tutorials/project_wizard/img/extra_step.png rename to images/tutorials/project_wizard/img/extra_step.png diff --git a/tutorials/project_wizard/module_types/img/new_module_type.png b/images/tutorials/project_wizard/module_types/img/new_module_type.png similarity index 100% rename from tutorials/project_wizard/module_types/img/new_module_type.png rename to images/tutorials/project_wizard/module_types/img/new_module_type.png diff --git a/tutorials/run_configurations/img/new_run_configuration.png b/images/tutorials/run_configurations/img/new_run_configuration.png similarity index 100% rename from tutorials/run_configurations/img/new_run_configuration.png rename to images/tutorials/run_configurations/img/new_run_configuration.png diff --git a/tutorials/run_configurations/img/ui_form.png b/images/tutorials/run_configurations/img/ui_form.png similarity index 100% rename from tutorials/run_configurations/img/ui_form.png rename to images/tutorials/run_configurations/img/ui_form.png diff --git a/tutorials/tree_structure_view/img/text_only.png b/images/tutorials/tree_structure_view/img/text_only.png similarity index 100% rename from tutorials/tree_structure_view/img/text_only.png rename to images/tutorials/tree_structure_view/img/text_only.png diff --git a/tutorials/writing_tests_for_plugins/img/plugin_copy_psi.png b/images/tutorials/writing_tests_for_plugins/img/plugin_copy_psi.png similarity index 100% rename from tutorials/writing_tests_for_plugins/img/plugin_copy_psi.png rename to images/tutorials/writing_tests_for_plugins/img/plugin_copy_psi.png diff --git a/user_interface_components/img/sample_calendar.png b/images/user_interface_components/img/sample_calendar.png similarity index 100% rename from user_interface_components/img/sample_calendar.png rename to images/user_interface_components/img/sample_calendar.png diff --git a/intro/content_updates.md b/intro/content_updates.md deleted file mode 100644 index 403d51aae..000000000 --- a/intro/content_updates.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: Content Updates ---- - -This page lists notable additions and updates to the SDK documentation and code samples. - -Follow [JBPlatform](https://twitter.com/JBPlatform/) on Twitter and visit [JetBrains Platform Blog](https://blog.jetbrains.com/platform/) for the latest announcements. - -See [Recently Updated](/recently_updated.md) ([RSS](https://github.com/JetBrains/intellij-sdk-docs/commits/master.atom)) for a detailed changelog. - -## 2020 - -### December - -IntelliJ Platform Explorer -: Explore usages of [Extension Points](/appendix/resources/extension_point_list.md) in open-source plugins using [IntelliJ Platform Explorer](https://jb.gg/ipe). - -### November - -Extension Point List -: All EPs [available in IJ Platform and Android](/appendix/resources/extension_point_list.md) can now be browsed conveniently. - -### August - -README added to Code Samples -: All code samples used in this guide now come with `README` making it easier to browse them. They can be conveniently accessed via a [separate GitHub repository](https://github.com/JetBrains/intellij-sdk-code-samples). - -### June - -Dynamic Plugins update -: Added new sections _Code_ and _Troubleshooting_ to [Dynamic Plugins](/basics/plugin_structure/dynamic_plugins.md). - -GitHub IntelliJ Platform Plugin Template -: Create new plugins with a preconfigured project scaffold and CI in [one click](/tutorials/github_template.md). - -Disposer & Disposable -: Added [reference](/basics/disposers.md) discussing resource cleanup/management. - -### May - -Settings (Preferences) -: Added [guide](/reference_guide/settings_guide.md) and [tutorial](/tutorials/settings_tutorial.md) on integrating with IDE Settings dialog. - -UI Inspector -: Inspect Swing components and associated data (like `AnAction` for menu item) using the [UI Inspector](/reference_guide/internal_actions/internal_ui_inspector.md). - -### March - -JCEF Support (_Experimental Feature_) -: Allows [embedding](/reference_guide/jcef.md) Chromium-based browser in the IDE. - -### February - -All Code Samples converted to Gradle -: [All samples](https://github.com/JetBrains/intellij-sdk-code-samples) now use the [recommended solution](/tutorials/build_system.md) of setting up plugin projects. - -### January - -Custom Language Support Tutorial converted to Gradle -: The [corresponding tutorial](/tutorials/custom_language_support_tutorial.md) and [Testing a Custom Language Plugin](/tutorials/writing_tests_for_plugins.md) have been updated and enhanced as well. - -Targeting specific IDEs -: [Part VIII - Product Specific](/basics/getting_started/plugin_compatibility.md) has been expanded massively, now also covering each IDE with its own dedicated page. - -## 2019 - -### December - -Dynamic Plugins support -: Added starting point [Dynamic Plugins](/basics/plugin_structure/dynamic_plugins.md) for migrating plugins (IntelliJ Platform 2020.1 and later). - -Plugin Components migration -: Components being a legacy feature, the [updated page](/basics/plugin_structure/plugin_components.md) describes migrating them to modern replacement API. - -### October - -Part X - Plugin Repository moved -: All contents have been moved to [JetBrains Marketplace](https://plugins.jetbrains.com/docs/marketplace/about-marketplace.html) documentation. - -### July - -New page: Optimizing Performance -: [How to improve performance](/reference_guide/performance/performance.md) working with PSI, indexing, and avoiding UI freezes. - -### May - -New Page: Kotlin UI DSL -: [Describes preferred way](/user_interface_components/kotlin_ui_dsl.md) of building UI/dialogs for IntelliJ Platform 2019.2 and later. diff --git a/products/idea.md b/products/idea.md deleted file mode 100644 index 4152e0e34..000000000 --- a/products/idea.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: IntelliJ IDEA ---- - - -> **TIP** Qualifying Open Source projects can [apply for free licenses](https://www.jetbrains.com/community/opensource/) of JetBrains products. - -Please see "Java" entry in table [Modules Specific to Functionality](/basics/getting_started/plugin_compatibility.md#modules-specific-to-functionality) on how to use Java specific functionality. - -* [Tomcat Integration](../reference_guide/tomcat_integration.md) -* [Spring API](../reference_guide/frameworks_and_external_apis/spring_api.md) diff --git a/project.ihp b/project.ihp new file mode 100644 index 000000000..9ed4e9a3c --- /dev/null +++ b/project.ihp @@ -0,0 +1,15 @@ + + + + + LOWER_CASE_DASHES_DOT_REMOVE + + + + + + + + + \ No newline at end of file diff --git a/reference_guide/api_changes_list.md b/reference_guide/api_changes_list.md index ac0f87688..9d8642060 100644 --- a/reference_guide/api_changes_list.md +++ b/reference_guide/api_changes_list.md @@ -1,6 +1,5 @@ ---- -title: Incompatible Changes in IntelliJ Platform and Plugins API ---- +[//]: # (title: Incompatible Changes in IntelliJ Platform and Plugins API) + - ## Verifying Compatibility ### Plugin Verifier @@ -74,7 +68,7 @@ Compatibility with newer IDEs can easily be verified for plugins hosted on the [ For local verification or non-public plugins, [intellij-plugin-verifier](https://github.com/JetBrains/intellij-plugin-verifier) can be used standalone as well. -Integration in [Gradle build](/tutorials/build_system.md) is possible using the `runPluginVerifier` task, please see [Gradle IntelliJ Plugin - Plugin Verifier DSL](https://github.com/JetBrains/gradle-intellij-plugin#plugin-verifier-dsl) for details. +Integration in [Gradle build](gradle_build_system.md) is possible using the `runPluginVerifier` task, please see [Gradle IntelliJ Plugin - Plugin Verifier DSL](https://github.com/JetBrains/gradle-intellij-plugin#plugin-verifier-dsl) for details. You can easily integrate it within your CI by running that task as another quality check step. Check the IntelliJ Platform Plugin Template [GitHub workflow configuration file](https://github.com/JetBrains/intellij-platform-plugin-template/blob/main/.github/workflows/build.yml) as sample. @@ -88,18 +82,18 @@ Consider using the following [IDE inspections](https://www.jetbrains.com/help/id - JVM languages \| Unstable API Usage - JVM languages \| Unstable type is used in signature - ## Known Breaking Changes -> **TIP** Follow [JBPlatform](https://twitter.com/JBPlatform/) on Twitter and visit [JetBrains Platform Blog](https://blog.jetbrains.com/platform/) for the latest announcements. + > Follow [JBPlatform](https://twitter.com/JBPlatform/) on Twitter and visit [JetBrains Platform Blog](https://blog.jetbrains.com/platform/) for the latest announcements. + > + {type="tip"} The following pages list the breaking changes in IDE and plugin releases with required/recommended steps to take by plugin authors. -* [**Changes in 2021.***](api_changes/api_changes_list_2021.md) -* [**Changes in 2020.***](api_changes/api_changes_list_2020.md) -* [**Changes in 2019.***](api_changes/api_changes_list_2019.md) -* [**Changes in 2018.***](api_changes/api_changes_list_2018.md) -* [**Changes in 2017.***](api_changes/api_changes_list_2017.md) -* [**Changes in 2016.***](api_changes/api_changes_list_2016.md) +* [**Changes in 2021.***](api_changes_list_2021.md) +* [**Changes in 2020.***](api_changes_list_2020.md) +* [**Changes in 2019.***](api_changes_list_2019.md) +* [**Changes in 2018.***](api_changes_list_2018.md) +* [**Changes in 2017.***](api_changes_list_2017.md) +* [**Changes in 2016.***](api_changes_list_2016.md) -> **NOTE** Changes from API marked with `org.jetbrains.annotations.ApiStatus.@Experimental`/`ScheduledForRemoval` are not listed here, as incompatible changes are to be expected. diff --git a/reference_guide/api_changes/api_changes_list_2016.md b/reference_guide/api_changes_list_2016.md similarity index 87% rename from reference_guide/api_changes/api_changes_list_2016.md rename to reference_guide/api_changes_list_2016.md index 2a016a633..01acbc03b 100644 --- a/reference_guide/api_changes/api_changes_list_2016.md +++ b/reference_guide/api_changes_list_2016.md @@ -1,13 +1,12 @@ ---- -title: Incompatible Changes in IntelliJ Platform and Plugins API 2016.* ---- +[//]: # (title: Incompatible Changes in IntelliJ Platform and Plugins API 2016.*) + -Please see [Incompatible API Changes](/reference_guide/api_changes_list.md) on how to verify compatibility. +Please see [Incompatible API Changes](api_changes_list.md) on how to verify compatibility. ## 2016.3 @@ -16,7 +15,6 @@ Please see [Incompatible API Changes](/reference_guide/api_changes_list.md) on h [`com.intellij.openapi.application.ApplicationListener.afterWriteActionFinished`](upsource:///platform/core-api/src/com/intellij/openapi/application/ApplicationListener.java?nav=1481:1505:focused&line=45) abstract method added : Implement this method or extend [`com.intellij.openapi.application.ApplicationAdapter`](upsource:////platform/core-api/src/com/intellij/openapi/application/ApplicationAdapter.java) class instead of implementing the interface. - ## 2016.2 ### Changes in IntelliJ Platform 2016.2 @@ -28,4 +26,4 @@ Please see [Incompatible API Changes](/reference_guide/api_changes_list.md) on h : [`com.intellij.util.net.HttpConfigurable.getPlainProxyPassword()`](upsource:///platform/platform-api/src/com/intellij/util/net/HttpConfigurable.java) instead. `org.jetbrains.asm4` package removed -: Use classes from `org.jetbrains.org.objectweb.asm` package instead. +: Use classes from `org.jetbrains.org.objectweb.asm` package instead. \ No newline at end of file diff --git a/reference_guide/api_changes/api_changes_list_2017.md b/reference_guide/api_changes_list_2017.md similarity index 88% rename from reference_guide/api_changes/api_changes_list_2017.md rename to reference_guide/api_changes_list_2017.md index 0d654e9a6..bd7bea3a3 100644 --- a/reference_guide/api_changes/api_changes_list_2017.md +++ b/reference_guide/api_changes_list_2017.md @@ -1,15 +1,16 @@ ---- -title: Incompatible Changes in IntelliJ Platform and Plugins API 2017.* ---- +[//]: # (title: Incompatible Changes in IntelliJ Platform and Plugins API 2017.*) + -Please see [Incompatible API Changes](/reference_guide/api_changes_list.md) on how to verify compatibility. +Please see [Incompatible API Changes](api_changes_list.md) on how to verify compatibility. -> **NOTE** Changes from API marked with `org.jetbrains.annotations.ApiStatus.@Experimental`/`ScheduledForRemoval` are not listed here, as incompatible changes are to be expected. + > Changes from API marked with `org.jetbrains.annotations.ApiStatus.@Experimental`/`ScheduledForRemoval` are not listed here, as incompatible changes are to be expected. + > + {type="note"} ## 2017.3 @@ -56,4 +57,4 @@ Please see [Incompatible API Changes](/reference_guide/api_changes_list.md) on h ### Changes in PhpStorm and PHP Plugin 2017.3 `com.jetbrains.php.lang.psi.elements.Function.getReturnType()` method return type changed from `PsiElement` to `PhpReturnType` -: Before method had been returning a `com.jetbrains.php.lang.psi.elements.ClassReference`. Now method returns `com.jetbrains.php.lang.psi.elements.PhpReturnType`. Method `ReturnType.getClassReference()` can be used if you need just a `ClassReference`. If you need to get the `PhpType`, use `com.jetbrains.php.lang.psi.elements.Function.getReturnType.getType()` method instead. +: Before method had been returning a `com.jetbrains.php.lang.psi.elements.ClassReference`. Now method returns `com.jetbrains.php.lang.psi.elements.PhpReturnType`. Method `ReturnType.getClassReference()` can be used if you need just a `ClassReference`. If you need to get the `PhpType`, use `com.jetbrains.php.lang.psi.elements.Function.getReturnType.getType()` method instead. \ No newline at end of file diff --git a/reference_guide/api_changes/api_changes_list_2018.md b/reference_guide/api_changes_list_2018.md similarity index 96% rename from reference_guide/api_changes/api_changes_list_2018.md rename to reference_guide/api_changes_list_2018.md index 05806c4b5..7b9179f52 100644 --- a/reference_guide/api_changes/api_changes_list_2018.md +++ b/reference_guide/api_changes_list_2018.md @@ -1,6 +1,5 @@ ---- -title: Incompatible Changes in IntelliJ Platform and Plugins API 2018.* ---- +[//]: # (title: Incompatible Changes in IntelliJ Platform and Plugins API 2018.*) + -Please see [Incompatible API Changes](/reference_guide/api_changes_list.md) on how to verify compatibility. +Please see [Incompatible API Changes](api_changes_list.md) on how to verify compatibility. -> **NOTE** Changes from API marked with `org.jetbrains.annotations.ApiStatus.@Experimental`/`ScheduledForRemoval` are not listed here, as incompatible changes are to be expected. + > Changes from API marked with `org.jetbrains.annotations.ApiStatus.@Experimental`/`ScheduledForRemoval` are not listed here, as incompatible changes are to be expected. + > + {type="note"} ## 2018.3 @@ -43,7 +44,6 @@ Please see [Incompatible API Changes](/reference_guide/api_changes_list.md) on h `com.intellij.psi.meta.PsiMetaData.getDependences` method removed : Use `com.intellij.psi.meta.PsiMetaData.getDependencies` instead. - ## 2018.2 ### Changes in IntelliJ Platform 2018.2 @@ -72,7 +72,6 @@ Please see [Incompatible API Changes](/reference_guide/api_changes_list.md) on h `org.apache.batik.script.InterpreterFactory.createInterpreter` abstract method added : Update `InterpreterFactory` implementations accordingly. - ## 2018.1 ### Changes in IntelliJ Platform 2018.1 @@ -140,4 +139,4 @@ Please see [Incompatible API Changes](/reference_guide/api_changes_list.md) on h : It's necessary to check that the code doesn't rely on the superclass. `com.jetbrains.php.lang.documentation.phpdoc.psi.impl.tags.PhpDocMethodImpl` superclass changed from `com.jetbrains.php.lang.documentation.phpdoc.psi.impl.PhpDocPsiElementImpl` to `com.jetbrains.php.lang.psi.elements.impl.PhpNamedElementImpl` -: It's necessary to check that the code doesn't rely on the superclass. +: It's necessary to check that the code doesn't rely on the superclass. \ No newline at end of file diff --git a/reference_guide/api_changes/api_changes_list_2019.md b/reference_guide/api_changes_list_2019.md similarity index 97% rename from reference_guide/api_changes/api_changes_list_2019.md rename to reference_guide/api_changes_list_2019.md index 276663b07..3bc681a7f 100644 --- a/reference_guide/api_changes/api_changes_list_2019.md +++ b/reference_guide/api_changes_list_2019.md @@ -1,6 +1,5 @@ ---- -title: Incompatible Changes in IntelliJ Platform and Plugins API 2019.* ---- +[//]: # (title: Incompatible Changes in IntelliJ Platform and Plugins API 2019.*) + -Please see [Incompatible API Changes](/reference_guide/api_changes_list.md) on how to verify compatibility. +Please see [Incompatible API Changes](api_changes_list.md) on how to verify compatibility. -> **NOTE** Changes from API marked with `org.jetbrains.annotations.ApiStatus.@Experimental`/`ScheduledForRemoval` are not listed here, as incompatible changes are to be expected. + > Changes from API marked with `org.jetbrains.annotations.ApiStatus.@Experimental`/`ScheduledForRemoval` are not listed here, as incompatible changes are to be expected. + > + {type="note"} ## 2019.3 @@ -193,7 +194,6 @@ Please see [Incompatible API Changes](/reference_guide/api_changes_list.md) on h `PARSE.expected.expression` property removed from resource bundle `com.jetbrains.python.PyBundle` : Use `com.jetbrains.python.PyPsiBundle` instead. - ## 2019.2 ### Changes in IntelliJ Platform 2019.2 @@ -226,7 +226,7 @@ Recompile your code to pick up the new signature. : Please bundle [performanceTesting plugin](https://plugins.jetbrains.com/plugin/7819-performance-testing) in case you would like to bundle YourKit profiler within your IDE. `com.intellij.extapi.psi.PsiElementBase` class removed -: Please use `com.intellij.psi.impl.PsiElementBase` or one of its descendants as a base class for PSI elements, e.g. `com.intellij.extapi.psi.ASTWrapperPsiElement`, as suggested in [Custom Language Support Tutorial](../../tutorials/custom_language_support/grammar_and_parser.md). +: Please use `com.intellij.psi.impl.PsiElementBase` or one of its descendants as a base class for PSI elements, e.g. `com.intellij.extapi.psi.ASTWrapperPsiElement`, as suggested in [Custom Language Support Tutorial](grammar_and_parser.md). `com.intellij.extapi.psi.MetadataPsiElementBase` class removed : Please use different base class for PSI elements. @@ -246,7 +246,6 @@ Recompile your code to pick up the new signature. `com.intellij.lexer.RestartableLexer.start(CharSequence buffer, int startOffset, int endOffset, int initialState, TokenIterator tokenIterator)` abstract method added : Implement method in `RestartableLexer` implementations. - ## 2019.1 ### Changes in IntelliJ Platform 2019.1 @@ -292,4 +291,4 @@ Recompile your code to pick up the new signature. : Field type has been generalized. In most of the cases, it's enough to recompile the code of the plugin. `org.jetbrains.kotlin.KtNodeTypes.STRING_TEMPLATE` field type changed from `org.jetbrains.kotlin.KtNodeType` to `com.intellij.psi.tree.IElementType` -: Field type has been generalized. In most of the cases, it's enough to recompile the code of the plugin. +: Field type has been generalized. In most of the cases, it's enough to recompile the code of the plugin. \ No newline at end of file diff --git a/reference_guide/api_changes/api_changes_list_2020.md b/reference_guide/api_changes_list_2020.md similarity index 95% rename from reference_guide/api_changes/api_changes_list_2020.md rename to reference_guide/api_changes_list_2020.md index 0f55d30be..fc0164d0c 100644 --- a/reference_guide/api_changes/api_changes_list_2020.md +++ b/reference_guide/api_changes_list_2020.md @@ -1,6 +1,5 @@ ---- -title: Incompatible Changes in IntelliJ Platform and Plugins API 2020.* ---- +[//]: # (title: Incompatible Changes in IntelliJ Platform and Plugins API 2020.*) + -Please see [Incompatible API Changes](/reference_guide/api_changes_list.md) on how to verify compatibility. +Please see [Incompatible API Changes](api_changes_list.md) on how to verify compatibility. -> **NOTE** Changes from API marked with `org.jetbrains.annotations.ApiStatus.@Experimental`/`ScheduledForRemoval` are not listed here, as incompatible changes are to be expected. + > Changes from API marked with `org.jetbrains.annotations.ApiStatus.@Experimental`/`ScheduledForRemoval` are not listed here, as incompatible changes are to be expected. + > + {type="note"} ## 2020.3 -> **NOTE** Java 11 is now required ([blog post](https://blog.jetbrains.com/platform/2020/09/intellij-project-migrates-to-java-11/)) when targeting 2020.3 and later only. + > Java 11 is now required ([blog post](https://blog.jetbrains.com/platform/2020/09/intellij-project-migrates-to-java-11/)) when targeting 2020.3 and later only. > Please make sure to always upgrade to the latest version of `gradle-intellij-plugin`. Follow releases on [GitHub](https://github.com/JetBrains/gradle-intellij-plugin/releases). - + > + {type="note"} + ### Changes in IntelliJ Platform 2020.3 `com.intellij.openapi.application.NonBlockingReadAction.finishOnUiThread` method parameter type changed from ``Consumer`` to ``Consumer`` @@ -114,7 +117,7 @@ This change doesn't break source or binary compatibility but may produce behavio ### Changes in PhpStorm and PHP Plugin 2020.3 Added PHP 8 support -: See [Breaking Changes in PhpStorm 2020.3](/products/phpstorm/php_open_api_breaking_changes_203.md). +: See [Breaking Changes in PhpStorm 2020.3](php_open_api_breaking_changes_203.md). ### Changes in Python Plugin 2020.3 @@ -155,7 +158,7 @@ Required changes in project setup ### Changes in IntelliJ Platform 2020.2 Support for JavaFX deprecated -: Plugins should migrate to [JCEF](/reference_guide/jcef.md). Alternatively, add an explicit dependency on [JavaFX Runtime for Plugins](https://plugins.jetbrains.com/plugin/14250-javafx-runtime-for-plugins). +: Plugins should migrate to [JCEF](jcef.md). Alternatively, add an explicit dependency on [JavaFX Runtime for Plugins](https://plugins.jetbrains.com/plugin/14250-javafx-runtime-for-plugins). `com.intellij.psi.util.PsiTreeUtil.processElements(element, processor)` method parameter type changed from `PsiElementProcessor` to `PsiElementProcessor` : This may break source-compatibility with clients that pass a more specific processor. Passing a more specific processor was illegal before because the `processElements` passes every descendant `PsiElement` to the processor regardless of its type. However, this worked with some poorly written clients, e.g. `PsiElementProcessor.CollectFilteredElements` and `PsiElementProcessor.FindFilteredElement` (both deprecated now). To simplify the migration, a new three-arg `processElements(element, elementClass, processor)` is introduced that filters by element class. In most cases, the simplest migration would be to add a wanted element class as a second argument. However, it's advised to use `SyntaxTraverser` API instead, which is more rich and flexible. @@ -221,7 +224,6 @@ Support for JavaFX deprecated : Please remove the plugin code supporting Java 13 language level features. IntelliJ IDEA supports preview features of the latest Java release and one upcoming release (if available). - #### VCS `com.intellij.diff.util.DiffUserDataKeysEx.REVISION_INFO` field removed @@ -249,7 +251,6 @@ IntelliJ IDEA supports preview features of the latest Java release and one upcom `org.jetbrains.plugins.groovy.formatter.AlignmentProvider.addPair` method parameter type changed from `Boolean` to `boolean` : Please adjust/recompile the code. - ### Changes in Java EE Plugins 2020.2 Java EE plugins split @@ -260,18 +261,15 @@ Java EE plugins split - `com.intellij.javaee.jpa` _Java EE: JPA_ - `com.intellij.javaee.web` _Java EE: Web/Servlets_ - ### Changes in JavaScript Plugin 2020.2 `com.intellij.lang.javascript.linter.jslint` package removed : JSLint functionality has been unbundled and moved to a separate plugin. [Issue](https://youtrack.jetbrains.com/issue/WEB-44511) - ### Changes in PhpStorm and PHP Plugin 2020.2 Added Union Types Support -: See [Breaking Changes in PhpStorm 2020.2](/products/phpstorm/php_open_api_breaking_changes_202.md). - +: See [Breaking Changes in PhpStorm 2020.2](php_open_api_breaking_changes_202.md). ### Changes in Kotlin Plugin 1.4 @@ -348,7 +346,7 @@ Java code migrated to use `TYPE_USE` nullability annotations : This may break source-compatibility with inheritors written in Kotlin. Images module functionality (package `org.intellij.images.*`) extracted to plugin -: The dependency [must be declared](/basics/plugin_structure/plugin_dependencies.md) explicitly now: +: The dependency [must be declared](plugin_dependencies.md) explicitly now: * Add `com.intellij.platform.images` in `plugin.xml` * Add to `build.gradle`: @@ -365,4 +363,4 @@ Images module functionality (package `org.intellij.images.*`) extracted to plugi : Use `com.jetbrains.python.psi.types.PyCallableType` instead. `com.jetbrains.python.psi.PyCallExpression.multiResolveCallee` method return type changed from `List` to `List` -: Use `com.jetbrains.python.psi.types.PyCallableType` instead of `com.jetbrains.python.psi.PyCallExpression.PyMarkedCallee`. +: Use `com.jetbrains.python.psi.types.PyCallableType` instead of `com.jetbrains.python.psi.PyCallExpression.PyMarkedCallee`. \ No newline at end of file diff --git a/reference_guide/api_changes/api_changes_list_2021.md b/reference_guide/api_changes_list_2021.md similarity index 90% rename from reference_guide/api_changes/api_changes_list_2021.md rename to reference_guide/api_changes_list_2021.md index ccc2a1034..3abce40e0 100644 --- a/reference_guide/api_changes/api_changes_list_2021.md +++ b/reference_guide/api_changes_list_2021.md @@ -1,6 +1,5 @@ ---- -title: Incompatible Changes in IntelliJ Platform and Plugins API 2021.* ---- +[//]: # (title: Incompatible Changes in IntelliJ Platform and Plugins API 2021.*) + -Please see [Incompatible API Changes](/reference_guide/api_changes_list.md) on how to verify compatibility. +Please see [Incompatible API Changes](api_changes_list.md) on how to verify compatibility. -> **NOTE** Changes from API marked with `org.jetbrains.annotations.ApiStatus.@Experimental`/`ScheduledForRemoval` are not listed here, as incompatible changes are to be expected. + > Changes from API marked with `org.jetbrains.annotations.ApiStatus.@Experimental`/`ScheduledForRemoval` are not listed here, as incompatible changes are to be expected. + > + {type="note"} ## 2021.1 ### Changes in IntelliJ Platform 2021.1 `com.intellij.util.io.PersistentHashMap.isCorrupted` method removed -: The storage checks for corruption automatically, there is no need of any explicit additional checks. - +: The storage checks for corruption automatically, there is no need of any explicit additional checks. \ No newline at end of file diff --git a/reference_guide/custom_language_support.md b/reference_guide/custom_language_support.md deleted file mode 100644 index 072f594c0..000000000 --- a/reference_guide/custom_language_support.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Custom Language Support ---- - - -*IntelliJ Platform* is a powerful platform for building development tools targeting *any* language. -Most of the IDE features consist of language-independent (provided by the platform) and language-specific parts. -Supporting a particular feature for a new language can be achieved with a small amount of effort: -a plugin must implement only the language-specific part. - -This part of the documentation explains the main concepts of the *Language API* and guides you through the sequence of steps that are usually required to develop a custom language plugin. -You can obtain additional information about the *Language API* from the JavaDoc comments for the *Language API* classes and from the Properties language support source code, which is part of the [IntelliJ IDEA Community Edition](https://github.com/JetBrains/intellij-community) source code. - -If you prefer a full example to the detailed descriptions offered in this section, please check out a step-by-step tutorial on how to create custom language support for _Simple Language_: -[Custom Language Support Tutorial](/tutorials/custom_language_support_tutorial.md). -Corresponding steps from the tutorial are linked under the "Examples" section on each page of this reference. - -The webinar [How We Built Comma, the Raku IDE, on the IntelliJ Platform](https://blog.jetbrains.com/platform/2020/01/webinar-recording-how-we-built-comma-the-raku-ide-on-the-intellij-platform/) offers an excellent introduction as well. - -Providing custom language support includes the following major steps: - -* [Registering File Type](/reference_guide/custom_language_support/registering_file_type.md) -* [Implementing Lexer](/reference_guide/custom_language_support/implementing_lexer.md) -* [Implementing Parser and PSI](/reference_guide/custom_language_support/implementing_parser_and_psi.md) -* [Syntax Highlighting and Error Highlighting](/reference_guide/custom_language_support/syntax_highlighting_and_error_highlighting.md) -* [References and Resolve](/reference_guide/custom_language_support/references_and_resolve.md) -* [Symbols](/reference_guide/custom_language_support/symbols.md) -* [Declarations and References](/reference_guide/custom_language_support/declarations_and_references.md) -* [Navigation](/reference_guide/custom_language_support/navigation.md) -* [Code Completion](/reference_guide/custom_language_support/code_completion.md) -* [Find Usages](/reference_guide/custom_language_support/find_usages.md) -* [Rename Refactoring](/reference_guide/custom_language_support/rename_refactoring.md) -* [Safe Delete Refactoring](/reference_guide/custom_language_support/safe_delete_refactoring.md) -* [Code Formatter](/reference_guide/custom_language_support/code_formatting.md) -* [Code Inspections and Intentions](/reference_guide/custom_language_support/code_inspections_and_intentions.md) -* [Structure View](/reference_guide/custom_language_support/structure_view.md) -* [Surround With](/reference_guide/custom_language_support/surround_with.md) -* [Go to Class and Go to Symbol](/reference_guide/custom_language_support/go_to_class_and_go_to_symbol.md) -* [Documentation](/reference_guide/custom_language_support/documentation.md) -* [Additional Minor Features](/reference_guide/custom_language_support/additional_minor_features.md) diff --git a/reference_guide/project_model/build_system.md b/reference_guide/project_model/build_system.md deleted file mode 100644 index 2a36d545f..000000000 --- a/reference_guide/project_model/build_system.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Build System ---- - - -* [External builder API and plugins](/reference_guide/frameworks_and_external_apis/external_builder_api.md) diff --git a/sdkdocs-template b/sdkdocs-template deleted file mode 160000 index 6232a70c3..000000000 --- a/sdkdocs-template +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 6232a70c3b68c85b1d718ac8fb4feb8b60576b58 diff --git a/topics/CODE_OF_CONDUCT.md b/topics/CODE_OF_CONDUCT.md new file mode 100644 index 000000000..12dd928c8 --- /dev/null +++ b/topics/CODE_OF_CONDUCT.md @@ -0,0 +1,7 @@ +[//]: # (title: Code of Conduct) + + + +## Code of Conduct + +This project and the corresponding community is governed by the [JetBrains Open Source and Community Code of Conduct](https://confluence.jetbrains.com/display/ALL/JetBrains+Open+Source+and+Community+Code+of+Conduct). Please make sure you read it. \ No newline at end of file diff --git a/topics/CONTRIBUTING.md b/topics/CONTRIBUTING.md new file mode 100644 index 000000000..4675098c5 --- /dev/null +++ b/topics/CONTRIBUTING.md @@ -0,0 +1,129 @@ +[//]: # (title: Contributing to the IntelliJ Platform SDK) + + + +This document describes our contribution guidelines for the open source IntelliJ Platform SDK documentation and sample code. +Before you begin contributing content to the SDK, please read this page thoroughly as well as the [Code of Conduct](CODE_OF_CONDUCT.md) and [License](https://github.com/JetBrains/intellij-sdk-docs/blob/master/LICENSE.txt) documents. +For information about contributing to the IntelliJ Platform itself, please visit [Contributing to the IntelliJ Platform](platform_contributions.md). + +Here are some useful things to know before authoring SDK content and submitting your Pull Request. +* Dummy list item + +## Setting Up the Documentation Build Environment + +This site runs via [Jekyll](https://jekyllrb.com), which is a popular static site generator, written in Ruby. It can be hosted locally to ensure that any changes are correct. Once set up, running the site is as easy as calling `rake preview`. + +Alternatively, the site can also be hosted in a [Docker container](https://www.docker.com). On Mac and Windows, this means the site is hosted in a virtual machine. Docker maintains this container, building it based on the instructions in the [`Dockerfile`](https://github.com/JetBrains/intellij-sdk-docs/blob/master/Dockerfile). All dependencies (Ruby, etc.) are automatically installed when building the image, which reduces the manual configuration steps. The Docker image is also used to build the [published site](https://www.jetbrains.org/intellij/sdk/docs/index.html), so it is a known working environment. + +### Developing Documentation with Docker + +Follow these steps to work with Docker: + +* Firstly, install Docker, using the [Docker Toolbox](https://www.docker.com/docker-toolbox). +* On Windows and Mac, start the Docker host virtual machine (start the "Docker Quickstart terminal" or run "Kitematic." See the Getting Started guides on [docker.com](https://www.docker.com) for more details). +* Clone the [`intellij-sdk-docs`](https://github.com/JetBrains/intellij-sdk-docs) repo to the local machine, and [initialise the `sdkdocs-template` submodule](#documentation-repository-submodules). +* Change the current directory to the parent directory of the git repo. +* Run `docker build -t intellij-sdk-docs .` to build the docker image from the current folder, and give it the tag `intellij-sdk-docs`. + * Note that this must be run from a command prompt that has the various `DOCKER_*` environment variables set up, such as the Docker Quickstart Terminal. +* Run `docker run -p 4000:4000 -v $PWD:/usr/src/app intellij-sdk-docs`. This command will: + * Start the docker container called `intellij-sdk-docs`. + * Forward port 4000 from the docker container to port 4000 on the docker client. + + > For Windows and Mac, this means port 4000 of the docker container is forwarded to port 4000 of the docker virtual machine, not `localhost`. For Linux, the docker client is the host machine, so `localhost:4000` is forwarded to port 4000 on the docker container. + > + > To hit the container's port 4000 from Windows or the Mac, it is necessary to hit the IP address of the docker client (virtual machine). Use `docker-machine ip default` to get the IP address of the docker client. Use `X.X.X.X:4000` to hit the client in the virtual machine, which is in turn mapped to the container's port 4000. + > + > Alternatively, modify the virtual machine's settings to automatically forward port 4000 to `localhost`. See this [blog post](https://acaird.github.io/computers/2014/11/16/docker-virtualbox-host-networking) for more details. + > + {type="note"} > + + * Mount the current directory (`$PWD` is a Unix style environment variable. You can use `%CD%` on Windows, or specify the full path) as `/usr/src/app` inside the docker container. The docker image will see the `intellij-sdk-docs` repo as the folder `/usr/src/app`. + + > If running on Windows in an MSYS bash script (e.g. the "Docker Quickstart terminal"), the path to the local folder needs to be properly escaped, or the MSYS environment will translate the paths to standard Windows path, and causing an error such as `invalid value "C:\\Users\\...;C:\\Program Files\\Git\\usr\\src\\app" for flag -v`. To fix this problem, prefix the full path with double slashes, e.g. `-v //c/Users/...`, or `docker run -p 4000:4000 -v /$PWD:/usr/src/app intellij-sdk-docs` (note the leading slash before `$PWD`). + > + {type="note"} + + * Run the commands in the Dockerfile's `CMD` instruction to execute: + * `rake bootstrap`, which ensures all of the prerequisites are installed, + * `rake preview`, which builds the site and starts to host it. +* Finally, you can access the newly created site by visiting [http://localhost:4000/intellij/sdk/docs/](http://localhost:4000/intellij/sdk/docs/), or by using the IP address of the docker client virtual machine (see the note above). + +### Developing Documentation Locally + +To build the documentation site, you need: + +* Ruby 2 - Jekyll is a Ruby application. +* Ruby 2 DevKit (for Windows) - Some of Jekyll's dependencies need to be compiled, and require the DevKit to be installed. +* `gem install bundler` - the site uses [Bundler](https://bundler.io) to manage gem dependencies within the repo, rather than globally installing to the local operating system. Run this command to install the Bundler toolset globally. + +#### macOS + +macOS comes with Ruby already installed. The only steps required are: + +* `gem install bundler` + +#### Windows + +* Install [Ruby 2](https://rubyinstaller.org) and the [Ruby 2 DevKit](https://rubyinstaller.org/downloads/) (one of the gems needs to build a native component) + * After installing the DevKit, make sure to edit the `config.yml` file to point to the Ruby installation + +This installation is easier if you use [Chocolatey](https://chocolatey.org), a package manager for Windows: + +* `choco install ruby` +* `choco install ruby2.devkit` + * After installing the DevKit, make sure to edit the `config.yml` file to point to the Ruby installation. + * By default, this is `C:\tools\DevKit\config.yml` + * Add the line `- C:\tools\ruby21` (including the leading minus sign) + +> **NOTE** Before running the `rake bootstrap` step listed below, please run the `devkitvars.bat` file from the DevKit. E.g. `C:\tools\DevKit\devkitvars.bat` + +### Bootstrapping the Documentation Build Environment + +1. Ensure Bundler is installed - `gem install bundler`. +2. On Windows, ensure the `devkitvars.bat` file has been run in the current command prompt (e.g. `c:\tools\DevKit\devkitvars.bat`). +3. Clone the documentation site. +4. Initialize and update the `sdkdocs-template` submodule - `git submodule init` and `git submodule update` +5. `rake bootstrap` - this uses Bundler to download all required gems. +6. `rake preview` - this will build the site, and host it in a local webserver. + +### Building and Previewing the Site + +To build and test the site, run `rake preview`. This will build the site and host it, using the config provided. The URL of the hosted site is displayed on the screen and depends on the `baseurl` field defined in `_config.yml`. + +> **NOTE** You must use `localhost` as hostname, _NOT_ 0.0.0.0, otherwise fonts fail to load. + +## Documentation Repository Submodules +The `sdkdocs-template` directory is actually a Git submodule, and it contains a submodule to the private `webhelp-template` repository. +The `sdkdocs-template` repository contains build scripts and compiled and minified JS and CSS that allow the site to run. +The private `webhelp-template` repository contains the code to build the JS and CSS. +It is currently closed source, but the plan is to make it open source at some point, in which case it is likely the two repositories will be merged. + +After cloning, a submodule needs to be initialized and updated: + +```sh +git submodule init +git submodule update +``` + +Initialization creates a `.gitmodules` file, register a submodule in the `sdkdocs-template` folder and check out the files. +Note that when a repo is added as a submodule, it doesn't get a `.git` folder, but instead gets a `.git` file that points to the actual location of the `.git` folder. + +A submodule can be updated using normal git commands such as `git pull`. +It can be switched to a different branch using `git checkout`, and any changes to the currently checked out revision need to be committed back into the main repository using git commands. +A submodule is initially cloned at a specific revision, and not as part of a branch.update + +If changes are made to the submodule, they should be made on a branch to a clone, and a Pull Request sent. +Changes can be made and committed, and the hosting repository will need to commit a pointer to the current version of the submodule. + +If there are any problems with the `sdkdocs-template`, please [raise an issue](https://github.com/JetBrains/sdkdocs-template/issues). + +## Creating IntelliJ Platform SDK Content +Content contributions to the IntelliJ Platform SDK are welcome. +Please download or clone the open source SDK project from [GitHub](https://github.com/JetBrains/intellij-sdk-docs), make additions or changes, and submit a pull request. +Before creating or altering content, please consult these guides: +* [SDK Documentation Style Guide](sdk_style.md). + This guide describes documentation conventions in terms of Markdown syntax. + Always test documentation changes using a [preview](#building-and-previewing-the-site) of the site. +* [SDK Code Sample Guidelines](sdk_code_guidelines.md). + Conventions for code sample organization, project settings, and naming conventions are described in this document. + Always test code changes by building and testing the SDK code sample. \ No newline at end of file diff --git a/topics/appendix/glossary.md b/topics/appendix/glossary.md new file mode 100644 index 000000000..70b22b7b5 --- /dev/null +++ b/topics/appendix/glossary.md @@ -0,0 +1,89 @@ +[//]: # (title: Glossary) + + + +## A + +Abstract Syntax Tree _(AST)_ +: The [Abstract Syntax Tree](implementing_parser_and_psi.md) represents the structure of source input files. +→ _Program Structure Interface_ + +Annotator +: Provides [semantic highlighting](syntax_highlighting_and_error_highlighting.md) based on underlying → _Program Structure Interface_ elements. +→ _Inspection_ + +## D + +Document Object Model _(DOM)_ +: [DOM API](xml_dom_api.md) abstracts working with XML files based on a custom semantic model. + +## E +Event Dispatch Thread _(EDT)_ +: The [Event Dispatch Thread](https://docs.oracle.com/javase/tutorial/uiswing/concurrency/dispatch.html) handles all Swing events. See also [General Threading Rules](general_threading_rules.md). + +Extension Point _(EP)_ +: Most functionality is provided by [Using Extension Points](plugin_extensions.md) provided by the platform or plugins. Plugins can also [define their own](plugin_extension_points.md) to allow extensibility. + +External System _(ES)_ +: [External System](external_system_integration.md) allows integrating external project management systems. + +## F + +File Based Index _(FBI)_ +: [File Based Index](file_based_indexes.md) allows storing key-value information based on the project's files. + +## I + +Inspection +: Supports configurable [semantic highlighting](code_inspections_and_intentions.md). +→ _Annotator_ + +Intention +: Provides an [automated fix](code_inspections_and_intentions.md) for commonly encountered code problems. + +## L + +Local History _(LVCS)_ +: A builtin → _Version Control System_ tracking all changes in the project [locally](https://www.jetbrains.com/help/idea/local-history.html). + +## J + +JetBrains Project System _(JPS)_ +: Represents the project model in [External Build](external_builder_api.md#accessing-project-model-and-configuration-from-external-build) process. + +JetBrains Runtime _(JBR)_ +: The [JetBrains Runtime](ide_development_instance.md#using-a-jetbrains-runtime-for-the-development-instance) is the default bundled runtime for all IntelliJ Platform-based IDEs by JetBrains. + +## P +Program Structure Interface _(PSI)_ +: The [Program Structure Interface](psi.md) represents a syntactic and semantic code model of the source input files. → _Abstract Syntax Tree_ → _Stubs_ + +## R + +Read Action +: Allows accessing code-related data structures for reading purposes. See also [General Threading Rules](general_threading_rules.md). +→ _Write Action_ + +Run Configuration _(RC)_ +: A [Run Configuration](basic_run_configurations.md) allows running external processes from within the IDE. + +## S + +Stubs +: A subset of a → _Program Structure Interface_ tree in a binary serialized compact format, see [Stub Indexes](stub_indexes.md). + +## V +Version Control System _(VCS)_ +: The API for [Version Control System](vcs_integration_for_plugins.md) allows accessing builtin as well as adding custom implementations. + +Virtual File _(VF)_ +: A [Virtual File](virtual_file.md) represents a file in a → _Virtual File System_. + +Virtual File System _(VFS)_ +: A [Virtual File System](virtual_file_system.md) provides a unified API for working with files represented as → _Virtual File_. + +## W + +Write Action +: Allows accessing code-related data structures for writing purposes. See also [General Threading Rules](general_threading_rules.md). +→ _Read Action_ \ No newline at end of file diff --git a/appendix/plugin_repository_obsolete.md b/topics/appendix/plugin_repository_obsolete.md similarity index 64% rename from appendix/plugin_repository_obsolete.md rename to topics/appendix/plugin_repository_obsolete.md index ad1ade683..505b116ff 100644 --- a/appendix/plugin_repository_obsolete.md +++ b/topics/appendix/plugin_repository_obsolete.md @@ -1,23 +1,13 @@ ---- -title: Plugin Repository [moved] +[//]: # (title: Plugin Repository [moved]) +[//]: # (: ) -redirect_from: - - /plugin_repository/index.html - - /plugin_repository/api/api_reference.html - - /plugin_repository/api/plugin_upload.html - - /plugin_repository/api/plugins_list.html - - /plugin_repository/api/plugin_details.html - - /plugin_repository/api/maven_interface.html - - /plugin_repository/api/plugin_developers.html - - /plugin_repository/feature_extractor.html - - /plugin_repository/custom_channels.html - ---- JetBrains provides an official plugins repository [JetBrains Plugin Repository](https://plugins.jetbrains.com) for all IntelliJ Platform-based IDEs, as well as TeamCity (limited functionality). -> **WARNING** **Part X - Plugin Repository** pages have moved to [JetBrains Marketplace](https://plugins.jetbrains.com/docs/marketplace/about-marketplace.html) documentation, please update your bookmarks. + > **Part X - Plugin Repository** pages have moved to [JetBrains Marketplace](https://plugins.jetbrains.com/docs/marketplace/about-marketplace.html) documentation, please update your bookmarks. + > + {type="warning"} For your convenience pages previously part of this documentation are linked below: @@ -29,4 +19,4 @@ For your convenience pages previously part of this documentation are linked belo * [Maven Interface](https://plugins.jetbrains.com/docs/marketplace/maven-interface.html) * [Plugin Developers List](https://plugins.jetbrains.com/docs/marketplace/plugin-developers-list.html) * [Plugin Recommendations](https://plugins.jetbrains.com/docs/marketplace/intellij-plugin-recommendations.html) -* [Custom Release Channels](https://plugins.jetbrains.com/docs/marketplace/custom-release-channels.html) +* [Custom Release Channels](https://plugins.jetbrains.com/docs/marketplace/custom-release-channels.html) \ No newline at end of file diff --git a/appendix/resources/consulting.md b/topics/appendix/resources/consulting.md similarity index 91% rename from appendix/resources/consulting.md rename to topics/appendix/resources/consulting.md index e2b5f1f10..0cb1207e4 100644 --- a/appendix/resources/consulting.md +++ b/topics/appendix/resources/consulting.md @@ -1,11 +1,12 @@ ---- -title: Consulting ---- +[//]: # (title: Consulting) + The following independent companies and individuals provide paid plugin consulting and development services. -> **NOTE** JetBrains is not responsible for nor guarantees the performance of these independent third-party companies. + > JetBrains is not responsible for nor guarantees the performance of these independent third-party companies. + > + {type="note"} | Name | Contact | Notes | | ------------------ | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | @@ -34,4 +35,4 @@ The following independent companies and individuals provide paid plugin consulti [ed2]: https://www.edument.se/en/page/intellij-platform-development [ed3]: https://commaide.com -Please [submit a PR or file a YouTrack issue](/intro/getting_help.md) for changes or additions to this list. +Please [submit a PR or file a YouTrack issue](getting_help.md) for changes or additions to this list. \ No newline at end of file diff --git a/appendix/resources/extension_point_list.md b/topics/appendix/resources/extension_point_list.md similarity index 98% rename from appendix/resources/extension_point_list.md rename to topics/appendix/resources/extension_point_list.md index 2011cbbbf..b32454e5a 100644 --- a/appendix/resources/extension_point_list.md +++ b/topics/appendix/resources/extension_point_list.md @@ -1,17 +1,4 @@ ---- -title: Extension Point List ---- - +[//]: # (title: Extension Point List) 1183 Extension Points @@ -23,11 +10,10 @@ _Implementation_ opens declaration of related class. | Icon | Description | Details | |---|---|---| -| ![Non-Dynamic](https://img.shields.io/badge/-Non--Dynamic-orange) | Non-[Dynamic Extension Point](/basics/plugin_structure/plugin_extension_points.md#dynamic-extension-points) | Installation/update of plugin requires restart | +| ![Non-Dynamic](https://img.shields.io/badge/-Non--Dynamic-orange) | Non-Dynamic Extension Point | Installation/update of plugin requires restart | | ![Experimental API](https://img.shields.io/badge/-Experimental_API-red) | Experimental API | Implementation annotated with `@ApiStatus.Experimental`, API might be altered or removed without prior notice | | ![Project-Level](https://img.shields.io/badge/-Project--Level-yellow) | Project-Level Extension Point | Declared with `area="IDEA_PROJECT"` | - ## [Analysis.xml](upsource:///platform/analysis-api/resources/META-INF/Analysis.xml) | Note | Extension Point | Implementation | @@ -319,13 +305,13 @@ _Implementation_ opens declaration of related class. | Note | Extension Point | Implementation | |---|---|---| -| ![Non-Dynamic](https://img.shields.io/badge/-Non--Dynamic-orange) | [com.android.tools.idea.customview.preview.
customViewEditorNotificationProvider](https://jb.gg/ipe?extensions=com.android.tools.idea.customview.preview.customViewEditorNotificationProvider) | [`Provider`](upsource:///platform/platform-api/src/com/intellij/ui/EditorNotifications.java) | +| ![Non-Dynamic](https://img.shields.io/badge/-Non--Dynamic-orange) | [com.android.tools.idea.customview.preview.
customViewEditorNotificationProvider](https://jb.gg/ipe?extensions=com.android.tools.idea.customview.preview.customViewEditorNotificationProvider) | [`Provider`](upsource:///platform/platform-api/src/com/intellij/ui/EditorNotifications.java) | ## [designer.xml](upsource:///android/designer/src/META-INF/designer.xml) | Note | Extension Point | Implementation | |---|---|---| -| ![Non-Dynamic](https://img.shields.io/badge/-Non--Dynamic-orange) | [com.android.tools.idea.uibuilder.editor.multirepresentation.
sourcecode.sourceCodePreviewRepresentationProvider](https://jb.gg/ipe?extensions=com.android.tools.idea.uibuilder.editor.multirepresentation.sourcecode.sourceCodePreviewRepresentationProvider) | [`PreviewRepresentationProvider`](upsource:///android/designer/src/com/android/tools/idea/uibuilder/editor/multirepresentation/PreviewRepresentationProvider.kt) | +| ![Non-Dynamic](https://img.shields.io/badge/-Non--Dynamic-orange) | [com.android.tools.idea.uibuilder.editor.multirepresentation.
sourcecode.sourceCodePreviewRepresentationProvider](https://jb.gg/ipe?extensions=com.android.tools.idea.uibuilder.editor.multirepresentation.sourcecode.sourceCodePreviewRepresentationProvider) | [`PreviewRepresentationProvider`](upsource:///android/designer/src/com/android/tools/idea/uibuilder/editor/multirepresentation/PreviewRepresentationProvider.kt) | | ![Non-Dynamic](https://img.shields.io/badge/-Non--Dynamic-orange) ![Project-Level](https://img.shields.io/badge/-Project--Level-yellow) | [com.android.tools.idea.uibuilder.handlers.viewHandlerProvider](https://jb.gg/ipe?extensions=com.android.tools.idea.uibuilder.handlers.viewHandlerProvider) | [`ViewHandlerProvider`](upsource:///android/designer/src/com/android/tools/idea/uibuilder/handlers/ViewHandlerProvider.kt) | ## [DesignerCorePlugin.xml](upsource:///plugins/ui-designer-core/src/META-INF/DesignerCorePlugin.xml) @@ -1510,14 +1496,14 @@ _Implementation_ opens declaration of related class. | ![Project-Level](https://img.shields.io/badge/-Project--Level-yellow) | [com.intellij.ignoredFileContentProvider](https://jb.gg/ipe?extensions=com.intellij.ignoredFileContentProvider) | [`IgnoredFileContentProvider`](upsource:///platform/vcs-api/src/com/intellij/openapi/vcs/changes/IgnoredFileContentProvider.java) | | ![Experimental API](https://img.shields.io/badge/-Experimental_API-red) | [com.intellij.ignoredFileProvider](https://jb.gg/ipe?extensions=com.intellij.ignoredFileProvider) | [`IgnoredFileProvider`](upsource:///platform/vcs-api/src/com/intellij/openapi/vcs/changes/IgnoredFileProvider.java) | | | [com.intellij.openapi.vcs.actions.AnnotateToggleAction.Provider](https://jb.gg/ipe?extensions=com.intellij.openapi.vcs.actions.AnnotateToggleAction.Provider) | [`Provider`](upsource:///platform/vcs-impl/src/com/intellij/openapi/vcs/actions/AnnotateToggleAction.java) | -| | [com.intellij.openapi.vcs.changes.actions.
CreatePatchFromChangesAction.Clipboard.ExtensionProvider](https://jb.gg/ipe?extensions=com.intellij.openapi.vcs.changes.actions.CreatePatchFromChangesAction.Clipboard.ExtensionProvider) | [`AnActionExtensionProvider`](upsource:///platform/platform-impl/src/com/intellij/openapi/actionSystem/AnActionExtensionProvider.java) | -| | [com.intellij.openapi.vcs.changes.actions.
CreatePatchFromChangesAction.Dialog.ExtensionProvider](https://jb.gg/ipe?extensions=com.intellij.openapi.vcs.changes.actions.CreatePatchFromChangesAction.Dialog.ExtensionProvider) | [`AnActionExtensionProvider`](upsource:///platform/platform-impl/src/com/intellij/openapi/actionSystem/AnActionExtensionProvider.java) | -| | [com.intellij.openapi.vcs.changes.actions.
diff.ChangeDiffRequestProvider](https://jb.gg/ipe?extensions=com.intellij.openapi.vcs.changes.actions.diff.ChangeDiffRequestProvider) | [`ChangeDiffRequestProvider`](upsource:///platform/vcs-impl/src/com/intellij/openapi/vcs/changes/actions/diff/ChangeDiffRequestProvider.java) | -| | [com.intellij.openapi.vcs.changes.actions.
diff.ChangeDiffViewerWrapperProvider](https://jb.gg/ipe?extensions=com.intellij.openapi.vcs.changes.actions.diff.ChangeDiffViewerWrapperProvider) | [`ChangeDiffViewerWrapperProvider`](upsource:///platform/vcs-impl/src/com/intellij/openapi/vcs/changes/actions/diff/ChangeDiffViewerWrapperProvider.java) | +| | [com.intellij.openapi.vcs.changes.actions.
CreatePatchFromChangesAction.Clipboard.ExtensionProvider](https://jb.gg/ipe?extensions=com.intellij.openapi.vcs.changes.actions.CreatePatchFromChangesAction.Clipboard.ExtensionProvider) | [`AnActionExtensionProvider`](upsource:///platform/platform-impl/src/com/intellij/openapi/actionSystem/AnActionExtensionProvider.java) | +| | [com.intellij.openapi.vcs.changes.actions.
CreatePatchFromChangesAction.Dialog.ExtensionProvider](https://jb.gg/ipe?extensions=com.intellij.openapi.vcs.changes.actions.CreatePatchFromChangesAction.Dialog.ExtensionProvider) | [`AnActionExtensionProvider`](upsource:///platform/platform-impl/src/com/intellij/openapi/actionSystem/AnActionExtensionProvider.java) | +| | [com.intellij.openapi.vcs.changes.actions.
diff.ChangeDiffRequestProvider](https://jb.gg/ipe?extensions=com.intellij.openapi.vcs.changes.actions.diff.ChangeDiffRequestProvider) | [`ChangeDiffRequestProvider`](upsource:///platform/vcs-impl/src/com/intellij/openapi/vcs/changes/actions/diff/ChangeDiffRequestProvider.java) | +| | [com.intellij.openapi.vcs.changes.actions.
diff.ChangeDiffViewerWrapperProvider](https://jb.gg/ipe?extensions=com.intellij.openapi.vcs.changes.actions.diff.ChangeDiffViewerWrapperProvider) | [`ChangeDiffViewerWrapperProvider`](upsource:///platform/vcs-impl/src/com/intellij/openapi/vcs/changes/actions/diff/ChangeDiffViewerWrapperProvider.java) | | | [com.intellij.openapi.vcs.changes.ui.filePathIconProvider](https://jb.gg/ipe?extensions=com.intellij.openapi.vcs.changes.ui.filePathIconProvider) | [`FilePathIconProvider`](upsource:///platform/vcs-api/src/com/intellij/openapi/vcs/changes/FilePathIconProvider.java) | | | [com.intellij.openapi.vcs.changes.vcsPreservingExecutor](https://jb.gg/ipe?extensions=com.intellij.openapi.vcs.changes.vcsPreservingExecutor) | [`VcsPreservingExecutor`](upsource:///platform/vcs-api/src/com/intellij/openapi/vcs/changes/VcsPreservingExecutor.java) | -| | [com.intellij.openapi.vcs.history.actions.
ShowDiffAfterWithLocalAction.ExtensionProvider](https://jb.gg/ipe?extensions=com.intellij.openapi.vcs.history.actions.ShowDiffAfterWithLocalAction.ExtensionProvider) | [`AnActionExtensionProvider`](upsource:///platform/platform-impl/src/com/intellij/openapi/actionSystem/AnActionExtensionProvider.java) | -| | [com.intellij.openapi.vcs.history.actions.
ShowDiffBeforeWithLocalAction.ExtensionProvider](https://jb.gg/ipe?extensions=com.intellij.openapi.vcs.history.actions.ShowDiffBeforeWithLocalAction.ExtensionProvider) | [`AnActionExtensionProvider`](upsource:///platform/platform-impl/src/com/intellij/openapi/actionSystem/AnActionExtensionProvider.java) | +| | [com.intellij.openapi.vcs.history.actions.
ShowDiffAfterWithLocalAction.ExtensionProvider](https://jb.gg/ipe?extensions=com.intellij.openapi.vcs.history.actions.ShowDiffAfterWithLocalAction.ExtensionProvider) | [`AnActionExtensionProvider`](upsource:///platform/platform-impl/src/com/intellij/openapi/actionSystem/AnActionExtensionProvider.java) | +| | [com.intellij.openapi.vcs.history.actions.
ShowDiffBeforeWithLocalAction.ExtensionProvider](https://jb.gg/ipe?extensions=com.intellij.openapi.vcs.history.actions.ShowDiffBeforeWithLocalAction.ExtensionProvider) | [`AnActionExtensionProvider`](upsource:///platform/platform-impl/src/com/intellij/openapi/actionSystem/AnActionExtensionProvider.java) | | | [com.intellij.openapi.vcs.impl.LocalLineStatusTrackerProvider](https://jb.gg/ipe?extensions=com.intellij.openapi.vcs.impl.LocalLineStatusTrackerProvider) | [`LocalLineStatusTrackerProvider`](upsource:///platform/vcs-impl/src/com/intellij/openapi/vcs/impl/LineStatusTrackerManager.kt) | | | [com.intellij.openapi.vcs.ui.cloneDialog.VcsCloneDialogExtension](https://jb.gg/ipe?extensions=com.intellij.openapi.vcs.ui.cloneDialog.VcsCloneDialogExtension) | [`VcsCloneDialogExtension`](upsource:///platform/vcs-api/src/com/intellij/openapi/vcs/ui/cloneDialog/VcsCloneDialogExtension.kt) | | | [com.intellij.patch.extension](https://jb.gg/ipe?extensions=com.intellij.patch.extension) | [`PatchEP`](upsource:///platform/vcs-api/vcs-api-core/src/com/intellij/openapi/diff/impl/patch/PatchEP.java) | @@ -1617,5 +1603,4 @@ _Implementation_ opens declaration of related class. |---|---|---| | ![Non-Dynamic](https://img.shields.io/badge/-Non--Dynamic-orange) | [XPathView.xpath.contextProviderExtension](https://jb.gg/ipe?extensions=XPathView.xpath.contextProviderExtension) | [`ContextProviderExtension`](upsource:///plugins/xpath/xpath-lang/src/org/intellij/lang/xpath/context/ContextProviderExtension.java) | | ![Non-Dynamic](https://img.shields.io/badge/-Non--Dynamic-orange) | [XPathView.xpath.functionProvider](https://jb.gg/ipe?extensions=XPathView.xpath.functionProvider) | [`XPathFunctionProvider`](upsource:///plugins/xpath/xpath-lang/src/org/intellij/lang/xpath/context/functions/XPathFunctionProvider.java) | -| ![Non-Dynamic](https://img.shields.io/badge/-Non--Dynamic-orange) | [XPathView.xsltRunnerExtension](https://jb.gg/ipe?extensions=XPathView.xsltRunnerExtension) | [`XsltRunnerExtension`](upsource:///plugins/xpath/xpath-lang/src/org/intellij/lang/xpath/xslt/run/XsltRunnerExtension.java) | - +| ![Non-Dynamic](https://img.shields.io/badge/-Non--Dynamic-orange) | [XPathView.xsltRunnerExtension](https://jb.gg/ipe?extensions=XPathView.xsltRunnerExtension) | [`XsltRunnerExtension`](upsource:///plugins/xpath/xpath-lang/src/org/intellij/lang/xpath/xslt/run/XsltRunnerExtension.java) | \ No newline at end of file diff --git a/appendix/resources/marketing.md b/topics/appendix/resources/marketing.md similarity index 92% rename from appendix/resources/marketing.md rename to topics/appendix/resources/marketing.md index ee0907e13..b02b2ad11 100644 --- a/appendix/resources/marketing.md +++ b/topics/appendix/resources/marketing.md @@ -1,9 +1,10 @@ ---- -title: Marketing ---- +[//]: # (title: Marketing) + -> **TIP** Please make sure to follow these [Quality Guidelines](https://plugins.jetbrains.com/docs/marketplace/quality-guidelines.html) for the general presentation of your plugin on JetBrains Marketplace. + > Please make sure to follow these [Quality Guidelines](https://plugins.jetbrains.com/docs/marketplace/quality-guidelines.html) for the general presentation of your plugin on JetBrains Marketplace. + > + {type="tip"} ## Embeddable Widgets @@ -14,20 +15,21 @@ title: Marketing For more details, please follow the [Embeddable Content](https://plugins.jetbrains.com/docs/marketplace/embeddable-content.html) section in the JetBrains Marketplace documentation. - ## Readme Badges Adding badges to the README files in open-source projects is common for providing additional information for users. Below are listed a few related to the IntelliJ SDK and plugins development provided by [shields.io](https://shields.io) and [espend.de](https://www.espend.de): -> **NOTE** The following code snippets contain `:pluginId` and `:packageName` placeholders. + > The following code snippets contain `:pluginId` and `:packageName` placeholders. > > `:pluginId` can be obtained from your plugin page URL, like: `https://plugins.jetbrains.com/plugin/6954-kotlin` - in this case, it's `6954`. > > `:pluginId` for shields.io also accepts a string ID that can be found in *Versions* tab, like `https://plugins.jetbrains.com/plugin/6954-kotlin/versions`. > > `:packageName` for ReSharper accepts only string ID. + > + {type="note"} ### Downloads @@ -55,7 +57,6 @@ Below are listed a few related to the IntelliJ SDK and plugins development provi ![Downloads](https://img.shields.io/resharper/dt/:packageName) ``` - ### Rating **IntelliJ Plugin Numeric Rating** @@ -72,7 +73,6 @@ Below are listed a few related to the IntelliJ SDK and plugins development provi ![Rating](https://img.shields.io/jetbrains/plugin/r/stars/:pluginId) ``` - ### Version **IntelliJ Plugins** @@ -101,7 +101,6 @@ Below are listed a few related to the IntelliJ SDK and plugins development provi ![Version](https://img.shields.io/resharper/v/:packageName?include_prereleases) ``` - ### Other Badges **GitHub Actions Workflow** @@ -130,4 +129,4 @@ Below are listed a few related to the IntelliJ SDK and plugins development provi [![Twitter Follow](https://img.shields.io/twitter/follow/JBPlatform?style=flat)](https://twitter.com/JBPlatform) ```markdown [![Twitter Follow](https://img.shields.io/twitter/follow/JBPlatform?style=flat)](https://twitter.com/JBPlatform) -``` +``` \ No newline at end of file diff --git a/appendix/resources/useful_links.md b/topics/appendix/resources/useful_links.md similarity index 83% rename from appendix/resources/useful_links.md rename to topics/appendix/resources/useful_links.md index 909fca4be..646ecaa08 100644 --- a/appendix/resources/useful_links.md +++ b/topics/appendix/resources/useful_links.md @@ -1,8 +1,5 @@ ---- -title: Useful Links -redirect_from: - - /resources.html ---- +[//]: # (title: Useful Links) + The following links represent useful resources for working with the _IntelliJ Platform_ and creating plugins. @@ -16,9 +13,10 @@ The following links represent useful resources for working with the _IntelliJ Pl ### Tooling * [IDE Settings, Caches, Logs, and Plugins](https://intellij-support.jetbrains.com/hc/en-us/articles/206544519-Directories-used-by-the-IDE-to-store-settings-caches-plugins-and-logs) -* [Internal Actions Menu](/reference_guide/internal_actions/internal_actions_intro.md) -* [IntelliJ Platform Artifacts Repository](/reference_guide/intellij_artifacts.md) -* [IntelliJ Plugin Verifier](https://github.com/JetBrains/intellij-plugin-verifier) (see also [Verifying Compatibility](/reference_guide/api_changes_list.md#verifying-compatibility)) +* [Internal Actions Menu](internal_actions_intro.md) +* [IntelliJ Platform Artifacts Repository](intellij_artifacts.md) +* [IntelliJ Plugin Verifier](https://github.com/JetBrains/intellij-plugin-verifier) (see also [Verifying Compatibility](api_changes_list.md#verifying-compatibility)) +* [IntelliJ Platform Explorer](https://jb.gg/ipe) ### Plugins * [PsiViewer](https://plugins.jetbrains.com/plugin/227-psiviewer) @@ -31,4 +29,4 @@ The following links represent useful resources for working with the _IntelliJ Pl * [How We Built Comma, the Raku IDE, on the IntelliJ Platform](https://blog.jetbrains.com/platform/2020/01/webinar-recording-how-we-built-comma-the-raku-ide-on-the-intellij-platform/) Jonathan Worthington, 2020 * [Building IntelliJ IDEA plugins in Scala](https://www.youtube.com/watch?v=IPO-cY_giNA) Igal Tabachnik, 2020 * [Live Development of a PyCharm Plugin](https://blog.jetbrains.com/pycharm/2019/01/webinar-recording-live-development-of-a-pycharm-plugin-with-joachim-ansorg/) Joachim Ansorg, 2019 -* [Build Developer Tools On Top of IntelliJ Platform](https://www.youtube.com/watch?v=vQDzjGzkPFc) Dmitry Jemerov, 2013 +* [Build Developer Tools On Top of IntelliJ Platform](https://www.youtube.com/watch?v=vQDzjGzkPFc) Dmitry Jemerov, 2013 \ No newline at end of file diff --git a/basics/analyzing.md b/topics/basics/analyzing.md similarity index 71% rename from basics/analyzing.md rename to topics/basics/analyzing.md index ee958fd1b..0c17028ab 100644 --- a/basics/analyzing.md +++ b/topics/basics/analyzing.md @@ -1,11 +1,10 @@ ---- -title: Analyzing ---- +[//]: # (title: Analyzing) + * Annotator -* [Inspections](/tutorials/code_inspections.md) +* [Inspections](code_inspections.md) * Profiles * Scopes * Suppressing Highlights - * Structural Search + * Structural Search \ No newline at end of file diff --git a/basics/architectural_overview/documents.md b/topics/basics/architectural_overview/documents.md similarity index 95% rename from basics/architectural_overview/documents.md rename to topics/basics/architectural_overview/documents.md index 4a7f15c46..eaf9d6d98 100644 --- a/basics/architectural_overview/documents.md +++ b/topics/basics/architectural_overview/documents.md @@ -1,6 +1,5 @@ ---- -title: Documents ---- +[//]: # (title: Documents) + A [`Document`](upsource:///platform/core-api/src/com/intellij/openapi/editor/Document.java) is an editable sequence of Unicode characters, typically corresponding to the text contents of a [virtual file](virtual_file.md). @@ -33,7 +32,9 @@ Also, document instances not linked to any virtual files can be created temporar Document instances are weakly referenced from `VirtualFile` instances. Thus, an unmodified `Document` instance can be garbage-collected if no one references it, and a new instance is created if the document contents are reaccessed later. -> **WARNING** Storing `Document` references in long-term data structures of a plugin will cause memory leaks. + > Storing `Document` references in long-term data structures of a plugin will cause memory leaks. + > + {type="warning"} ## How do I create a Document? @@ -62,4 +63,4 @@ All text strings passed to `Document` modification methods (`setText()`, `insert [`DocumentUtil`](upsource:///platform/core-impl/src/com/intellij/util/DocumentUtil.java) contains utility methods for `Document` processing. This allows you to get information like the text offsets of particular lines. -This is particularly useful when you need text location/offset information about a given `PsiElement`. +This is particularly useful when you need text location/offset information about a given `PsiElement`. \ No newline at end of file diff --git a/basics/architectural_overview/file_view_providers.md b/topics/basics/architectural_overview/file_view_providers.md similarity index 97% rename from basics/architectural_overview/file_view_providers.md rename to topics/basics/architectural_overview/file_view_providers.md index 94a617c6f..593262dc7 100644 --- a/basics/architectural_overview/file_view_providers.md +++ b/topics/basics/architectural_overview/file_view_providers.md @@ -1,6 +1,5 @@ ---- -title: File View Providers ---- +[//]: # (title: File View Providers) + A file view provider ([`FileViewProvider`](upsource:///platform/core-api/src/com/intellij/psi/FileViewProvider.java)) manages access to multiple PSI trees within a single file. @@ -37,4 +36,4 @@ Register as follows in `plugin.xml`: ``` -Where `%file_type%` refers to the type of the file being created (for example, "JFS"). +Where `%file_type%` refers to the type of the file being created (for example, "JFS"). \ No newline at end of file diff --git a/basics/architectural_overview/files.md b/topics/basics/architectural_overview/files.md similarity index 60% rename from basics/architectural_overview/files.md rename to topics/basics/architectural_overview/files.md index ba06722a5..9d334d60b 100644 --- a/basics/architectural_overview/files.md +++ b/topics/basics/architectural_overview/files.md @@ -1,7 +1,6 @@ ---- -title: Files ---- +[//]: # (title: Files) + -* [Virtual File System](/basics/virtual_file_system.md) -* [Virtual Files](virtual_file.md) +* [Virtual File System](virtual_file_system.md) +* [Virtual Files](virtual_file.md) \ No newline at end of file diff --git a/basics/architectural_overview/general_threading_rules.md b/topics/basics/architectural_overview/general_threading_rules.md similarity index 91% rename from basics/architectural_overview/general_threading_rules.md rename to topics/basics/architectural_overview/general_threading_rules.md index a19d0f55c..e6e16bee0 100644 --- a/basics/architectural_overview/general_threading_rules.md +++ b/topics/basics/architectural_overview/general_threading_rules.md @@ -1,16 +1,15 @@ ---- -title: General Threading Rules ---- +[//]: # (title: General Threading Rules) + -## Read/Write Lock +## Read-Write Lock In general, code-related data structures in the *IntelliJ Platform* are covered by a single reader/writer lock. You must not access the model outside a read or write action for the following subsystems: -- [Program Structure Interface](/basics/architectural_overview/psi.md) (PSI) -- [Virtual File System](/basics/virtual_file_system.md) (VFS) -- [Project root model](/basics/project_structure.md). +- [Program Structure Interface](psi.md) (PSI) +- [Virtual File System](virtual_file_system.md) (VFS) +- [Project root model](project_structure.md). **Reading** data is allowed from any thread. Reading data from the UI thread does not require any special effort. @@ -22,7 +21,6 @@ As a rule of thumb, whenever starting a read action, check if the PSI/VFS/projec Modifying the model is only allowed from write-safe contexts, including user actions and `invokeLater()` calls from them (see the next section). You may not modify PSI, VFS, or project model from inside UI renderers or `SwingUtilities.invokeLater()` calls. - ## Modality and `invokeLater()` To pass control from a background thread to the [Event Dispatch Thread](https://docs.oracle.com/javase/tutorial/uiswing/concurrency/dispatch.html) (EDT), instead of the standard `SwingUtilities.invokeLater()`, plugins should use `ApplicationManager.getApplication().invokeLater()`. @@ -40,10 +38,9 @@ None specified `ModalityState.any()` : The operation will be executed as soon as possible regardless of modal dialogs. Please note that modifying PSI, VFS, or project model is prohibited from such runnables. -If a UI thread activity needs to access [file-based index](/basics/indexing_and_psi_stubs.md) (e.g., it's doing any project-wide PSI analysis, resolves references, etc.), please use `DumbService.smartInvokeLater()`. +If a UI thread activity needs to access [file-based index](indexing_and_psi_stubs.md) (e.g., it's doing any project-wide PSI analysis, resolves references, etc.), please use `DumbService.smartInvokeLater()`. That way, it is run after all possible indexing processes have been completed. - ## Background processes and `ProcessCanceledException` Background progresses are managed by [`ProgressManager`](upsource:///platform/core-api/src/com/intellij/openapi/progress/ProgressManager.java) class, which has plenty of methods to execute the given code with a modal (dialog), non-modal (visible in the status bar), or invisible progress. @@ -84,4 +81,4 @@ There are two recommended ways of doing this: In both approaches, always check at the start of each read action, if the objects are still valid, and if the whole operation still makes sense (i.e., not canceled by the user, the project isn't closed, etc.). With `ReadAction.nonBlocking()`, use `expireWith()` or `expireWhen()` for that. -If the activity has to access [file-based index](/basics/indexing_and_psi_stubs.md) (e.g., it's doing any project-wide PSI analysis, resolves references, etc.), use `ReadAction.nonBlocking(...).inSmartMode()`. +If the activity has to access [file-based index](indexing_and_psi_stubs.md) (e.g., it's doing any project-wide PSI analysis, resolves references, etc.), use `ReadAction.nonBlocking(...).inSmartMode()`. \ No newline at end of file diff --git a/basics/architectural_overview/modifying_psi.md b/topics/basics/architectural_overview/modifying_psi.md similarity index 99% rename from basics/architectural_overview/modifying_psi.md rename to topics/basics/architectural_overview/modifying_psi.md index 03b7b71d4..293c7bd5c 100644 --- a/basics/architectural_overview/modifying_psi.md +++ b/topics/basics/architectural_overview/modifying_psi.md @@ -1,6 +1,5 @@ ---- -title: Modifying the PSI ---- +[//]: # (title: Modifying the PSI) + The PSI is a read-write representation of the source code as a tree of elements corresponding to a source file's structure. @@ -56,7 +55,6 @@ PsiExpression result = (PsiExpression) binaryExpression.replace(equalsCall); Just as everywhere else in the IntelliJ Platform API, the text passed to `createFileFromText()` and other `createFromText()` methods must use only `\n` as line separators. - ## Maintaining Tree Structure Consistency The PSI modification methods do not restrict you in the way you can build the resulting tree structure. @@ -67,7 +65,6 @@ Therefore, you always need to ensure that the structure you built with PSI modif To make sure you're not introducing inconsistencies, you can call `PsiTestUtil.checkFileStructure()` in the tests for your action that modifies the PSI. This method ensures that the structure you've built is the same as what the parser produces. - ## Whitespaces and Imports When working with PSI modification functions, you should never create individual whitespace nodes (spaces or line breaks) from the text. @@ -78,9 +75,8 @@ Also, when working with Java code (or with code in other languages with a simila Instead, you should insert fully-qualified names into the code you're generating, and then call the `shortenClassReferences()` method in the [`JavaCodeStyleManager`](upsource:///java/java-psi-api/src/com/intellij/psi/codeStyle/JavaCodeStyleManager.java) (or the equivalent API for the language you're working with). This ensures that the imports are created according to the user's code style settings and inserted into the file's correct place. - ## Combining PSI and Document Modifications In some cases, you need to perform a PSI modification and then to perform an operation on the document you've just modified through the PSI (for example, start a live template). In this case, you need to call a special method that completes the PSI-based post-processing (such as formatting) and commits the changes to the document. -The method you need to call is called `doPostponedOperationsAndUnblockDocument()`, and it's defined in the [`PsiDocumentManager`](upsource:///platform/core-api/src/com/intellij/psi/PsiDocumentManager.java) class. +The method you need to call is called `doPostponedOperationsAndUnblockDocument()`, and it's defined in the [`PsiDocumentManager`](upsource:///platform/core-api/src/com/intellij/psi/PsiDocumentManager.java) class. \ No newline at end of file diff --git a/basics/architectural_overview/navigating_psi.md b/topics/basics/architectural_overview/navigating_psi.md similarity index 98% rename from basics/architectural_overview/navigating_psi.md rename to topics/basics/architectural_overview/navigating_psi.md index 7344dcdba..5702e9b61 100644 --- a/basics/architectural_overview/navigating_psi.md +++ b/topics/basics/architectural_overview/navigating_psi.md @@ -1,6 +1,5 @@ ---- -title: Navigating the PSI ---- +[//]: # (title: Navigating the PSI) + There are three main ways to navigate the PSI: *top-down*, *bottom-up*, and *references*. @@ -9,7 +8,6 @@ In the second scenario, you have a specific point in the PSI tree (for example, Finally, *references* allow you to navigate from the usages of an element (e.g., a method call) to the declaration (the method being called) and back. References are described in a [separate topic](psi_references.md). - ## Top-Down Navigation The most common way to perform top-down navigation is to use a *visitor*. @@ -57,4 +55,4 @@ PsiMethod containingMethod = PsiTreeUtil.getParentOfType(element, PsiMethod.clas PsiClass containingClass = containingMethod.getContainingClass(); ``` -To see how the navigation works in practice, please refer to the [code sample](https://github.com/JetBrains/intellij-sdk-code-samples/blob/master/psi_demo/src/main/java/org/intellij/sdk/psi/PsiNavigationDemoAction.java). +To see how the navigation works in practice, please refer to the [code sample](https://github.com/JetBrains/intellij-sdk-code-samples/blob/master/psi_demo/src/main/java/org/intellij/sdk/psi/PsiNavigationDemoAction.java). \ No newline at end of file diff --git a/basics/architectural_overview/psi.md b/topics/basics/architectural_overview/psi.md similarity index 52% rename from basics/architectural_overview/psi.md rename to topics/basics/architectural_overview/psi.md index 9362db3a8..e039218b2 100644 --- a/basics/architectural_overview/psi.md +++ b/topics/basics/architectural_overview/psi.md @@ -1,13 +1,12 @@ ---- -title: Program Structure Interface (PSI) ---- +[//]: # (title: Program Structure Interface \(PSI\)) + The Program Structure Interface, commonly referred to as just PSI, is the layer in the _IntelliJ Platform_ responsible for parsing files and creating the syntactic and semantic code model that powers so many of the platform's features. -* [PSI Files](/basics/architectural_overview/psi_files.md) -* [File View Providers](/basics/architectural_overview/file_view_providers.md) -* [PSI Elements](/basics/architectural_overview/psi_elements.md) +* [PSI Files](psi_files.md) +* [File View Providers](file_view_providers.md) +* [PSI Elements](psi_elements.md) -> **TIP** A useful tool for debugging the PSI implementation is the [PsiViewer plugin](https://plugins.jetbrains.com/plugin/227-psiviewer). -> It can show you the PSI tree structure, the properties of every PSI element, and highlight its text range. + > A useful tool for debugging the PSI implementation is the [PsiViewer plugin](https://plugins.jetbrains.com/plugin/227-psiviewer). +> It can show you the PSI tree structure, the properties of every PSI element, and highlight its text range. \ No newline at end of file diff --git a/basics/architectural_overview/psi_elements.md b/topics/basics/architectural_overview/psi_elements.md similarity index 96% rename from basics/architectural_overview/psi_elements.md rename to topics/basics/architectural_overview/psi_elements.md index bb12842fa..72c91fbfb 100644 --- a/basics/architectural_overview/psi_elements.md +++ b/topics/basics/architectural_overview/psi_elements.md @@ -1,6 +1,5 @@ ---- -title: PSI Elements ---- +[//]: # (title: PSI Elements) + A PSI (Program Structure Interface) file represents a hierarchy of PSI elements (so-called _PSI trees_). @@ -25,4 +24,4 @@ The [`PsiElement`](upsource:///platform/core-api/src/com/intellij/psi/PsiElement ## What can I do with PSI elements? -See [PSI Cook Book](/basics/psi_cookbook.md) +See [PSI Cook Book](psi_cookbook.md) \ No newline at end of file diff --git a/basics/architectural_overview/psi_files.md b/topics/basics/architectural_overview/psi_files.md similarity index 95% rename from basics/architectural_overview/psi_files.md rename to topics/basics/architectural_overview/psi_files.md index abbb9a074..1b3a3dfcb 100644 --- a/basics/architectural_overview/psi_files.md +++ b/topics/basics/architectural_overview/psi_files.md @@ -1,6 +1,5 @@ ---- -title: PSI Files ---- +[//]: # (title: PSI Files) + A PSI (Program Structure Interface) file is the root of a structure representing a file's contents as a hierarchy of elements in a particular programming language. @@ -49,8 +48,8 @@ To save the PSI file to disk, use the [`PsiDirectory`](upsource:///platform/core ## How do I extend PSI? PSI can be extended to support additional languages through custom language plugins. -For more details on developing custom language plugins, see the [Custom Language Support](/reference_guide/custom_language_support.md) reference guide. +For more details on developing custom language plugins, see the [Custom Language Support](custom_language_support.md) reference guide. ## What are the rules for working with PSI? -Any changes done to the content of PSI files are reflected in documents, so all [rules for working with documents](documents.md#what-are-the-rules-of-working-with-documents) (read/write actions, commands, read-only status handling) are in effect. +Any changes done to the content of PSI files are reflected in documents, so all [rules for working with documents](documents.md#what-are-the-rules-of-working-with-documents) (read/write actions, commands, read-only status handling) are in effect. \ No newline at end of file diff --git a/basics/architectural_overview/psi_references.md b/topics/basics/architectural_overview/psi_references.md similarity index 92% rename from basics/architectural_overview/psi_references.md rename to topics/basics/architectural_overview/psi_references.md index b5304a8a5..ab2952db1 100644 --- a/basics/architectural_overview/psi_references.md +++ b/topics/basics/architectural_overview/psi_references.md @@ -1,6 +1,5 @@ ---- -title: PSI References ---- +[//]: # (title: PSI References) + A *reference* in a PSI tree is an object that represents a link from a *usage* of a particular element in the code to the corresponding *declaration*. *Resolving* a reference means locating the declaration to which a specific usage refers. @@ -35,7 +34,9 @@ The process of resolving references is distinct from parsing and is not performe Moreover, it is not always successful. If the code currently open in the IDE does not compile, or in other situations, it's normal for `PsiReference.resolve()` to return `null` - all code working with references must be prepared to handle that. -> **TIP** Please see also _Cache results of heavy computations_ in [Working with PSI efficiently](/reference_guide/performance/performance.md#working-with-psi-efficiently). + > Please see also _Cache results of heavy computations_ in [Working with PSI efficiently](performance.md#working-with-psi-efficiently). + > + {type="tip"} ## Contributed References @@ -56,8 +57,7 @@ References are also often contributed to non-code files, such as XML or JSON. Contributing references is one of the most common ways to extend an existing language. For example, your plugin can contribute references to Java code, even though the Java PSI is part of the platform and not defined in your plugin. -To contribute references, see the [reference contributor tutorial](/tutorials/custom_language_support/reference_contributor.md). - +To contribute references, see the [reference contributor tutorial](reference_contributor.md). ## References with Optional or Multiple Resolve Results @@ -80,7 +80,6 @@ The call returns an array of [`ResolveResult`](upsource:///platform/core-api/src Each of the objects identifies a PSI element and also specifies whether the result is valid. For example, suppose you have multiple Java method overloads and a call with arguments not matching any of the overloads. In that case, you will get back `ResolveResult` objects for all of the overloads, and `isValidResult()` returns `false` for all of them. - ## Searching for References As you already know, resolving a reference means going from usage to the corresponding declaration. @@ -92,4 +91,4 @@ The latter allows stopping processing as soon as the first (matching) result has ## Implementing References -Please refer to the [guide](/reference_guide/custom_language_support/references_and_resolve.md) and corresponding [tutorial](/tutorials/custom_language_support/reference_contributor.md) for more information. +Please refer to the [guide](references_and_resolve.md) and corresponding [tutorial](reference_contributor.md) for more information. \ No newline at end of file diff --git a/basics/architectural_overview/virtual_file.md b/topics/basics/architectural_overview/virtual_file.md similarity index 87% rename from basics/architectural_overview/virtual_file.md rename to topics/basics/architectural_overview/virtual_file.md index f0d435d76..2885255fe 100644 --- a/basics/architectural_overview/virtual_file.md +++ b/topics/basics/architectural_overview/virtual_file.md @@ -1,9 +1,8 @@ ---- -title: Virtual Files ---- +[//]: # (title: Virtual Files) + -A [`VirtualFile`](upsource:///platform/core-api/src/com/intellij/openapi/vfs/VirtualFile.java) (VF) is the *IntelliJ Platform's* representation of a file in a [Virtual File System (VFS)](/basics/virtual_file_system.md). +A [`VirtualFile`](upsource:///platform/core-api/src/com/intellij/openapi/vfs/VirtualFile.java) (VF) is the *IntelliJ Platform's* representation of a file in a [Virtual File System (VFS)](virtual_file_system.md). Most commonly, a virtual file is a file in a local file system. However, the *IntelliJ Platform* supports multiple pluggable file system implementations, so virtual files can also represent classes in a JAR file, old revisions of files loaded from a version control repository, and so on. @@ -56,9 +55,11 @@ If one needs to create a file through VFS, use `VirtualFile.createChildData()` t ## How do I get notified when VFS changes? -> **NOTE** See [Virtual file system events](/basics/virtual_file_system.md#virtual-file-system-events) for important details. + > See [Virtual file system events](virtual_file_system.md#virtual-file-system-events) for important details. + > + {type="note"} -Implement [`BulkFileListener`](upsource:///platform/core-api/src/com/intellij/openapi/vfs/newvfs/BulkFileListener.java) and subscribe to the [message bus](/reference_guide/messaging_infrastructure.md) topic `VirtualFileManager.VFS_CHANGES`. +Implement [`BulkFileListener`](upsource:///platform/core-api/src/com/intellij/openapi/vfs/newvfs/BulkFileListener.java) and subscribe to the [message bus](messaging_infrastructure.md) topic `VirtualFileManager.VFS_CHANGES`. For example: ```java @@ -70,7 +71,7 @@ project.getMessageBus().connect().subscribe(VirtualFileManager.VFS_CHANGES, new }); ``` -See [Message Infrastructure](/reference_guide/messaging_infrastructure.md) and [Plugin Listeners](/basics/plugin_structure/plugin_listeners.md) for more details. +See [Message Infrastructure](messaging_infrastructure.md) and [Plugin Listeners](plugin_listeners.md) for more details. For a non-blocking alternative, starting with version 2019.2 of the platform, see [`AsyncFileListener`](upsource:///platform/core-api/src/com/intellij/openapi/vfs/AsyncFileListener.java). @@ -84,10 +85,10 @@ Use [`ProjectLocator`](upsource:///platform/projectModel-api/src/com/intellij/op ## How do I extend VFS? -To provide an alternative file system implementation (for example, an FTP file system), implement the [`VirtualFileSystem`](upsource:///platform/core-api/src/com/intellij/openapi/vfs/VirtualFileSystem.java) class (most likely you'll also need to implement `VirtualFile`), and register your implementation via `com.intellij.virtualFileSystem` extension point (2019.2 and later) or [application component](/basics/plugin_structure/plugin_components.md) for earlier versions. +To provide an alternative file system implementation (for example, an FTP file system), implement the [`VirtualFileSystem`](upsource:///platform/core-api/src/com/intellij/openapi/vfs/VirtualFileSystem.java) class (most likely you'll also need to implement `VirtualFile`), and register your implementation via `com.intellij.virtualFileSystem` extension point (2019.2 and later) or [application component](plugin_components.md) for earlier versions. To hook into operations performed in the local file system (for example, when developing a version control system integration that needs custom rename/move handling), implement [`LocalFileOperationsHandler`](upsource:///platform/analysis-api/src/com/intellij/openapi/vfs/LocalFileOperationsHandler.java) and register it via `LocalFileSystem.registerAuxiliaryFileOperationsHandler()`. ## What are the rules for working with VFS? -See [Virtual File System](/basics/virtual_file_system.md) for a detailed description of the VFS architecture and usage guidelines. +See [Virtual File System](virtual_file_system.md) for a detailed description of the VFS architecture and usage guidelines. \ No newline at end of file diff --git a/basics/action_system.md b/topics/basics/basic_action_system.md similarity index 93% rename from basics/action_system.md rename to topics/basics/basic_action_system.md index 5084d2238..d164b594c 100644 --- a/basics/action_system.md +++ b/topics/basics/basic_action_system.md @@ -1,6 +1,5 @@ ---- -title: Action System ---- +[//]: # (title: Action System) + ## Introduction @@ -12,21 +11,20 @@ The action implementation determines the contexts in which an action is availabl Registration determines where an action appears in the IDE UI. Once implemented and registered, an action receives callbacks from the IntelliJ Platform in response to user gestures. -The [Creating Actions](/tutorials/action_system/working_with_custom_actions.md) tutorial describes the process of adding a custom action to a plugin. -The [Grouping Actions](/tutorials/action_system/grouping_action.md) tutorial demonstrates three types of groups that can contain actions. +The [Creating Actions](working_with_custom_actions.md) tutorial describes the process of adding a custom action to a plugin. +The [Grouping Actions](grouping_action.md) tutorial demonstrates three types of groups that can contain actions. The rest of this page is an overview of actions as an extension point. -* bullet list -{:toc} - ## Action Implementation An action is a class derived from the abstract class [`AnAction`](upsource:///platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java). The IntelliJ Platform calls methods of an action when a user interacts with a menu item or toolbar button. -> **WARNING** Classes based on `AnAction` do not have class fields of any kind. + > Classes based on `AnAction` do not have class fields of any kind. > This is because an instance of `AnAction` class exists for the entire lifetime of the application. > If the `AnAction` class uses a field to store data that has a shorter lifetime and doesn't clear this data promptly, the data leaks. > For example, any `AnAction` data that exists only within the context of a `Project` causes the `Project` to be kept in memory after the user has closed it. + > + {type="warning"} ### Principal Implementation Overrides Every IntelliJ Platform action should override `AnAction.update()` and must override `AnAction.actionPerformed()`. @@ -41,18 +39,22 @@ Every IntelliJ Platform action should override `AnAction.update()` and must over See [Overriding the `AnAction.actionPerformed()` Method](#overriding-the-anactionactionperformed-method) for more information. There are other methods to override in the `AnAction` class, such as changing the default `Presentation` object for the action. -There is also a use case for overriding action constructors when registering them with dynamic action groups, demonstrated in the [Grouping Actions](/tutorials/action_system/grouping_action.md#adding-child-actions-to-the-dynamic-group) tutorial. +There is also a use case for overriding action constructors when registering them with dynamic action groups, demonstrated in the [Grouping Actions](grouping_action.md#adding-child-actions-to-the-dynamic-group) tutorial. However, the `update()` and `actionPerformed()` methods are essential to basic operation. ### Overriding the AnAction.update Method The method `AnAction.update()` is periodically called by the IntelliJ Platform in response to user gestures. The `update()` method gives an action to evaluate the current context and enable or disable its functionality. -> **WARNING** The `AnAction.update()` method can be called frequently and on a UI thread. + > The `AnAction.update()` method can be called frequently and on a UI thread. This method needs to _execute very quickly_; no real work should be performed in this method. For example, checking selection in a tree or a list is considered valid, but working with the file system is not. + > + {type="warning"} -> **TIP** If the new state of an action cannot be determined quickly, then evaluation should be performed in the `AnAction.actionPerformed()` method, and notify the user that the action cannot be executed if the context isn't suitable. + > If the new state of an action cannot be determined quickly, then evaluation should be performed in the `AnAction.actionPerformed()` method, and notify the user that the action cannot be executed if the context isn't suitable. + > + {type="tip"} #### Determining the Action Context The `AnActionEvent` object passed to `update()` carries information about the current context for the action. @@ -82,8 +84,10 @@ Toolbar actions display their respective icons for the disabled state. The visibility of a disabled action in a menu depends on whether the host menu (e.g., "ToolsMenu") containing the action has the `compact` attribute set. See [Grouping Actions](#grouping-actions) for more information about the `compact` attribute and menu actions' visibility. -> **NOTE** If an action is added to a toolbar, its `update()` can be called if there was any user activity or focus transfer. + > If an action is added to a toolbar, its `update()` can be called if there was any user activity or focus transfer. If the action's availability changes in the absence of these events, then call [`ActivityTracker.getInstance().inc()`](upsource:///platform/platform-api/src/com/intellij/ide/ActivityTracker.java) to notify the action subsystem to update all toolbar actions. + > + {type="note"} An example of enabling a menu action based on whether a project is open is demonstrated in [`PopupDialogAction.update()`](https://github.com/JetBrains/intellij-sdk-code-samples/blob/master/action_basics/src/main/java/org/intellij/sdk/action/PopupDialogAction.java) method. @@ -126,7 +130,7 @@ If the `compact` attribute is `true` for a menu group, an action in the menu onl In contrast, if the `compact` attribute is `false`, an action in the menu appears if its state is disabled but visible. Some menus like **Tools** have the `compact` attribute set, so there isn't a way to show an action on the tools menu if it is not enabled. -| Host Menu
`compact` Setting | Action Enabled | Visibility Enabled | Menu Item Visible? | Menu Item Appears Gray? | +| Host Menu
`compact` Setting | Action Enabled | Visibility Enabled | Menu Item Visible? | Menu Item Appears Gray? | | :-----: | :------------: | :----------------: | :----------------: | :---------------------: | | T | **F** | T | **F** | N/A | | T | T | T | T | F | @@ -135,7 +139,7 @@ Some menus like **Tools** have the `compact` attribute set, so there isn't a way All other combinations of `compact`, visibility, and enablement produce N/A for gray appearance because the menu item isn't visible. -See the [Grouping Actions](/tutorials/action_system/grouping_action.md) tutorial for examples of creating action groups. +See the [Grouping Actions](grouping_action.md) tutorial for examples of creating action groups. ## Registering Actions There are two main ways to register an action: either by listing it in the `` section of a plugin's `plugin.xml` file or through code. @@ -159,7 +163,7 @@ A different context, such as searching for the action using **Help \| Find Actio A second `override-text` element uses `place` and `use-text-of-place` attributes to declare the same version of the text used in the Main Menu is also used in the Editor Popup Menu. Additional `override-text` elements could be used to specify other places where the Main Menu text should be used. -An example of using `` is demonstrated in the [Creating Actions](/tutorials/action_system/working_with_custom_actions.md#using-override-text-for-an-action) tutorial. +An example of using `` is demonstrated in the [Creating Actions](working_with_custom_actions.md#using-override-text-for-an-action) tutorial. #### Setting the Synonym Element _2020.3_ @@ -220,7 +224,7 @@ _2020.3_ If `` is used for an group `id`, the key includes the `` attribute: * `group...text=Place-dependent Translated Group Text` -See [Extending DefaultActionGroup](/tutorials/action_system/grouping_action.md#extending-defaultactiongroup) for a tutorial of localizing Actions and Groups. +See [Extending DefaultActionGroup](grouping_action.md#extending-defaultactiongroup) for a tutorial of localizing Actions and Groups. #### Action Declaration Reference The places where actions can appear are defined by constants in [`ActionPlaces`](upsource:///platform/platform-api/src/com/intellij/openapi/actionSystem/ActionPlaces.java). @@ -228,7 +232,9 @@ Group IDs for the IntelliJ Platform are defined in [`PlatformActions.xml`](upsou This, and additional information can also be found by using the [Code Completion](https://www.jetbrains.com/help/idea/auto-completing-code.html#invoke-basic-completion), [Quick Definition](https://www.jetbrains.com/help/idea/viewing-reference-information.html#view-definition-symbols) and [Quick Documentation](https://www.jetbrains.com/help/idea/viewing-reference-information.html#inline-quick-documentation) features. -> **TIP** To lookup existing Action ID (e.g. for use in `relative-to-action`), [UI Inspector](/reference_guide/internal_actions/internal_ui_inspector.md) can be used. + > To lookup existing Action ID (e.g. for use in `relative-to-action`), [UI Inspector](internal_ui_inspector.md) can be used. + > + {type="tip"} ```xml @@ -361,4 +367,4 @@ To get a Swing component from such an object, call the respective `getComponent( If an action toolbar is attached to a specific component (for example, a panel in a tool window), call `ActionToolbar.setTargetComponent()` and pass the related component's instance as a parameter. Setting the target ensures that the toolbar buttons' state depends on the state of the related component, not on the current focus location within the IDE frame. -See [Toolbar](https://jetbrains.design/intellij/controls/toolbar/) in _IntelliJ Platform UI Guidelines_ for an overview. +See [Toolbar](https://jetbrains.design/intellij/controls/toolbar/) in _IntelliJ Platform UI Guidelines_ for an overview. \ No newline at end of file diff --git a/basics/run_configurations.md b/topics/basics/basic_run_configurations.md similarity index 67% rename from basics/run_configurations.md rename to topics/basics/basic_run_configurations.md index b47384124..3504485a3 100644 --- a/basics/run_configurations.md +++ b/topics/basics/basic_run_configurations.md @@ -1,6 +1,5 @@ ---- -title: Run Configurations ---- +[//]: # (title: Run Configurations) + *Run Configurations* allow users to run specific external processes from within the IDE, e.g., a script, an application, a server, etc. @@ -10,12 +9,12 @@ You can provide the UI for the user to specify execution options, and an option Classes used to manipulate run configurations can be split into the following groups: -* [Run configuration management](/basics/run_configurations/run_configuration_management.md). +* [Run configuration management](run_configuration_management.md). This includes creation, persistence, and modification. -* [Execution](/basics/run_configurations/run_configuration_execution.md). +* [Execution](run_configuration_execution.md). This diagram shows the main classes: -![Architecture](img/classes.png) +![Architecture](classes.png) -See [Run Configurations Tutorial](/tutorials/run_configurations.md) for a fully working sample. +See [Run Configurations Tutorial](run_configurations.md) for a fully working sample. \ No newline at end of file diff --git a/basics/basics.md b/topics/basics/basics.md similarity index 78% rename from basics/basics.md rename to topics/basics/basics.md index 110ab77a5..1875dffc6 100644 --- a/basics/basics.md +++ b/topics/basics/basics.md @@ -1,8 +1,5 @@ ---- -title: Quick Start Guide -redirect_from: - - /basics.html ---- +[//]: # (title: Quick Start Guide) + This section covers the basics of working with the *IntelliJ Platform*. @@ -11,6 +8,6 @@ It will familiarize you with the working environment, project structure, and fre * [Main Types of IntelliJ Platform Plugins](types_of_plugins.md) * [Creating Your First Plugin](getting_started.md) * [Plugin Structure](plugin_structure.md) -* [Kotlin for Plugin Developers](/tutorials/kotlin.md) +* [Kotlin for Plugin Developers](kotlin.md) * [IDE Development Instances](ide_development_instance.md) -* [Plugin development FAQ](faq.md) +* [Plugin development FAQ](faq.md) \ No newline at end of file diff --git a/basics/disposers.md b/topics/basics/disposers.md similarity index 89% rename from basics/disposers.md rename to topics/basics/disposers.md index bbe726f66..87eb264c1 100644 --- a/basics/disposers.md +++ b/topics/basics/disposers.md @@ -1,6 +1,5 @@ ---- -title: Disposer and Disposable ---- +[//]: # (title: Disposer and Disposable) + The IntelliJ Platform's [`Disposer`](upsource:///platform/util/src/com/intellij/openapi/util/Disposer.java) facilitates resource cleanup. @@ -15,20 +14,16 @@ A `Disposable` is an interface for any object providing a `Disposable.dispose()` The `Disposer` supports chaining `Disposables` in parent-child relationships. -* bullet list -{:toc} - ## Automatically Disposed Objects Many objects are disposed automatically by the platform if they implement the `Disposable` interface. -The most important type of such objects is [services](/basics/plugin_structure/plugin_services.md). +The most important type of such objects is [services](plugin_services.md). Application-level services are automatically disposed by the platform when the IDE is closed or the plugin providing the service is unloaded. Project-level services are disposed when the project is closed, or the plugin is unloaded. Note that extensions registered in `plugin.xml` are *not* automatically disposed. If an extension requires executing some code to dispose it, you need to define a service and to put the code in its `dispose()` method or use it as a parent disposable. - ## The Disposer Singleton The primary purpose of the [`Disposer`](upsource:///platform/util/src/com/intellij/openapi/util/Disposer.java) singleton is to enforce the rule that _a child `Disposable` never outlives its parent_. @@ -50,14 +45,16 @@ One of the parent `Disposables` provided by the IntelliJ Platform can be chosen, Use the following guidelines to choose the correct parent: -* For resources required for a plugin's entire lifetime, use an application or project level [service](/basics/plugin_structure/plugin_services.md). -* For resources required while a [dialog](/user_interface_components/dialog_wrapper.md) is displayed, use `DialogWrapper.getDisposable()`. -* For resources required while a [tool window](/user_interface_components/tool_windows.md) tab is displayed, pass your instance implementing `Disposable` to `Content.setDisposer()`. +* For resources required for a plugin's entire lifetime, use an application or project level [service](plugin_services.md). +* For resources required while a [dialog](dialog_wrapper.md) is displayed, use `DialogWrapper.getDisposable()`. +* For resources required while a [tool window](tool_windows.md) tab is displayed, pass your instance implementing `Disposable` to `Content.setDisposer()`. * For resources with a shorter lifetime, create a disposable using `Disposer.newDisposable()` and dispose it manually using `Disposable.dispose()`. Note that it's always best to specify a parent for such a disposable (e.g., a project-level service), so that there is no memory leak if the `Disposable.dispose()` call is not reached because of an exception or a programming error. -> **WARNING** Even though `Application` and `Project` implement `Disposable`, they must NEVER be used as parent disposables in plugin code. + > Even though `Application` and `Project` implement `Disposable`, they must NEVER be used as parent disposables in plugin code. Disposables registered using those objects as parents will not be disposed when the plugin is unloaded, leading to memory leaks. + > + {type="warning"} The `Disposer` API's flexibility means that if the parent instance is chosen unwisely, the child may consume resources for longer than required. Continuing to use resources when they are no longer needed can be a severe source of contention due to leaving some zombie objects behind due to each invocation. @@ -86,7 +83,7 @@ Using such methods is always preferable to removing listeners explicitly from th To choose the correct parent disposable, use the guidelines from the previous section. -The same rules apply to [message bus](/reference_guide/messaging_infrastructure.md) connections. +The same rules apply to [message bus](messaging_infrastructure.md) connections. Always pass a parent disposable to `MessageBus.connect()`, and make sure it has the shortest possible lifetime. ### Determining Disposal Status @@ -94,8 +91,10 @@ You can use `Disposer.isDisposed()` to check whether a `Disposable` has already This check is useful, for example, for an asynchronous callback to a `Disposable` that may be disposed before the callback is executed. In such a case, the best strategy is usually to do nothing and return early. -> **WARNING** Non-disposed objects shouldn't hold onto references to disposed objects, as this constitutes a memory leak. + > Non-disposed objects shouldn't hold onto references to disposed objects, as this constitutes a memory leak. > Once a `Disposable` is released, it should be completely inactive, and there's no reason to refer to it anymore. + > + {type="warning"} ### Ending a Disposable Lifecycle A plugin can manually end a `Disposable` lifecycle by calling `Disposer.dispose(Disposable)`. @@ -133,8 +132,10 @@ Regardless, it illustrates the basic pattern, which is: * The `Foo` disposable is registered as a child of `parentDisposable` in the constructor. * The `dispose()` method consolidates the necessary release actions and will be called by the `Disposer`. -> **WARNING** Never call `Disposable.dispose()` directly because it bypasses the parent-child relationships established in `Disposer`. + > Never call `Disposable.dispose()` directly because it bypasses the parent-child relationships established in `Disposer`. > Always call `Disposer.dispose(Disposable)` instead. + > + {type="warning"} ## Diagnosing Disposer Leaks @@ -170,12 +171,14 @@ The following snippet represents the sort of "memory leak detected" error encoun … ``` -> **TIP** The first part of the callstack is unrelated to diagnosing the memory leak. + > The first part of the callstack is unrelated to diagnosing the memory leak. > Instead, pay attention to the second part of the call stack, after `Caused by: java.lang.Throwable`. + > + {type="tip"} In this specific case, the IntelliJ Platform ([`CoreProgressManager`](upsource:///platform/core-impl/src/com/intellij/openapi/progress/impl/CoreProgressManager.java)) started a task that contained the `DynamicWizard` code. In turn, that code allocated a `Project` that was never disposed by the time the application exited. That is a promising place to start digging. The above memory leak was ultimately caused by failing to pass a `Project` instance to a function responsible for registering it for disposal. -Often the fix for a memory leak is as simple as understanding the memory scope of the object being allocated - usually a UI container, project, or application - and making sure a `Disposer.register()` call is made appropriately for it. +Often the fix for a memory leak is as simple as understanding the memory scope of the object being allocated - usually a UI container, project, or application - and making sure a `Disposer.register()` call is made appropriately for it. \ No newline at end of file diff --git a/basics/editing.md b/topics/basics/editing.md similarity index 65% rename from basics/editing.md rename to topics/basics/editing.md index ec6f8c049..5e6fa3234 100644 --- a/basics/editing.md +++ b/topics/basics/editing.md @@ -1,9 +1,8 @@ ---- -title: Editing ---- +[//]: # (title: Editing) + * Code Completion -* [Templates](/basics/templates.md) +* [Templates](templates.md) * QuickDoc -* [Intentions](/tutorials/code_intentions.md) +* [Intentions](code_intentions.md) \ No newline at end of file diff --git a/basics/faq.md b/topics/basics/faq.md similarity index 98% rename from basics/faq.md rename to topics/basics/faq.md index 31da53eec..0007746d3 100644 --- a/basics/faq.md +++ b/topics/basics/faq.md @@ -1,8 +1,5 @@ ---- -title: Plugin Development FAQ -redirect_from: - - /faq.html ---- +[//]: # (title: Plugin Development FAQ) + This FAQ is a topical index of questions that have been asked (and answered) on our [IntelliJ IDEA Open API and Plugin Development forum](https://intellij-support.jetbrains.com/hc/en-us/community/topics/200366979-IntelliJ-IDEA-Open-API-and-Plugin-Development). @@ -24,7 +21,7 @@ This FAQ is a topical index of questions that have been asked (and answered) on * [Where do I get the list of built-in action IDs?](https://intellij-support.jetbrains.com/hc/en-us/community/posts/206126699-List-of-built-in-action-ID-s-) ## Accessing and Modifying the Source Code -* [PSI Architectural Overview](/basics/architectural_overview/psi.md) +* [PSI Architectural Overview](psi.md) * [How do I find all subclasses of a class?](https://intellij-support.jetbrains.com/hc/en-us/community/posts/206791895-finding-all-derived-class-given-parent-class) * [How do I find all anonymous classes created in a class?](https://intellij-support.jetbrains.com/hc/en-us/community/posts/206792205-How-to-find-anonymous-classes-in-PsiClass-) * [How do I calculate the value of a string literal token?](https://intellij-support.jetbrains.com/hc/en-us/community/posts/206139829-How-to-evaluate-the-value-of-PsiJavaToken-of-STRING-LITERAL-type) @@ -41,7 +38,7 @@ This FAQ is a topical index of questions that have been asked (and answered) on * [How do I find the source file given the path to a .class file?](https://intellij-support.jetbrains.com/hc/en-us/community/posts/206800595-How-to-find-the-source-for-a-class-file) * [How do I find classes with the specified non-qualified name?](https://intellij-support.jetbrains.com/hc/en-us/community/posts/206146759-How-to-resolve-unqualified-name-to-possible-PsiClasses-) * [How do I find the module in which a class is located?](https://intellij-support.jetbrains.com/hc/en-us/community/posts/206103859-How-to-get-Module-from-PsiClass-) -* [PSI Cookbook](/basics/psi_cookbook.md) +* [PSI Cookbook](psi_cookbook.md) ## Working with XML and XML DOM * [How do I change the value of an XML attribute through the PSI?](https://intellij-support.jetbrains.com/hc/en-us/community/posts/206139639-Change-xml-attribute-value) @@ -144,4 +141,4 @@ This FAQ is a topical index of questions that have been asked (and answered) on * [How do I open a project programmatically?](https://intellij-support.jetbrains.com/hc/en-us/community/posts/206146969-how-to-open-a-project-) * [How do I get the folder of the currently selected file?](https://intellij-support.jetbrains.com/hc/en-us/community/posts/206121889-How-to-get-the-folder-of-currenctly-selected-file) * [How do I encrypt some values in the configuration data of my plugin?](https://intellij-support.jetbrains.com/hc/en-us/community/posts/206147039-JDOMExternalizable-and-encrypting-) -* [How can I track exceptions from my plugin?](https://intellij-support.jetbrains.com/hc/en-us/community/posts/206762245-How-can-I-track-plugin-s-exceptions-/comments/206112345) +* [How can I track exceptions from my plugin?](https://intellij-support.jetbrains.com/hc/en-us/community/posts/206762245-How-can-I-track-plugin-s-exceptions-/comments/206112345) \ No newline at end of file diff --git a/basics/getting_started.md b/topics/basics/getting_started.md similarity index 68% rename from basics/getting_started.md rename to topics/basics/getting_started.md index 6b0412dff..489b208d2 100644 --- a/basics/getting_started.md +++ b/topics/basics/getting_started.md @@ -1,6 +1,5 @@ ---- -title: Creating Your First Plugin ---- +[//]: # (title: Creating Your First Plugin) + This documentation section will help you get started with developing plugins for the *IntelliJ Platform*. @@ -12,7 +11,9 @@ There are three supported workflows available for building plugins. The recommended workflow for new projects is to [use GitHub Template](#using-github-template) or to [use Gradle](#using-gradle) to create everything from scratch. The old [Plugin DevKit](#using-devkit) workflow still supports existing projects. -> **NOTE** If a new plugin will be Scala-based, a dedicated SBT plugin [sbt-idea-plugin](https://github.com/JetBrains/sbt-idea-plugin) is available. + > If a new plugin will be Scala-based, a dedicated SBT plugin [sbt-idea-plugin](https://github.com/JetBrains/sbt-idea-plugin) is available. + > + {type="note"} The Gradle workflow offers several advantages: * Representations of source sets, modules, and projects are portable, @@ -29,20 +30,20 @@ Specific to development of IntelliJ Platform plugins with the Gradle plugin for * Built-in integration with [IntelliJ Plugin Verifier](https://github.com/JetBrains/intellij-plugin-verifier) tool used for running the compatibility checks as performed on [JetBrains Plugin Repository](https://plugins.jetbrains.com). ## Using GitHub Template -* [Developing plugins using GitHub Template](/tutorials/github_template.md) +* [Developing plugins using GitHub Template](github_template.md) ## Using Gradle -* [Developing plugins using Gradle](/tutorials/build_system.md) - * [Getting Started with Gradle](/tutorials/build_system/prerequisites.md) - * [Configuring Gradle Projects](/tutorials/build_system/gradle_guide.md) - * [Publishing Plugins with Gradle](/tutorials/build_system/deployment.md) +* [Developing plugins using Gradle](gradle_build_system.md) + * [Getting Started with Gradle](gradle_prerequisites.md) + * [Configuring Gradle Projects](gradle_guide.md) + * [Publishing Plugins with Gradle](deployment.md) ## Using DevKit -* [Developing plugins using DevKit](getting_started/using_dev_kit.md) - * [Setting Up a Development Environment](getting_started/setting_up_environment.md) - * [Creating a Plugin Project](getting_started/creating_plugin_project.md) - * [Creating Actions](/tutorials/action_system/working_with_custom_actions.md) - * [Running and Debugging a Plugin](getting_started/running_and_debugging_a_plugin.md) - * [Deploying a Plugin](getting_started/deploying_plugin.md) - * [Publishing a Plugin](getting_started/publishing_plugin.md) +* [Developing plugins using DevKit](using_dev_kit.md) + * [Setting Up a Development Environment](setting_up_environment.md) + * [Creating a Plugin Project](creating_plugin_project.md) + * [Creating Actions](working_with_custom_actions.md) + * [Running and Debugging a Plugin](running_and_debugging_a_plugin.md) + * [Deploying a Plugin](deploying_plugin.md) + * [Publishing a Plugin](publishing_plugin.md) \ No newline at end of file diff --git a/basics/getting_started/build_number_ranges.md b/topics/basics/getting_started/build_number_ranges.md similarity index 89% rename from basics/getting_started/build_number_ranges.md rename to topics/basics/getting_started/build_number_ranges.md index 39ad455cf..da1e19315 100644 --- a/basics/getting_started/build_number_ranges.md +++ b/topics/basics/getting_started/build_number_ranges.md @@ -1,21 +1,12 @@ ---- -title: Build Number Ranges ---- - - +[//]: # (title: Build Number Ranges) Use this reference of build number ranges to specify the correct `since-build` and `until-build` values in your plugin descriptor. -When using Gradle, setting the actual values in `plugin.xml` is usually managed by the `patchPluginXml` task, see [Patching the Plugin Configuration File](/tutorials/build_system/gradle_guide.md#patching-the-plugin-configuration-file) for details. +When using Gradle, setting the actual values in `plugin.xml` is usually managed by the `patchPluginXml` task, see [Patching the Plugin Configuration File](gradle_guide.md#patching-the-plugin-configuration-file) for details. -> **NOTE** Compatibility with specified version range (and compatible products) should always be verified using [Plugin Verifier](/reference_guide/api_changes_list.md#verifying-compatibility) to ensure binary compatibility. + > Compatibility with specified version range (and compatible products) should always be verified using [Plugin Verifier](api_changes_list.md#verifying-compatibility) to ensure binary compatibility. + > + {type="note"} Starting with IntelliJ IDEA 9 beta, a multi-part build number is used, such as `IU-162.94`. @@ -44,11 +35,15 @@ Usually you should omit the product ID and use only the branch number and build ``` -> **NOTE** Specific build numbers and their corresponding release version are available via _Previous Releases_ on the corresponding product's download page, e.g. [Previous IntelliJ IDEA Releases](https://www.jetbrains.com/idea/download/previous.html). + > Specific build numbers and their corresponding release version are available via _Previous Releases_ on the corresponding product's download page, e.g. [Previous IntelliJ IDEA Releases](https://www.jetbrains.com/idea/download/previous.html). + > + {type="note"} ### IntelliJ Platform Based Products of Recent IDE Versions -> **TIP** Which versions should your plugin support? We've collected some insights based on download statistics in [Statistics: Product Versions in Use](https://plugins.jetbrains.com/docs/marketplace/product-versions-in-use-statistics.html). + > Which versions should your plugin support? We've collected some insights based on download statistics in [Statistics: Product Versions in Use](https://plugins.jetbrains.com/docs/marketplace/product-versions-in-use-statistics.html). + > + {type="tip"} | Branch number | IntelliJ Platform version | | --------------------------------------------------------------- | ------------------------- | @@ -156,4 +151,4 @@ The build number for each release: | 6.0.6 | 6197 | | 6.0.5 | 6180 | | 6.0.1 | 5784 | -| 5.1.2 | 4267 | +| 5.1.2 | 4267 | \ No newline at end of file diff --git a/basics/getting_started/creating_plugin_project.md b/topics/basics/getting_started/creating_plugin_project.md similarity index 71% rename from basics/getting_started/creating_plugin_project.md rename to topics/basics/getting_started/creating_plugin_project.md index 61beddc57..186fa11e2 100644 --- a/basics/getting_started/creating_plugin_project.md +++ b/topics/basics/getting_started/creating_plugin_project.md @@ -1,11 +1,10 @@ ---- -title: Creating a Plugin Project -redirect_from: - - /basics/getting_started/creating_an_action.html ---- +[//]: # (title: Creating a Plugin Project) + -> **NOTE** For new projects, it is highly recommended to use [Gradle](/tutorials/build_system.md). + > For new projects, it is highly recommended to use [Gradle](gradle_build_system.md). + > + {type="note"} This section explains how you can create a new plugin project from scratch using the New Project wizard. Optionally, you can import an existing project or import a project from external models. @@ -16,7 +15,7 @@ For more information, refer to the [IntelliJ IDEA Web Help](https://www.jetbrain * On the main menu, choose **File \| New \| Project**. The *New Project* wizard starts. - ![New Project Wizard](img/new_project_wizard.png) + ![New Project Wizard](new_project_wizard.png) * Set *IntelliJ Platform Plugin* project type. * Click **Next**. * Set the desired project name. @@ -25,13 +24,13 @@ For more information, refer to the [IntelliJ IDEA Web Help](https://www.jetbrain ### To Create an IntelliJ Platform Plugin Module * Select **File \| New \| Module** and choose the *IntelliJ Platform Plugin* module type - ![IntelliJ Platform Plugin Module](img/intellij_platform_plugin_module.png) + ![IntelliJ Platform Plugin Module](intellij_platform_plugin_module.png)

* Enter your desired plugin name. * Go to **File \| Project Structure** and select the newly created *IntelliJ Platform SDK* as the default SDK for the plugin module: - ![Set Plugin Module SDK](img/set_plugin_module_sdk.png) + ![Set Plugin Module SDK](set_plugin_module_sdk.png) ### Adding Code to the Project Before running the new project, add some code to provide simple functionality. -See the [Creating Actions](/tutorials/action_system/working_with_custom_actions.md) tutorial for step-by-step instructions for adding a menu action. +See the [Creating Actions](working_with_custom_actions.md) tutorial for step-by-step instructions for adding a menu action. \ No newline at end of file diff --git a/basics/getting_started/deploying_plugin.md b/topics/basics/getting_started/deploying_plugin.md similarity index 76% rename from basics/getting_started/deploying_plugin.md rename to topics/basics/getting_started/deploying_plugin.md index 47c24e128..e2beed0f1 100644 --- a/basics/getting_started/deploying_plugin.md +++ b/topics/basics/getting_started/deploying_plugin.md @@ -1,6 +1,5 @@ ---- -title: Deploying a Plugin ---- +[//]: # (title: Deploying a Plugin) + Before your custom plugin can be used, it must be deployed: built, installed, and then enabled using Plugin Manager. @@ -11,17 +10,17 @@ To deploy a plugin: * Prepare your plugin for deployment. In the main menu, select **Build \| Prepare Plugin Module \ for Deployment**. - ![Prepare Plugin for Deployment](deploying_plugin/img/prepare_plugin_for_deployment.png) + ![Prepare Plugin for Deployment](prepare_plugin_for_deployment.png) * If the plugin module does not depend on any libraries, a `.jar` archive will be created. Otherwise, a `.zip` archive will be created, including all the plugin libraries specified in the project settings. - ![Jar Saved Notification](deploying_plugin/img/jar_saved_notification.png) + ![Jar Saved Notification](jar_saved_notification.png) * [Install](https://www.jetbrains.com/help/idea/managing-plugins.html#installing-plugins-from-disk) the newly created archive/jar file from disk. The `editor_basics` code sample builds the plugin archive/jar into the `editor_basics` project folder: - ![Jar File Location](deploying_plugin/img/jar_location.png) + ![Jar File Location](jar_location.png) -* Restart your IDE so the changes will take effect. +* Restart your IDE so the changes will take effect. \ No newline at end of file diff --git a/basics/getting_started/plugin_compatibility.md b/topics/basics/getting_started/plugin_compatibility.md similarity index 84% rename from basics/getting_started/plugin_compatibility.md rename to topics/basics/getting_started/plugin_compatibility.md index fd3902665..ae20b85ab 100644 --- a/basics/getting_started/plugin_compatibility.md +++ b/topics/basics/getting_started/plugin_compatibility.md @@ -1,16 +1,6 @@ ---- -title: Plugin Compatibility with IntelliJ Platform Products ---- - +[//]: # (title: Plugin Compatibility with IntelliJ Platform Products) - + ## Introduction All products based on the _IntelliJ Platform_ are built on the same underlying API. @@ -19,17 +9,16 @@ Underlying those shared features are shared components. When authoring a plugin for the IntelliJ Platform, it is important to understand and declare dependencies on these components. Otherwise, it may not be possible to load or run the plugin in a product because the components on which it depends aren't available. -> **TIP** Qualifying Open Source projects can [apply for free licenses](https://www.jetbrains.com/community/opensource/) of JetBrains products. - -* bullet list -{:toc} + > Qualifying Open Source projects can [apply for free licenses](https://www.jetbrains.com/community/opensource/) of JetBrains products. + > + {type="tip"} ## Declaring Plugin Dependencies For the purposes of dependencies, a _module_ can be thought of like a built-in plugin that ships as a non-removable part of a product. A working definition of a dependency is that a plugin project cannot be run without the module present in an IntelliJ Platform-based product. Declaring a dependency on a module also expresses a plugin's compatibility with a product in that the IntelliJ Platform determines whether a product contains the correct modules to support a plugin before loading it. -[Part I](/basics/plugin_structure/plugin_dependencies.md) of this document describes the syntax for declaring plugin dependencies and optional plugin dependencies. +[Part I](plugin_dependencies.md) of this document describes the syntax for declaring plugin dependencies and optional plugin dependencies. Part II of this document (below) describes the IntelliJ Platform modules' functionality to aid in determining the dependencies of a plugin. The way dependency declarations are handled by the Intellij Platform is determined by the contents of the `plugin.xml` file: @@ -50,9 +39,11 @@ A core set of modules are available in all products based on the IntelliJ Platfo These modules provide a set of shared functionality. The following table lists modules that are currently available in all products. -> **NOTE** All plugins should declare a dependency on **`com.intellij.modules.platform`** to indicate dependence on shared functionality. + > All plugins should declare a dependency on **`com.intellij.modules.platform`** to indicate dependence on shared functionality. + > + {type="note"} -| Module for `` Element
Declaration in `plugin.xml` File |
Functionality | +| Module for `` Element
Declaration in `plugin.xml` File |
Functionality | | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | | **`com.intellij.modules.platform`** | Messaging, UI Themes, UI Components, Files, Documents, Actions, Components, Services, Extensions, Editors | | `com.intellij.modules.lang` | File Type, Lexer, Parser, Highlighting, References, Code Completion, Find, Rename, Formatter, Code Navigation | @@ -73,9 +64,9 @@ A plugin project is compatible with PHP functionality if it declares a dependenc The following table lists **(1)** modules or built-in plugins that provide specific functionality, and the products currently shipping with them. -| Module or Plugin for `` Element
Declaration in `plugin.xml` File |
Functionality | IntelliJ Platform-Based
Product Compatibility | +| Module or Plugin for `` Element
Declaration in `plugin.xml` File |
Functionality | IntelliJ Platform-Based
Product Compatibility | | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `com.intellij.modules.java` See **(2)** below.
`com.intellij.java` | **Java** language PSI Model, Inspections, Intentions, Completion, Refactoring, Test Framework | IntelliJ IDEA, Android Studio | +| `com.intellij.modules.java` See **(2)** below.
`com.intellij.java` | **Java** language PSI Model, Inspections, Intentions, Completion, Refactoring, Test Framework | IntelliJ IDEA, Android Studio | | `com.intellij.modules.androidstudio` | Android SDK Platform, Build Tools, Platform Tools, SDK Tools | Android Studio | | `com.intellij.modules.appcode` | CocoaPods, Core Data Objects, Device & Simulator Support | AppCode | | `com.intellij.modules.cidr.lang` | **C, C++, Objective-C/C++** language PSI Model, Swift/Objective-C Interaction, Inspections, Intentions, Completion, Refactoring, Test Framework | AppCode, CLion | @@ -97,7 +88,7 @@ To see a list of modules, invoke the [code completion](https://www.jetbrains.com **(2)** The [Java language functionality](https://blog.jetbrains.com/platform/2019/06/java-functionality-extracted-as-a-plugin/) was extracted as a plugin in version 2019.2 of the IntelliJ Platform. This refactoring separated the Java implementation from the other, non-language portions of the platform. -Consequently, [dependencies](/basics/plugin_structure/plugin_dependencies.md) on Java functionality are expressed differently in `plugin.xml` depending on the version of the IntelliJ Platform being targeted: +Consequently, [dependencies](plugin_dependencies.md) on Java functionality are expressed differently in `plugin.xml` depending on the version of the IntelliJ Platform being targeted: * Syntax for 2019.2 and later releases: * `plugin.xml` _allowable alternative_ add `com.intellij.java` @@ -106,7 +97,7 @@ Consequently, [dependencies](/basics/plugin_structure/plugin_dependencies.md) on * `plugin.xml` add `com.intellij.modules.java` ## Exploring Module and Plugin APIs -Once the [dependency on a module or plugin](/basics/plugin_structure/plugin_dependencies.md) is declared in `plugin.xml`, it's useful to explore the packages and classes available in that dependency. +Once the [dependency on a module or plugin](plugin_dependencies.md) is declared in `plugin.xml`, it's useful to explore the packages and classes available in that dependency. The section below gives some recommended procedures for discovering what's available in a module or plugin on which a project depends. These procedures assume a project has the `build.gradle` and `plugin.xml` dependencies configured correctly. @@ -118,15 +109,15 @@ Reimporting the project will automatically update the dependencies. In the Project Window, select Project View and scroll to the bottom to see [External Libraries](https://www.jetbrains.com/help/idea/project-tool-window.html#content_pane). Look for the library `Gradle:unzipped.com.jetbrains.plugins:foo:`, where "foo" matches, or is similar to the contents of the `` tags in `plugin.xml` or the `intellij.plugins` declaration in `build.gradle`. -The image below shows the External Libraries for the example plugin project configuration explained in [Configuring build.gradle](/products/dev_alternate_products.md#configuring-buildgradle-using-the-intellij-idea-product-attribute) and [Configuring plugin.xml](/products/dev_alternate_products.md#configuring-pluginxml). +The image below shows the External Libraries for the example plugin project configuration explained in [Configuring build.gradle](dev_alternate_products.md#configuring-buildgradle-using-the-intellij-idea-product-attribute) and [Configuring plugin.xml](dev_alternate_products.md#configuring-pluginxml). -![Example PhpStorm Project Libraries](img/php_prj_libs.png){:width="700px"} +![Example PhpStorm Project Libraries](php_prj_libs.png){width="700"} Expand the External Library (as shown) to reveal the JAR files contained in the library. Drill down into the JAR files to expose the packages and (decompiled) classes. ### Exploring APIs as an Extender -If a project is dependent on a plugin or module, in some cases, the project can also [extend](/basics/plugin_structure/plugin_extensions.md) the functionality available from the plugin or module. +If a project is dependent on a plugin or module, in some cases, the project can also [extend](plugin_extensions.md) the functionality available from the plugin or module. To browse the opportunities for extension, start by placing the cursor on the contents of the `` elements in the project's `plugin.xml` file. Use the [Go to Declaration](https://www.jetbrains.com/help/idea/navigating-through-the-source-code.html#go_to_declaration) IDE feature to navigate to the `plugin.xml` file for the plugin on which the project depends. @@ -138,13 +129,12 @@ Continuing the example, search the PHP plugin's `plugin.xml` file for: * `` to find where the PHP plugin extends functionality. The extension namespace (in this example `com.jetbrains.php`) will match the `` defined in the `plugin.xml` file. - ## Verifying Dependency Before marking a plugin project as _dependent only on modules in a target product_ in addition to `com.intellij.modules.platform`, verify the plugin isn't implicitly dependent on any APIs that are specific to IntelliJ IDEA. -For [Gradle-based](/tutorials/build_system.md) projects, [Plugin Verifier](/reference_guide/api_changes_list.md#plugin-verifier) can be used to ensure compatibility with all specified target IDEs. +For [Gradle-based](gradle_build_system.md) projects, [Plugin Verifier](api_changes_list.md#plugin-verifier) can be used to ensure compatibility with all specified target IDEs. -For [DevKit-based](/basics/getting_started/using_dev_kit.md) projects, create an SDK pointing to an installation of the intended target IntelliJ Platform-based product, e.g., PhpStorm, rather than IntelliJ IDEA. +For [DevKit-based](using_dev_kit.md) projects, create an SDK pointing to an installation of the intended target IntelliJ Platform-based product, e.g., PhpStorm, rather than IntelliJ IDEA. Use the same development version of the IntelliJ platform as the targeted product. Based on the tables above, the [JetBrains Plugins Repository](https://plugins.jetbrains.com/) automatically detects the JetBrains products with which a plugin is compatible, and makes the compatibility information available to plugin authors. @@ -152,4 +142,4 @@ The compatibility information determines if plugins are available at the plugin ## Platform API Version Compatibility The API of _IntelliJ Platform_ and bundled plugins may change between releases. -The significant changes that may break plugins are listed on [Incompatible Changes in IntelliJ Platform and Plugins API](/reference_guide/api_changes_list.md) page. +The significant changes that may break plugins are listed on [Incompatible Changes in IntelliJ Platform and Plugins API](api_changes_list.md) page. \ No newline at end of file diff --git a/basics/getting_started/publishing_plugin.md b/topics/basics/getting_started/publishing_plugin.md similarity index 84% rename from basics/getting_started/publishing_plugin.md rename to topics/basics/getting_started/publishing_plugin.md index 9cb98e6e7..db682d3c1 100644 --- a/basics/getting_started/publishing_plugin.md +++ b/topics/basics/getting_started/publishing_plugin.md @@ -1,12 +1,13 @@ ---- -title: Publishing a Plugin ---- +[//]: # (title: Publishing a Plugin) + When your plugin is ready, you can publish it to a plugin repository so that other users can install it. -You can choose to publish it on the [JetBrains Plugins Repository](https://plugins.jetbrains.com) or a [custom plugin repository](/basics/getting_started/update_plugins_format.md). +You can choose to publish it on the [JetBrains Plugins Repository](https://plugins.jetbrains.com) or a [custom plugin repository](update_plugins_format.md). -> **TIP** Please see [Marketing](/appendix/resources/marketing.md) for remarks on how to prepare your plugin for optimal presentation. + > Please see [Marketing](marketing.md) for remarks on how to prepare your plugin for optimal presentation. + > + {type="tip"} ### Publishing to the JetBrains Plugins Repository To upload your plugin to the [JetBrains Plugins Repository](https://plugins.jetbrains.com), you must log in with your personal JetBrains Account. @@ -23,4 +24,4 @@ To upload your plugin to the [JetBrains Plugins Repository](https://plugins.jetb 3. Fill in the **Add new plugin** form that opens and click the **Add the plugin** button to upload your plugin. ### Publishing a Plugin to a Custom Plugin Repository -If you plan to publish your plugin to a repository _other than_ the [JetBrains Plugins Repository](https://plugins.jetbrains.com), please refer to the [Publishing to Custom Plugin Repositories](update_plugins_format.md) documentation. +If you plan to publish your plugin to a repository _other than_ the [JetBrains Plugins Repository](https://plugins.jetbrains.com), please refer to the [Publishing to Custom Plugin Repositories](update_plugins_format.md) documentation. \ No newline at end of file diff --git a/basics/getting_started/running_and_debugging_a_plugin.md b/topics/basics/getting_started/running_and_debugging_a_plugin.md similarity index 84% rename from basics/getting_started/running_and_debugging_a_plugin.md rename to topics/basics/getting_started/running_and_debugging_a_plugin.md index bde47fe73..8150ebae5 100644 --- a/basics/getting_started/running_and_debugging_a_plugin.md +++ b/topics/basics/getting_started/running_and_debugging_a_plugin.md @@ -1,13 +1,12 @@ ---- -title: Running and Debugging a Plugin ---- +[//]: # (title: Running and Debugging a Plugin) + It's possible to run and debug a plugin directly from the *IntelliJ IDEA*. You need a configured special profile (a *Plugin* Run/Debug configuration) that specifies the plugin module, VM parameters, and other specific options. When you run such a profile, it launches the IDE with your plugin installed. -See [IDE Development Instances](/basics/ide_development_instance.md) for more information about configuration and advanced settings. +See [IDE Development Instances](ide_development_instance.md) for more information about configuration and advanced settings. For information on how to change the Run/Debug configuration profile, refer to [Run/Debug Configuration](https://www.jetbrains.com/help/idea/run-debug-configuration.html) and [Run/Debug Configuration: Plugin](https://www.jetbrains.com/idea/help/run-debug-configuration-plugin.html) in *IntelliJ IDEA* Web Help. @@ -19,4 +18,4 @@ Using *IntelliJ IDEA*'s debugger, you can find out the origin of the run-time er **To run a plugin** -* Select **Run \| Run** in the main menu, or press Shift + F10. +* Select **Run \| Run** in the main menu, or press Shift + F10. \ No newline at end of file diff --git a/basics/getting_started/setting_up_environment.md b/topics/basics/getting_started/setting_up_environment.md similarity index 72% rename from basics/getting_started/setting_up_environment.md rename to topics/basics/getting_started/setting_up_environment.md index 467694601..14a682919 100644 --- a/basics/getting_started/setting_up_environment.md +++ b/topics/basics/getting_started/setting_up_environment.md @@ -1,9 +1,10 @@ ---- -title: Setting Up a Development Environment ---- +[//]: # (title: Setting Up a Development Environment) + -> **NOTE** For new projects, it is highly recommended to use [Gradle](/tutorials/build_system.md). + > For new projects, it is highly recommended to use [Gradle](gradle_build_system.md). + > + {type="note"} ### Preliminary Steps @@ -22,25 +23,25 @@ Use the following checklist to ensure that you are ready to develop your custom To set up your plugin development environment: * Create a new *IntelliJ Platform SDK* under **File \| Project Structure**: - ![Create IntelliJ Platform SDK](img/create_intellij_idea_sdk.png) + ![Create IntelliJ Platform SDK](create_intellij_idea_sdk.png)

* Specify the installation folder of the *IntelliJ IDEA Community Edition* as the home directory. - > **WARNING** You may use IntelliJ IDEA Ultimate as an alternative, but debugging the core code will only work with the *Community Edition*. - ![Set Home Directory](img/set_home_directory.png) + > You may use IntelliJ IDEA Ultimate as an alternative, but debugging the core code will only work with the *Community Edition*. + ![Set Home Directory](set_home_directory.png)

* Select **1.8** as the default Java SDK. See the _IntelliJ Build Configuration_ section of [Check Out And Build Community Edition](upsource:///README.md) for instructions about creating **1.8** Java SDK. - ![Set IDEA JDK](img/set_java_sdk.png) + ![Set IDEA JDK](set_java_sdk.png)

* In the Sourcepath tab of the SDK settings, click the *Add* button: - ![Add Sourcepath](img/add_sourcepath.png) + ![Add Sourcepath](add_sourcepath.png)

* Specify the source code directory for the *IntelliJ IDEA Community Edition*: - ![Specify Source Paths](img/community_sources_directory.png) + ![Specify Source Paths](community_sources_directory.png)

* Specify the **Sandbox Home** directory. @@ -48,7 +49,9 @@ To set up your plugin development environment: Shown below is the default *Sandbox Home* directory for a user on Mac OS X. Any directory can be chosen as the *Sandbox Home* location. Use the ellipsis button (shown below) to define a custom location. + > + {type="warning"} - See the [IDE Development Instances](/basics/ide_development_instance.md) page for more information about default *Sandbox Home* directory locations and contents. + See the [IDE Development Instances](ide_development_instance.md) page for more information about default *Sandbox Home* directory locations and contents. - ![Specify Sandbox Path](img/plugins-sandbox.png) + ![Specify Sandbox Path](plugins-sandbox.png) \ No newline at end of file diff --git a/basics/getting_started/update_plugins_format.md b/topics/basics/getting_started/update_plugins_format.md similarity index 74% rename from basics/getting_started/update_plugins_format.md rename to topics/basics/getting_started/update_plugins_format.md index 190a9bb25..050b466a5 100644 --- a/basics/getting_started/update_plugins_format.md +++ b/topics/basics/getting_started/update_plugins_format.md @@ -1,6 +1,5 @@ ---- -title: Publishing a Plugin to a Custom Plugin Repository ---- +[//]: # (title: Publishing a Plugin to a Custom Plugin Repository) + If you intend to use a plugin repository _other than_ the [JetBrains Plugins Repository](https://plugins.jetbrains.com), you will need to: @@ -10,7 +9,9 @@ If you intend to use a plugin repository _other than_ the [JetBrains Plugins Rep This can be the same web server you are using for the custom repository or a different HTTPS web server. * Add the URL for the custom repository to the JetBrains IDE [Repository Settings/Preferences](https://www.jetbrains.com/help/idea/managing-plugins.html#repos). -> **TIP** Gradle plugin [IntelliJ plugin uploader](https://github.com/brian-mcnamara/plugin_uploader) can be used to automate deployment. + > Gradle plugin [IntelliJ plugin uploader](https://github.com/brian-mcnamara/plugin_uploader) can be used to automate deployment. + > + {type="tip"} ## Describing Your Plugins in updatePlugins.xml File Every custom plugin repository must have at least one `updatePlugins.xml` file to describe every hosted plugin's latest available version. @@ -68,6 +69,6 @@ Here are the candidate elements: | Element | Effects & Requirements | |:-------------------------------------------------------------|:----------------------------| -| ``
My Plugin Name
`` | By default the name of the plugin JAR/ZIP file is displayed before installation.
Using the `` element displays the name of the plugin.
Contents should match the `` element contents in the plugins's `plugin.xml` file to avoid confusion. | -| ``
My plugin is awesome
`` | By default no description for the plugin is displayed before installation.
Using the `` element will cause a description to be displayed before installation.
Contents should match the `` element contents in the plugins's `plugin.xml` file to avoid confusion.
Optionally, an enclosing `` element can be used if the description needs to contain HTML tags. | -| ``
Added cool feature
`` | By default no change notes for the plugin are displayed before installation.
Using the `` element will cause a description of changes to be displayed before installation.
Contents should match the `` element contents in the plugin's `plugin.xml` file to avoid confusion.
Optionally, an enclosing `` element can be used if the change notes need to contain HTML tags. | +| ``
My Plugin Name
`` | By default the name of the plugin JAR/ZIP file is displayed before installation.
Using the `` element displays the name of the plugin.
Contents should match the `` element contents in the plugins's `plugin.xml` file to avoid confusion. | +| ``
My plugin is awesome
`` | By default no description for the plugin is displayed before installation.
Using the `` element will cause a description to be displayed before installation.
Contents should match the `` element contents in the plugins's `plugin.xml` file to avoid confusion.
Optionally, an enclosing `` element can be used if the description needs to contain HTML tags. | +| ``
Added cool feature
`` | By default no change notes for the plugin are displayed before installation.
Using the `` element will cause a description of changes to be displayed before installation.
Contents should match the `` element contents in the plugin's `plugin.xml` file to avoid confusion.
Optionally, an enclosing `` element can be used if the change notes need to contain HTML tags. | \ No newline at end of file diff --git a/basics/getting_started/using_dev_kit.md b/topics/basics/getting_started/using_dev_kit.md similarity index 72% rename from basics/getting_started/using_dev_kit.md rename to topics/basics/getting_started/using_dev_kit.md index c342d5fac..3892304b5 100644 --- a/basics/getting_started/using_dev_kit.md +++ b/topics/basics/getting_started/using_dev_kit.md @@ -1,9 +1,10 @@ ---- -title: Using DevKit ---- +[//]: # (title: Using DevKit) + -> **NOTE** For new projects, it is highly recommended to use [Gradle](/tutorials/build_system.md). + > For new projects, it is highly recommended to use [Gradle](gradle_build_system.md). + > + {type="note"} _Plugin DevKit_ is a bundled IntelliJ IDEA plugin for developing plugins for the IntelliJ Platform using IntelliJ IDEA's build system. It provides its custom SDK type and a set of actions for building plugins within the IDE. @@ -12,7 +13,7 @@ In this section: * [Setting Up a Development Environment](setting_up_environment.md) * [Creating a Plugin Project](creating_plugin_project.md) -* [Creating Actions](/tutorials/action_system/working_with_custom_actions.md) +* [Creating Actions](working_with_custom_actions.md) * [Running and Debugging a Plugin](running_and_debugging_a_plugin.md) * [Deploying a Plugin](deploying_plugin.md) -* [Publishing a Plugin](publishing_plugin.md) +* [Publishing a Plugin](publishing_plugin.md) \ No newline at end of file diff --git a/basics/ide_development_instance.md b/topics/basics/ide_development_instance.md similarity index 79% rename from basics/ide_development_instance.md rename to topics/basics/ide_development_instance.md index c0634c9b0..cbb9cee8f 100644 --- a/basics/ide_development_instance.md +++ b/topics/basics/ide_development_instance.md @@ -1,15 +1,14 @@ ---- -title: IDE Development Instances -redirect_from: - - /basics/settings_caches_logs.html ---- +[//]: # (title: IDE Development Instances) + A JetBrains feature for developing plugins is running or debugging a plugin project from within an IntelliJ Platform-based IDE such as IntelliJ IDEA. -Selecting the [**runIde**](/tutorials/build_system/prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin) task for a Gradle-based project (or [**Run**](getting_started/running_and_debugging_a_plugin.md) menu for a DevKit-based project) will launch a _Development Instance_ of the IDE with the plugin enabled. +Selecting the [**runIde**](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin) task for a Gradle-based project (or [**Run**](running_and_debugging_a_plugin.md) menu for a DevKit-based project) will launch a _Development Instance_ of the IDE with the plugin enabled. This page describes how to control some of the settings for the Development Instance. -> **TIP** Please see also [Advanced Configuration](https://www.jetbrains.com/help/idea/tuning-the-ide.html) for general VM options and properties. + > Please see also [Advanced Configuration](https://www.jetbrains.com/help/idea/tuning-the-ide.html) for general VM options and properties. + > + {type="tip"} ## Using a JetBrains Runtime for the Development Instance An everyday use case is to develop (build) a plugin project against a JDK, e.g., Java 8, and then run or debug the plugin in a Development Instance of the IDE. @@ -44,39 +43,37 @@ The [Run Configuration](https://www.jetbrains.com/help/idea/run-debug-configurat The default Run Configuration uses the same JDK for building the plugin project and running the plugin in a Development Instance. To change the runtime for the Development Instance, set the _JRE_ field in the Run Configuration edit dialog to download a JetBrains Runtime. - ## Enabling Auto-Reload -Starting in 2020.1, this is available for compatible [dynamic plugins](/basics/plugin_structure/dynamic_plugins.md). +Starting in 2020.1, this is available for compatible [dynamic plugins](dynamic_plugins.md). This allows a much faster development cycle by avoiding a full restart of the development instance after detecting code changes (when JARs are modified). Please note that any unloading problems in a production environment will ask the user to restart the IDE. ### Gradle plugin 0.4.22 and Later Enabled by default for target platform 2020.2 or later. -Set `autoReloadPlugins = true` in [**runIde**](/tutorials/build_system/prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin) task to enable it for earlier platform versions or `autoReloadPlugins = false` to disable it explicitly. +Set `autoReloadPlugins = true` in [**runIde**](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin) task to enable it for earlier platform versions or `autoReloadPlugins = false` to disable it explicitly. ### Gradle plugin 0.4.21 and Earlier/DevKit -Add system property `idea.auto.reload.plugins` in the [run configuration](getting_started/running_and_debugging_a_plugin.md) (DevKit-based) or [**runIde**](/tutorials/build_system/prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin) task (Gradle-based). -For [Gradle-based plugins](/tutorials/build_system/prerequisites.md) using `gradle-intellij-plugin` 0.4.17 or later, this property is set automatically. +Add system property `idea.auto.reload.plugins` in the [run configuration](running_and_debugging_a_plugin.md) (DevKit-based) or [**runIde**](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin) task (Gradle-based). +For [Gradle-based plugins](gradle_prerequisites.md) using `gradle-intellij-plugin` 0.4.17 or later, this property is set automatically. To disable auto-reload, set `idea.auto.reload.plugins` to `false` explicitly (2020.1.2+). - ## The Development Instance Sandbox Directory The _Sandbox Home_ directory contains the [settings, caches, logs, and plugins](#development-instance-settings-caches-logs-and-plugins) for a Development Instance of the IDE. This information is stored in a different location than for the [installed IDE itself](https://intellij-support.jetbrains.com/hc/en-us/articles/206544519-Directories-used-by-the-IDE-to-store-settings-caches-plugins-and-logs). ### Sandbox Home Location for Gradle-Based Plugin Projects For Gradle-based plugins, the default Sandbox Home location is defined by the IntelliJ Platform `gradle-intellij-plugin`. -See [Configuring a Gradle Plugin Project](/tutorials/build_system/prerequisites.md) for more information about specifying a Sandbox Home location. +See [Configuring a Gradle Plugin Project](gradle_prerequisites.md) for more information about specifying a Sandbox Home location. The default Sandbox Home location for Gradle-based plugin projects is: * **Windows** `\build\idea-sandbox` * **Linux or macOS** `/build/idea-sandbox` ### Sandbox Home Location for DevKit-Based Plugin Projects For DevKit-based plugins, the default Sandbox Home location is defined in the IntelliJ Platform Plugin SDK. -See specifying the [Sandbox Home for DevKit Projects](/basics/getting_started/setting_up_environment.md) for more information. +See specifying the [Sandbox Home for DevKit Projects](setting_up_environment.md) for more information. The default Sandbox Home directory location for DevKit-based plugin projects is: * **Windows:** `\.\system\plugins-sandbox\` * **Linux:** `~/./system/plugins-sandbox/` @@ -90,4 +87,4 @@ Within the Sandbox Home directory are subdirectories of the Development Instance * `system/log` or `system\log` contains the `idea.log` file for the IDE instance. Each of these Sandbox Home subdirectories can be manually cleared to reset the IDE Development Instance. -At the next launch of a Development Instance, the subdirectories will be repopulated with the appropriate information. +At the next launch of a Development Instance, the subdirectories will be repopulated with the appropriate information. \ No newline at end of file diff --git a/basics/indexing_and_psi_stubs.md b/topics/basics/indexing_and_psi_stubs.md similarity index 86% rename from basics/indexing_and_psi_stubs.md rename to topics/basics/indexing_and_psi_stubs.md index 092a12bbc..c3b9c352e 100644 --- a/basics/indexing_and_psi_stubs.md +++ b/topics/basics/indexing_and_psi_stubs.md @@ -1,6 +1,5 @@ ---- -title: Indexing and PSI Stubs ---- +[//]: # (title: Indexing and PSI Stubs) + ## Indices @@ -10,8 +9,8 @@ Plugin developers can use the existing indexes built by the IDE itself and build It supports two main types of indexes: -* [File-based indices](/basics/indexing_and_psi_stubs/file_based_indexes.md) -* [Stub indices](/basics/indexing_and_psi_stubs/stub_indexes.md) +* [File-based indices](file_based_indexes.md) +* [Stub indices](stub_indexes.md) File-based indexes are built directly over the content of files. Stub indexes are built over serialized *stub trees*. @@ -21,8 +20,10 @@ Querying a file-based index gets you the set of files matching a specific condit Querying a stub index gets you the set of matching PSI elements. Therefore, custom language plugin developers should typically use stub indexes in their plugin implementations. -> **TIP** [Indices Viewer](https://plugins.jetbrains.com/plugin/13029-indices-viewer/) is a plugin that helps to inspect indices' contents and properties. -Please see also [Improving indexing performance](/reference_guide/performance/performance.md#improving-indexing-performance). + > [Indices Viewer](https://plugins.jetbrains.com/plugin/13029-indices-viewer/) is a plugin that helps to inspect indices' contents and properties. +Please see also [Improving indexing performance](performance.md#improving-indexing-performance). + > + {type="tip"} ## Dumb Mode diff --git a/basics/indexing_and_psi_stubs/file_based_indexes.md b/topics/basics/indexing_and_psi_stubs/file_based_indexes.md similarity index 87% rename from basics/indexing_and_psi_stubs/file_based_indexes.md rename to topics/basics/indexing_and_psi_stubs/file_based_indexes.md index e2b06d6b1..05257695d 100644 --- a/basics/indexing_and_psi_stubs/file_based_indexes.md +++ b/topics/basics/indexing_and_psi_stubs/file_based_indexes.md @@ -1,6 +1,5 @@ ---- -title: File-Based Indexes ---- +[//]: # (title: File-Based Indexes) + File-based indexes are based on a Map/Reduce architecture. @@ -41,10 +40,14 @@ An implementation of a file-based index consists of the following main parts: If you don't need to associate any value with the files (i.e., your value type is `Void`), you can simplify the implementation by using [`ScalarIndexExtension`](upsource:///platform/indexing-api/src/com/intellij/util/indexing/ScalarIndexExtension.java) as the base class. -> **WARNING** The data returned by `DataIndexer.map()` must depend only on input data passed to the method, and must not depend on any external files. + > The data returned by `DataIndexer.map()` must depend only on input data passed to the method, and must not depend on any external files. > Otherwise, your index will not be correctly updated when the external data changes, and you will have stale data in your index. + > + {type="warning"} -> **NOTE** Please see `com.intellij.util.indexing.DebugAssertions` on how to enable additional debugging assertions during development to assert correct index implementation. + > Please see `com.intellij.util.indexing.DebugAssertions` on how to enable additional debugging assertions during development to assert correct index implementation. + > + {type="note"} ## Accessing a File-Based Index @@ -54,14 +57,18 @@ The following primary operations are supported: * `getAllKeys()` and `processAllKeys()` allow obtaining the list of all keys found in files, which are a part of the specified project. -> **NOTE** The returned data is guaranteed to contain all keys found in up-to-date project content, but may also include additional keys not currently found in the project. + > The returned data is guaranteed to contain all keys found in up-to-date project content, but may also include additional keys not currently found in the project. + > + {type="note"} * `getValues()` allows to get all values associated with a specific key but not the files in which they were found. * `getContainingFiles()` allows collecting all files in which a particular key was encountered. * `processValues()` allows iterating through all files in which a specific key was encountered and accessing the associated values simultaneously. -> **WARNING** Nested index access is forbidden as it might lead to a deadlock. + > Nested index access is forbidden as it might lead to a deadlock. > Collect all necessary data from index A first, then process results while accessing index B. + > + {type="warning"} ## Standard Indexes @@ -76,4 +83,4 @@ Generally, the word index should be accessed indirectly by using helper methods [`FilenameIndex`](upsource:///platform/indexing-api/src/com/intellij/psi/search/FilenameIndex.java) provides a quick way to find all files matching a specific file name. ### File Type Index -[`FileTypeIndex`](upsource:///platform/indexing-api/src/com/intellij/psi/search/FileTypeIndex.java) serves a similar goal: it allows to find all files of a particular [`FileType`](upsource:///platform/core-api/src/com/intellij/openapi/fileTypes/FileType.java) quickly. +[`FileTypeIndex`](upsource:///platform/indexing-api/src/com/intellij/psi/search/FileTypeIndex.java) serves a similar goal: it allows to find all files of a particular [`FileType`](upsource:///platform/core-api/src/com/intellij/openapi/fileTypes/FileType.java) quickly. \ No newline at end of file diff --git a/basics/indexing_and_psi_stubs/stub_indexes.md b/topics/basics/indexing_and_psi_stubs/stub_indexes.md similarity index 95% rename from basics/indexing_and_psi_stubs/stub_indexes.md rename to topics/basics/indexing_and_psi_stubs/stub_indexes.md index efcda6bb9..c4990ab98 100644 --- a/basics/indexing_and_psi_stubs/stub_indexes.md +++ b/topics/basics/indexing_and_psi_stubs/stub_indexes.md @@ -1,6 +1,5 @@ ---- -title: Stub Indexes ---- +[//]: # (title: Stub Indexes) + ## Stub Trees @@ -49,12 +48,16 @@ This will cause the stubs and stub indices to be rebuilt, and will avoid mismatc By default, if a PSI element extends `StubBasedPsiElement`, all elements of that type will be stored in the stub tree. If you need more precise control over which elements are stored, override `IStubElementType.shouldCreateStub()` and return `false` for elements that should not be included in the stub tree. -> **NOTE** The exclusion is not recursive: if some elements of the element for which you returned false are also stub-based PSI elements, they will be included in the stub tree. + > The exclusion is not recursive: if some elements of the element for which you returned false are also stub-based PSI elements, they will be included in the stub tree. + > + {type="note"} It's essential to ensure that all information stored in the stub tree depends only on the contents of the file for which stubs are being built, and does not depend on any external files. Otherwise, the stub tree will not be rebuilt when external dependency changes, and you will have stale and incorrect data in the stub tree. -> **TIP** Please see also [Improving indexing performance](/reference_guide/performance/performance.md#improving-indexing-performance). + > Please see also [Improving indexing performance](performance.md#improving-indexing-performance). + > + {type="tip"} ## Stub Indexes @@ -76,4 +79,4 @@ To access the data from an index, the following two methods are used: ## Related Forum Discussions -* [Lifecycle of stub creation](https://intellij-support.jetbrains.com/hc/en-us/community/posts/206121959-Lifecycle-of-stub-creation/comments/206143885) +* [Lifecycle of stub creation](https://intellij-support.jetbrains.com/hc/en-us/community/posts/206121959-Lifecycle-of-stub-creation/comments/206143885) \ No newline at end of file diff --git a/basics/intellij_coding_guidelines.md b/topics/basics/intellij_coding_guidelines.md similarity index 98% rename from basics/intellij_coding_guidelines.md rename to topics/basics/intellij_coding_guidelines.md index a7fb8fedd..db5ca7083 100644 --- a/basics/intellij_coding_guidelines.md +++ b/topics/basics/intellij_coding_guidelines.md @@ -1,6 +1,5 @@ ---- -title: IntelliJ Platform Coding Guidelines ---- +[//]: # (title: IntelliJ Platform Coding Guidelines) + If you are writing code that you would like to contribute to the IntelliJ Platform (either as a patch or as a plugin), following these guidelines will make it easier for the JetBrains development team to review and accept your changes. @@ -59,4 +58,4 @@ The ideal pull request would contain one commit with everything needed to fix th The best would be to commit early, but then to squash all commits into one with a descriptive commit message. -Sometimes several commits for a single issue are also acceptable, but each of these should be self-contained "steps" to solve the problem. +Sometimes several commits for a single issue are also acceptable, but each of these should be self-contained "steps" to solve the problem. \ No newline at end of file diff --git a/basics/persistence.md b/topics/basics/persistence.md similarity index 52% rename from basics/persistence.md rename to topics/basics/persistence.md index 6c503086c..537a2153d 100644 --- a/basics/persistence.md +++ b/topics/basics/persistence.md @@ -1,11 +1,10 @@ ---- -title: Persistence Model ---- +[//]: # (title: Persistence Model) + The IntelliJ Platform Persistence Model is used to store a variety of information. -For example, [Run Configurations](run_configurations.md) and [Settings](settings.md) are stored using the Persistence Model. +For example, [Run Configurations](basic_run_configurations.md) and [Settings](settings.md) are stored using the Persistence Model. There are two distinct approaches, depending on the type of data being persisted: -* [Persisting State of Components](/basics/persisting_state_of_components.md) -* [Persisting Sensitive Data](/basics/persisting_sensitive_data.md) +* [Persisting State of Components](persisting_state_of_components.md) +* [Persisting Sensitive Data](persisting_sensitive_data.md) \ No newline at end of file diff --git a/basics/persisting_sensitive_data.md b/topics/basics/persisting_sensitive_data.md similarity index 95% rename from basics/persisting_sensitive_data.md rename to topics/basics/persisting_sensitive_data.md index 054185ce2..86da55a3f 100644 --- a/basics/persisting_sensitive_data.md +++ b/topics/basics/persisting_sensitive_data.md @@ -1,6 +1,5 @@ ---- -title: Persisting Sensitive Data ---- +[//]: # (title: Persisting Sensitive Data) + The Credentials Store API allows you to store sensitive user data securely, like passwords, server URLs, etc. @@ -51,4 +50,4 @@ The default storage format depends on the OS. [linux]: https://specifications.freedesktop.org/secret-service/latest/ [linux]: https://wiki.gnome.org/Projects/Libsecret -Users can override the default behavior in Preferences \| Appearance & Behavior \| System Settings \| Passwords. +Users can override the default behavior in Preferences \| Appearance & Behavior \| System Settings \| Passwords. \ No newline at end of file diff --git a/basics/persisting_state_of_components.md b/topics/basics/persisting_state_of_components.md similarity index 94% rename from basics/persisting_state_of_components.md rename to topics/basics/persisting_state_of_components.md index 9aca0548d..bf93c161e 100644 --- a/basics/persisting_state_of_components.md +++ b/topics/basics/persisting_state_of_components.md @@ -1,12 +1,13 @@ ---- -title: Persisting State of Components ---- +[//]: # (title: Persisting State of Components) + The *IntelliJ Platform* provides an API that allows components or services to persist their state between restarts of the IDE. You can use either a simple API to persist a few values or persist the state of more complicated components using the [`PersistentStateComponent`](upsource:///platform/projectModel-api/src/com/intellij/openapi/components/PersistentStateComponent.java) interface. -> **WARNING** If you need to persist sensitive data like passwords, please see [Persisting Sensitive Data](persisting_sensitive_data.md). + > If you need to persist sensitive data like passwords, please see [Persisting Sensitive Data](persisting_sensitive_data.md). + > + {type="warning"} ## Using PropertiesComponent for Simple Non-Roamable Persistence @@ -23,7 +24,7 @@ Since all plugins share the same namespace, it is highly recommended to prefix k The [`com.intellij.openapi.components.PersistentStateComponent`](upsource:///platform/projectModel-api/src/com/intellij/openapi/components/PersistentStateComponent.java) interface gives you the most flexibility for defining the values to be persisted, their format, and storage location. To use it: -- mark a [service](plugin_structure/plugin_services.md) as implementing the `PersistentStateComponent` interface +- mark a [service](plugin_services.md) as implementing the `PersistentStateComponent` interface - define the state class - specify the storage location using `@com.intellij.openapi.components.State` @@ -86,7 +87,6 @@ It should return the component's default state: the one used if there is nothing State class should have an `equals()` method, but state objects are compared by fields if it is not implemented. When using Kotlin, use [Data Classes](https://kotlinlang.org/docs/reference/data-classes.html). - The following types of values can be persisted: * numbers (both primitive types, such as `int`, and boxed types, such as `Integer`) @@ -123,7 +123,6 @@ class State { } ``` - ### Defining the Storage Location To specify where precisely the persisted values are stored, add `@State` annotation to the `PersistentStateComponent` class. @@ -142,14 +141,18 @@ The simplest ways of specifying the `@Storage` annotation are as follows (since The state is persisted in a separate file by specifying a different setting for the `value` parameter, which was the `file` parameter before 2016.x. -> **NOTE** For application-level components, it is strongly recommended to use a custom file, using of `other.xml` is deprecated. + > For application-level components, it is strongly recommended to use a custom file, using of `other.xml` is deprecated. + > + {type="note"} The `roamingType` parameter of the `@Storage` annotation specifies the roaming type when the Settings Repository plugin is used. ## Customizing the XML Format of Persisted Values -> **NOTE** Please consider using annotation parameters only to achieve backward compatibility. + > Please consider using annotation parameters only to achieve backward compatibility. > Otherwise, please feel free to file issues about serialization cosmetics. + > + {type="note"} If you want to use the default bean serialization but need to customize the storage format in XML (for example, for compatibility with previous versions of your plugin or externally defined XML formats), you can use the `@Tag`, `@Attribute`, `@Property`, `@MapAnnotation`, `@AbstractCollection` annotations. @@ -184,4 +187,4 @@ Components save their state in the following files: * Project-level: project (`.ipr`) file. However, if the workspace option in the `plugin.xml` file is set to `true`, then the workspace (`.iws`) file is used instead. -* Module-level: module (`.iml`) file. +* Module-level: module (`.iml`) file. \ No newline at end of file diff --git a/basics/platform_contributions.md b/topics/basics/platform_contributions.md similarity index 94% rename from basics/platform_contributions.md rename to topics/basics/platform_contributions.md index 75566c612..be45c1700 100644 --- a/basics/platform_contributions.md +++ b/topics/basics/platform_contributions.md @@ -1,9 +1,8 @@ ---- -title: Contributing to the IntelliJ Platform ---- +[//]: # (title: Contributing to the IntelliJ Platform) + -Please make sure to read the [Code of Conduct](/CODE_OF_CONDUCT.md). +Please make sure to read the [Code of Conduct](intellij-sdk-docs-original_CODE_OF_CONDUCT.md). ## Participate in the Community @@ -27,7 +26,7 @@ If you are a member of a different open-source community, why not mention Intell ### Write Documents We're always looking for new articles about IntelliJ IDEA features as well as documentation for the IntelliJ Platform. You can write tutorials, how-tos, sample applications, or share your experience with the IntelliJ Platform. -You can publish your documentation on a website or blog, or submit a [pull request](/CONTRIBUTING.md) to the SDK Docs. +You can publish your documentation on a website or blog, or submit a [pull request](intellij-sdk-docs-original_CONTRIBUTING.md) to the SDK Docs. ### Produce Screencasts Screencasts have recently become very popular as a way to show other developers how to use the tool effectively. @@ -63,4 +62,4 @@ A developer will review your patch and, if it meets the [quality criteria](intel You will also need to sign the [JetBrains Contributor License Agreement (CLA)](https://www.jetbrains.com/agreements/cla/) to complete your contribution. ### Become a Committer -Developers with a long history of submitting high-quality patches can gain direct commit rights. +Developers with a long history of submitting high-quality patches can gain direct commit rights. \ No newline at end of file diff --git a/topics/basics/plugin_structure.md b/topics/basics/plugin_structure.md new file mode 100644 index 000000000..8b988babd --- /dev/null +++ b/topics/basics/plugin_structure.md @@ -0,0 +1,17 @@ +[//]: # (title: Plugin Structure) + + + +Click the following topics to learn more about the plugin system structure and plugin lifecycles: + +* [Plugin Content](plugin_content.md) +* [Plugin Class Loaders](plugin_class_loaders.md) +* [Plugin Actions](plugin_actions.md) +* [Plugin Extensions](plugin_extensions.md) +* [Plugin Services](plugin_services.md) +* [Plugin Listeners](plugin_listeners.md) +* [Plugin Extension Points](plugin_extension_points.md) +* [Plugin Components](plugin_components.md) +* [Plugin Configuration File](plugin_configuration_file.md) +* [Plugin Logo (Icon)](plugin_icon_file.md) +* [Plugin Dependencies](plugin_dependencies.md) \ No newline at end of file diff --git a/basics/plugin_structure/dynamic_plugins.md b/topics/basics/plugin_structure/dynamic_plugins.md similarity index 84% rename from basics/plugin_structure/dynamic_plugins.md rename to topics/basics/plugin_structure/dynamic_plugins.md index 94ad9d1d7..4e3531cf6 100644 --- a/basics/plugin_structure/dynamic_plugins.md +++ b/topics/basics/plugin_structure/dynamic_plugins.md @@ -1,12 +1,13 @@ ---- -title: Dynamic Plugins ---- +[//]: # (title: Dynamic Plugins) + Starting with the 2020.1 release, installing, updating, and uninstalling plugins without restarting the IDE is available in the IntelliJ Platform. -During plugin development, [Auto-Reload](/basics/ide_development_instance.md#enabling-auto-reload) also allows code changes to take effect immediately in the sandbox IDE instance. +During plugin development, [Auto-Reload](ide_development_instance.md#enabling-auto-reload) also allows code changes to take effect immediately in the sandbox IDE instance. -> **NOTE** If a plugin _requires_ restart (e.g., due to using native libraries) specify `require-restart="true"` for `` root tag in `plugin.xml`. + > If a plugin _requires_ restart (e.g., due to using native libraries) specify `require-restart="true"` for `` root tag in `plugin.xml`. + > + {type="note"} ## Restrictions @@ -14,7 +15,7 @@ For a plugin to support this, all restrictions listed below must be met. To verify a plugin locally, run **Analyze \| Run Inspection by Name... \| Plugin.xml dynamic plugin verification** inspection on all plugin descriptor files. For plugins hosted on the [JetBrains Plugins Repository](https://plugins.jetbrains.com) the built-in [Plugin Verifier](https://blog.jetbrains.com/platform/2018/07/plugins-repository-now-integrates-with-the-plugin-verification-tool/) will run these checks automatically. -See [Plugin Verifier](/reference_guide/api_changes_list.md#plugin-verifier) for more information on how to run it locally or on CI. +See [Plugin Verifier](api_changes_list.md#plugin-verifier) for more information on how to run it locally or on CI. ### No Use of Components @@ -44,7 +45,9 @@ Application, project, and module services declared with `overrides="true"` are n ## Code -> **NOTE** Loading and unloading plugins happens in EDT and under write action. + > Loading and unloading plugins happens in EDT and under write action. + > + {type="note"} ### CachedValue @@ -80,4 +83,4 @@ To find leaks preventing clean unload, perform the following steps: - Open the `.hprof` snapshot generated on plugin unload, look for the plugin ID string - Find the `PluginClassLoader` referencing the plugin ID string - Look at references to the `PluginClassLoader` instance. - Every one of them is a memory leak (or part of a memory leak) that needs to be resolved. + Every one of them is a memory leak (or part of a memory leak) that needs to be resolved. \ No newline at end of file diff --git a/basics/plugin_structure/plugin_actions.md b/topics/basics/plugin_structure/plugin_actions.md similarity index 88% rename from basics/plugin_structure/plugin_actions.md rename to topics/basics/plugin_structure/plugin_actions.md index 569fefb57..8a844f7bc 100644 --- a/basics/plugin_structure/plugin_actions.md +++ b/topics/basics/plugin_structure/plugin_actions.md @@ -1,6 +1,5 @@ ---- -title: Plugin Actions ---- +[//]: # (title: Plugin Actions) + The *IntelliJ Platform* provides the concept of _actions_. @@ -15,4 +14,4 @@ Subgroups of the group can form submenus of a menu. The user can customize all registered actions via [Menus and Toolbars](https://www.jetbrains.com/help/idea/customize-actions-menus-and-toolbars.html) settings. -Please see [Action System](/basics/action_system.md) on how to create and register actions in the IDE. +Please see [Action System](basic_action_system.md) on how to create and register actions in the IDE. \ No newline at end of file diff --git a/basics/plugin_structure/plugin_class_loaders.md b/topics/basics/plugin_structure/plugin_class_loaders.md similarity index 97% rename from basics/plugin_structure/plugin_class_loaders.md rename to topics/basics/plugin_structure/plugin_class_loaders.md index f29c3b051..0721ea078 100644 --- a/basics/plugin_structure/plugin_class_loaders.md +++ b/topics/basics/plugin_structure/plugin_class_loaders.md @@ -1,6 +1,5 @@ ---- -title: Plugin Class Loaders ---- +[//]: # (title: Plugin Class Loaders) + A separate class loader is used to load the classes of each plugin. @@ -23,4 +22,4 @@ For this to work in a plugin, the context class loader must be set to the plugin } finally { Thread.currentThread().setContextClassLoader(current); } -``` +``` \ No newline at end of file diff --git a/basics/plugin_structure/plugin_components.md b/topics/basics/plugin_structure/plugin_components.md similarity index 91% rename from basics/plugin_structure/plugin_components.md rename to topics/basics/plugin_structure/plugin_components.md index 0d9b9e355..948d4d2ef 100644 --- a/basics/plugin_structure/plugin_components.md +++ b/topics/basics/plugin_structure/plugin_components.md @@ -1,10 +1,11 @@ ---- -title: Plugin Components ---- +[//]: # (title: Plugin Components) + -> **WARNING** When writing new plugins, creating Components should be avoided. + > When writing new plugins, creating Components should be avoided. > Any existing Components should be migrated to services, extensions, or listeners (see below). + > + {type="warning"} Plugin Components are a legacy feature supported for compatibility with plugins created for older versions of the IntelliJ Platform. Plugins using Components do not support [dynamic loading](dynamic_plugins.md) (the ability to install, update, and uninstall plugins without restarting the IDE). @@ -20,7 +21,7 @@ To manage some state or logic that is only needed when the user performs a speci ### Persisting State -To store the state of your plugin at the application or project level, use a [Service](plugin_services.md), and implement the `PersistentStateComponent` interface. See [Persisting State of Components](/basics/persisting_state_of_components.md) for details. +To store the state of your plugin at the application or project level, use a [Service](plugin_services.md), and implement the `PersistentStateComponent` interface. See [Persisting State of Components](persisting_state_of_components.md) for details. ### Subscribing to Events @@ -45,8 +46,8 @@ To execute code when a project is being opened, use one of these two [extensions : [StartupActivity.Background](upsource:///platform/core-api/src/com/intellij/openapi/startup/StartupActivity.java) for execution with 5 seconds delay in background thread (2019.3 or later). Any long-running or CPU intensive tasks should be made visible to users by using `ProgressManager.run(Task.Backgroundable)`. -Access to indices must be wrapped with `DumbService`, see also [General Threading Rules](/basics/architectural_overview/general_threading_rules.md). +Access to indices must be wrapped with `DumbService`, see also [General Threading Rules](general_threading_rules.md). ### Application/Project Close -To execute code on project closing or application shutdown, implement the `Disposable` interface in a [Service](plugin_services.md) and place the code in the `dispose()` method. Alternatively, use `Disposer.register()` passing a `Project` or `Application` service instance as the `parent` argument (see [Choosing a Disposable Parent](/basics/disposers.md#choosing-a-disposable-parent)). +To execute code on project closing or application shutdown, implement the `Disposable` interface in a [Service](plugin_services.md) and place the code in the `dispose()` method. Alternatively, use `Disposer.register()` passing a `Project` or `Application` service instance as the `parent` argument (see [Choosing a Disposable Parent](disposers.md#choosing-a-disposable-parent)). \ No newline at end of file diff --git a/basics/plugin_structure/plugin_configuration_file.md b/topics/basics/plugin_structure/plugin_configuration_file.md similarity index 96% rename from basics/plugin_structure/plugin_configuration_file.md rename to topics/basics/plugin_structure/plugin_configuration_file.md index 0bd164780..21c1dce03 100644 --- a/basics/plugin_structure/plugin_configuration_file.md +++ b/topics/basics/plugin_structure/plugin_configuration_file.md @@ -1,17 +1,16 @@ ---- -title: Plugin Configuration File - plugin.xml ---- +[//]: # (title: Plugin Configuration File - plugin.xml) + The following is a sample plugin configuration file. This sample showcases and describes all elements that can be used in the `plugin.xml` file. -Additional information about configuring `` is available in the [Actions](/basics/action_system.md#registering-actions) section in Part II. +Additional information about configuring `` is available in the [Actions](basic_action_system.md#registering-actions) section in Part II. Limited HTML elements are allowed within `` and `` elements. However, content containing HTML elements must be surrounded by `` tags. Allowed HTML elements include text formatting, paragraphs, and lists. -When using Gradle, a number of metadata elements will be provided at build time by [`patchPluginXml` task](/tutorials/build_system/gradle_guide.md#patching-the-plugin-configuration-file). +When using Gradle, a number of metadata elements will be provided at build time by [`patchPluginXml` task](gradle_guide.md#patching-the-plugin-configuration-file). ```xml @@ -156,4 +155,4 @@ When using Gradle, a number of metadata elements will be provided at build time -``` +``` \ No newline at end of file diff --git a/basics/plugin_structure/plugin_content.md b/topics/basics/plugin_structure/plugin_content.md similarity index 97% rename from basics/plugin_structure/plugin_content.md rename to topics/basics/plugin_structure/plugin_content.md index a77f87089..1d4e93754 100644 --- a/basics/plugin_structure/plugin_content.md +++ b/topics/basics/plugin_structure/plugin_content.md @@ -1,6 +1,5 @@ ---- -title: Plugin Content ---- +[//]: # (title: Plugin Content) + The plugin `jar` file must contain: @@ -8,7 +7,6 @@ The plugin `jar` file must contain: - the classes that implement the plugin functionality - recommended: plugin logo file(s) (`META-INF/pluginIcon*.svg`) ([Plugin Logo](plugin_icon_file.md)) - ### Plugin Without Dependencies A plugin consisting of a single `.jar` file is placed in the `/plugins` directory. @@ -25,7 +23,6 @@ A plugin consisting of a single `.jar` file is placed in the `/plugins` director └── pluginIcon_dark.svg ``` - ### Plugin With Dependencies The plugin `.jar` file is placed in the `/lib` folder under the plugin's "root" folder, together with all required bundled libraries. @@ -48,4 +45,4 @@ All jars from the `/lib` folder are automatically added to the classpath (see al ├── plugin.xml ├── pluginIcon.svg └── pluginIcon_dark.svg -``` +``` \ No newline at end of file diff --git a/basics/plugin_structure/plugin_dependencies.md b/topics/basics/plugin_structure/plugin_dependencies.md similarity index 63% rename from basics/plugin_structure/plugin_dependencies.md rename to topics/basics/plugin_structure/plugin_dependencies.md index ae3dc15ca..78b7e6577 100644 --- a/basics/plugin_structure/plugin_dependencies.md +++ b/topics/basics/plugin_structure/plugin_dependencies.md @@ -1,18 +1,19 @@ ---- -title: Plugin Dependencies ---- +[//]: # (title: Plugin Dependencies) + A plugin may depend on classes from other plugins, either bundled, third-party, or by the same author. This document describes the syntax for declaring plugin dependencies and optional plugin dependencies. -For more information about dependencies on the IntelliJ Platform modules, see Part II of this document: [Plugin Compatibility with IntelliJ Platform Products](/basics/getting_started/plugin_compatibility.md). +For more information about dependencies on the IntelliJ Platform modules, see Part II of this document: [Plugin Compatibility with IntelliJ Platform Products](plugin_compatibility.md). -> **NOTE** It is impossible to specify the minimum/maximum version for the dependent plugin. ([Issue](https://youtrack.jetbrains.com/issue/IDEABKL-7906)) + > It is impossible to specify the minimum/maximum version for the dependent plugin. ([Issue](https://youtrack.jetbrains.com/issue/IDEABKL-7906)) + > + {type="note"} To express dependencies on classes from other plugins or modules, perform the following three required steps: -## 1. Locating Plugin ID and Preparing Sandbox -A compatible version must be chosen carefully according to the plugin's [compatibility](/basics/getting_started/build_number_ranges.md). +## Locating Plugin ID and Preparing Sandbox +A compatible version must be chosen carefully according to the plugin's [compatibility](build_number_ranges.md). For plugins published on [JetBrains Plugins Repository](https://plugins.jetbrains.com) - open plugin's detail page @@ -21,15 +22,17 @@ For plugins published on [JetBrains Plugins Repository](https://plugins.jetbrain For bundled and non-public plugins, locate the plugin's main JAR file containing `META-INF/plugin.xml` descriptor with `` tag (or `` if not specified). -If the plugin is not bundled with the target IDE, run the (sandbox) [IDE Development Instance](/basics/ide_development_instance.md) of your target IDE and install the plugin there. +If the plugin is not bundled with the target IDE, run the (sandbox) [IDE Development Instance](ide_development_instance.md) of your target IDE and install the plugin there. -## 2. Project Setup +## Project Setup Depending on the chosen development workflow (Gradle or DevKit), one of the two following steps is necessary. -### 2.1 Gradle -> **NOTE** Please see the `plugins` attribute [gradle-intellij-plugin: Configuration](https://github.com/JetBrains/gradle-intellij-plugin#configuration) for acceptable values. +### Gradle + > Please see the `plugins` attribute [gradle-intellij-plugin: Configuration](https://github.com/JetBrains/gradle-intellij-plugin#configuration) for acceptable values. + > + {type="note"} -If the project uses [Gradle](/tutorials/build_system.md) with a Groovy build script to build the plugin, add the dependency to the `plugins` parameter of the `intellij` block in your `build.gradle`, for example: +If the project uses [Gradle](gradle_build_system.md) with a Groovy build script to build the plugin, add the dependency to the `plugins` parameter of the `intellij` block in your `build.gradle`, for example: ```groovy intellij { @@ -45,36 +48,41 @@ intellij { } ``` -> **NOTE** Transitive dependencies required for tests must currently be [specified explicitly](https://github.com/JetBrains/gradle-intellij-plugin/issues/38). + > Transitive dependencies required for tests must currently be [specified explicitly](https://github.com/JetBrains/gradle-intellij-plugin/issues/38). + > + {type="note"} -### 2.2 DevKit -> **TIP** Existing DevKit-based projects can be converted to use [Gradle setup](/tutorials/build_system/prerequisites.md#adding-gradle-support-to-an-existing-devkit-based-intellij-platform-plugin) where managing dependencies is fully automated. +### DevKit + > Existing DevKit-based projects can be converted to use [Gradle setup](gradle_prerequisites.md#adding-gradle-support-to-an-existing-devkit-based-intellij-platform-plugin) where managing dependencies is fully automated. + > + {type="tip"} -If the project uses [DevKit](/basics/getting_started/using_dev_kit.md), add the JARs of the plugin on which the project depends to the **classpath** of the *IntelliJ Platform SDK*. +If the project uses [DevKit](using_dev_kit.md), add the JARs of the plugin on which the project depends to the **classpath** of the *IntelliJ Platform SDK*. -> **WARNING** Do not add the plugin JARs as a library: this will fail at runtime because the IntelliJ Platform will load two separate copies of the dependency plugin classes. + > Do not add the plugin JARs as a library: this will fail at runtime because the IntelliJ Platform will load two separate copies of the dependency plugin classes. + > + {type="warning"} To do that, open the Project Structure dialog, select the SDK used in the project, press the + button in the Classpath tab, and select the plugin JAR file or files: * For bundled plugins, the plugin JAR files are located in `plugins/` or `plugins//lib` under the main installation directory. If you're not sure which JAR to add, you can add all of them. * For non-bundled plugins, the plugin JAR files are located in `config/plugins/` or `config/plugins//lib` under the directory specified as "Sandbox Home" in the IntelliJ Platform Plugin SDK settings. -## 3. Dependency Declaration in plugin.xml -Regardless of whether a plugin project uses [Modules Available in All Products](/basics/getting_started/plugin_compatibility.md#modules-available-in-all-products), or [Modules Specific to Functionality](/basics/getting_started/plugin_compatibility.md#modules-specific-to-functionality), the correct module must be listed as a dependency in `plugin.xml`. +## Dependency Declaration in plugin.xml +Regardless of whether a plugin project uses [Modules Available in All Products](plugin_compatibility.md#modules-available-in-all-products), or [Modules Specific to Functionality](plugin_compatibility.md#modules-specific-to-functionality), the correct module must be listed as a dependency in `plugin.xml`. If a project depends on another plugin, the dependency must be declared like a module. If only general IntelliJ Platform features (APIs) are used, then a default dependency on `com.intellij.modules.platform` must be declared. To display a list of available IntelliJ Platform modules, invoke the [code completion](https://www.jetbrains.com/help/idea/auto-completing-code.html#4eac28ba) feature for the `` element contents while editing the plugin project's `plugin.xml` file. -### 3.1 Configuring plugin.xml +### Configuring plugin.xml In the `plugin.xml`, add a `` tag with the dependency plugin's ID as its content. -Continuing with the example from [Section 2](#2-project-setup) above, the dependency declaration in `plugin.xml` would be: +Continuing with the example from [Project Setup](#project-setup) above, the dependency declaration in `plugin.xml` would be: ```xml org.another.plugin ``` - ## Optional Plugin Dependencies A project can also specify an optional plugin dependency. In this case, the plugin will load even if the plugin it depends on is not installed or enabled, but part of the plugin's functionality will not be available. @@ -85,7 +93,9 @@ Declare additional `optional="true"` and `config-file` attribute pointing to opt dependency.plugin.id ``` -> **NOTE** Additional plugin descriptor files must follow the naming pattern `myPluginId-$NAME$.xml` resulting in unique filenames to prevent problems with classloaders in tests ([Details](https://youtrack.jetbrains.com/issue/IDEA-205964)). + > Additional plugin descriptor files must follow the naming pattern `myPluginId-$NAME$.xml` resulting in unique filenames to prevent problems with classloaders in tests ([Details](https://youtrack.jetbrains.com/issue/IDEA-205964)). + > + {type="note"} For example, if a plugin adds additional highlighting for Java and Kotlin files, use the following setup. The main `plugin.xml` will define an annotator for Java and specify an optional dependency on the Kotlin plugin (`org.jetbrains.kotlin`): @@ -114,4 +124,4 @@ _myPluginId-withKotlin.xml_ -``` +``` \ No newline at end of file diff --git a/basics/plugin_structure/plugin_extension_points.md b/topics/basics/plugin_structure/plugin_extension_points.md similarity index 91% rename from basics/plugin_structure/plugin_extension_points.md rename to topics/basics/plugin_structure/plugin_extension_points.md index 14f6a2388..6760c1bb3 100644 --- a/basics/plugin_structure/plugin_extension_points.md +++ b/topics/basics/plugin_structure/plugin_extension_points.md @@ -1,9 +1,10 @@ ---- -title: Plugin Extension Points ---- +[//]: # (title: Plugin Extension Points) + -> **NOTE** See [Plugin Extensions](plugin_extensions.md) for _using_ extension points in your plugin. + > See [Plugin Extensions](plugin_extensions.md) for _using_ extension points in your plugin. + > + {type="note"} By defining _extension points_ in your plugin, you can allow other plugins to extend your plugin's functionality. There are two types of extension points: @@ -75,7 +76,9 @@ public class MyBeanClass extends AbstractExtensionPointBean { } ``` -> **TIP** See [Extension properties code insight](plugin_extensions.md#extension-properties-code-insight) on how to provide smart completion/validation. + > See [Extension properties code insight](plugin_extensions.md#extension-properties-code-insight) on how to provide smart completion/validation. + > + {type="tip"} For above extension points usage in _anotherPlugin_ would look like this (see also [Declaring Extensions](plugin_extensions.md#declaring-extensions)): @@ -138,5 +141,5 @@ Extension points matching these conditions can then be marked as _dynamic_ by ad ``` -> **NOTE** All non-dynamic extension points are highlighted via _Plugin DevKit \| Plugin descriptor \| Plugin.xml dynamic plugin verification_ inspection available in IntelliJ IDEA 2020.1 or later. -> Previous versions also highlight the `dynamic` attribute as "experimental". + > All non-dynamic extension points are highlighted via _Plugin DevKit \| Plugin descriptor \| Plugin.xml dynamic plugin verification_ inspection available in IntelliJ IDEA 2020.1 or later. +> Previous versions also highlight the `dynamic` attribute as "experimental". \ No newline at end of file diff --git a/basics/plugin_structure/plugin_extensions.md b/topics/basics/plugin_structure/plugin_extensions.md similarity index 89% rename from basics/plugin_structure/plugin_extensions.md rename to topics/basics/plugin_structure/plugin_extensions.md index 34af61e9b..042071686 100644 --- a/basics/plugin_structure/plugin_extensions.md +++ b/topics/basics/plugin_structure/plugin_extensions.md @@ -1,26 +1,25 @@ ---- -title: Plugin Extensions -redirect_from: - /basics/plugin_structure/plugin_extensions_and_extension_points.html ---- +[//]: # (title: Plugin Extensions) + _Extensions_ are the most common way for a plugin to extend the IntelliJ Platform's functionality in a way that is not as straightforward as adding an action to a menu or toolbar. The following are some of the most common tasks accomplished using extensions: - * The `com.intellij.toolWindow` extension point allows plugins to add [tool windows](/user_interface_components/tool_windows.md) + * The `com.intellij.toolWindow` extension point allows plugins to add [tool windows](tool_windows.md) (panels displayed at the sides of the IDE user interface); * The `com.intellij.applicationConfigurable` and `com.intellij.projectConfigurable` extension points allow plugins to add pages to the - [Settings/Preferences dialog](/basics/settings.md); - * [Custom language plugins](/reference_guide/custom_language_support.md) use many extension points + [Settings/Preferences dialog](settings.md); + * [Custom language plugins](custom_language_support.md) use many extension points to extend various language support features in the IDE. There are [more than 1000 extension](#how-to-get-the-extension-points-list) points available in the platform and the bundled plugins, allowing to customize different parts of the IDE behavior. ## Declaring Extensions -> **TIP** Auto-completion, Quick Documentation, and other code insight features are available on extension point tags and attributes. + > Auto-completion, Quick Documentation, and other code insight features are available on extension point tags and attributes. + > + {type="tip"} 1. Add an `` element to your `plugin.xml` if it's not yet present there. Set the `defaultExtensionNs` attribute to one of the following values: @@ -32,7 +31,6 @@ There are [more than 1000 extension](#how-to-get-the-extension-points-list) poin * If the extension point was declared using the `interface` attribute, for newly added child element, set the `implementation` attribute to the name of the class that implements the specified interface. * If the extension point was declared using the `beanClass` attribute, for newly added child element, set all attributes annotated with the [`@Attribute`](upsource:///platform/util/src/com/intellij/util/xmlb/annotations/Attribute.java) annotations in the specified bean class. - To clarify this procedure, consider the following sample section of the `plugin.xml` file that defines two extensions designed to access the `com.intellij.appStarter` and `com.intellij.projectTemplatesFactory` extension points in the *IntelliJ Platform* and one extension to access the `another.plugin.myExtensionPoint` extension point in another plugin `another.plugin`: ```xml @@ -93,9 +91,7 @@ Attributes with `Enum` type support code insight with _lowerSnakeCased_ notation ## How to get the extension points list? -[Extension Point List](/appendix/resources/extension_point_list.md) contains all available in *IntelliJ Platform* and from bundled plugins in IntelliJ IDEA. +[Extension Point List](extension_point_list.md) contains all available in *IntelliJ Platform* and from bundled plugins in IntelliJ IDEA. Alternatively (or when using 3rd party extension points), all available extension points for the specified namespace can be listed using auto-completion inside the `` block. -Use **View \| Quick Documentation** in the lookup list to access more information about the extension point and implementation (if applicable). - - +Use **View \| Quick Documentation** in the lookup list to access more information about the extension point and implementation (if applicable). \ No newline at end of file diff --git a/basics/plugin_structure/plugin_icon_file.md b/topics/basics/plugin_structure/plugin_icon_file.md similarity index 72% rename from basics/plugin_structure/plugin_icon_file.md rename to topics/basics/plugin_structure/plugin_icon_file.md index 599b98b61..42e56e640 100644 --- a/basics/plugin_structure/plugin_icon_file.md +++ b/topics/basics/plugin_structure/plugin_icon_file.md @@ -1,6 +1,5 @@ ---- -title: Plugin Logo ---- +[//]: # (title: Plugin Logo) + Beginning in version 2019.1, the IntelliJ Platform supports representing a plugin with a logo. @@ -8,19 +7,18 @@ A _Plugin Logo_ is intended to be a unique representation of a plugin's function Previously this page referred to Plugin Logos as _Plugin Icons_. **Note:** icons and images used within a plugin have different requirements. -See [Working with Icons and Images](/reference_guide/work_with_icons_and_images.md) for more information. - -* bullet list -{:toc} +See [Working with Icons and Images](work_with_icons_and_images.md) for more information. ## Introduction Plugin Logos are shown in the [JetBrains Plugins Repository](https://plugins.jetbrains.com). They also appear in the Settings/Preferences [Plugin Manager](https://www.jetbrains.com/help/idea/managing-plugins.html) UI in IntelliJ Platform-based IDEs. Whether online or in the product UI, a Plugin Logo helps users to identify a plugin more quickly in a list, as shown below: -![Example Product Plugin Preferences Dialog](img/plugin_prefs.png){:width="800px"} +![Example Product Plugin Preferences Dialog](plugin_prefs.png){width="800"} -> **NOTE** When browsing [custom plugin repositories](/basics/getting_started/update_plugins_format.md), there is no support for showing logos for plugins hosted there but not yet installed. + > When browsing [custom plugin repositories](update_plugins_format.md), there is no support for showing logos for plugins hosted there but not yet installed. + > + {type="note"} ## Plugin Logo Requirements For a Plugin Logo to be displayed correctly within an IntelliJ Platform-based IDE, it must: @@ -41,7 +39,7 @@ Verify that Plugin Logo designs are effective in both sizes and all display cont ### Plugin Logo Shape Plugin Logo designs should leave at least 2px transparent padding around the perimeter, as shown below: -![36px by 36px is the area where the visible part of the Logo should fit](img/icon_size.png){:width="225px"} +![36px by 36px is the area where the visible part of the Logo should fit](icon_size.png){width="225"} Make sure Plugin Logos have the same visual weight as the logos in the examples below. The more filled a Plugin Logo design is, the less actual space it needs. @@ -50,31 +48,31 @@ See more examples of [visual weight compensation](https://jetbrains.design/intel For basic shapes, use the following sizes. Note the different areas of transparent padding used for each shape: -| ![Square 32px by 32px](img/square_logo.png){:width="225px"} | ![Circle 36px in diameter](img/circle_logo.png){:width="225px"} | +| ![Square 32px by 32px](square_logo.png){width="225"} | ![Circle 36px in diameter](circle_logo.png){:width="225"} | |:---:|:---:| | _Square logo 32px by 32px_ | _Circular logo 36px in diameter_ | -| ![Horizontal rectangle 36px by 26px](img/rectangle_horizontal.png){:width="225px"} | ![Vertical rectangle 26px by 36px](img/rectangle_vertical.png){:width="225px"} | +| ![Horizontal rectangle 36px by 26px](rectangle_horizontal.png){width="225"} | ![Vertical rectangle 26px by 36px](rectangle_vertical.png){:width="225"} | | _Horizontal rectangular logo 36px by 26px_ | _Vertical rectangular logo 26px by 36px_ | -
+
### Plugin Logo Colors If the plugin's technology already has a logo, use its colors. Check the license terms before using the logo. If there is no existing logo, or its use is prohibited, create a custom logo based on the [Action Colors Palette](https://jetbrains.design/intellij/principles/icons/#action-icons) in the IntelliJ Platform UI Guidelines for Icons. -| ![The YouTrack Plugin Logo uses the YouTrack product logo ](img/yt_logo.png){:height="200px" width="200px"} | ![The Keymap Plugin Logo uses a color from the Action Colors Palette](img/keymap_logo.png){:height="200px" width="200px"} | +| ![The YouTrack Plugin Logo uses the YouTrack product logo ](yt_logo.png){height="200" width="200"} | ![The Keymap Plugin Logo uses a color from the Action Colors Palette](keymap_logo.png){:height="200" width="200"} | |:---:|:---:| -| _The YouTrack Plugin Logo uses
the YouTrack product logo_ | _The Keymap Plugin Logo uses a color
from the Action Colors Palette_ | +| _The YouTrack Plugin Logo uses
the YouTrack product logo_ | _The Keymap Plugin Logo uses a color
from the Action Colors Palette_ | Ensure a Plugin Logo is visible on both light and dark backgrounds. If one Plugin Logo design does not work on both light and dark backgrounds, create separate light and dark versions of the Plugin Logo. The examples below illustrate how a Plugin Logo design may work well for a light background but not for a dark background. Consequently, a separate Plugin Logo for dark backgrounds is needed. -| ![Plugin Logo on Light UI Theme](img/light_version.png){:width="225px"} | ![Light Plugin Logo on Dark UI Theme](img/dark_bad.png){:width="225px"} | ![Plugin Logo for Dark UI Theme](img/dark_good.png){:width="225px"} | +| ![Plugin Logo on Light UI Theme](light_version.png){width="225"} | ![Light Plugin Logo on Dark UI Theme](dark_bad.png){:width="225"} | ![Plugin Logo for Dark UI Theme](dark_good.png){:width="225"} | |:---:|:---:|:---:| -| _The light Plugin Logo design
works well on light UI Theme_ | _The light Plugin Logo design does
not work well on a dark UI Theme_ | _A separate, dark Plugin Logo design
works well on dark UI Theme_ | +| _The light Plugin Logo design
works well on light UI Theme_ | _The light Plugin Logo design does
not work well on a dark UI Theme_ | _A separate, dark Plugin Logo design
works well on dark UI Theme_ | ### Plugin Logo File Format All Plugin Logo images must be SVG format. @@ -86,7 +84,6 @@ Name the Plugin Logo files according to the following conventions: If a separate Logo file for dark UI Themes exists in the plugin, then this file is used solely for light UI Themes, * `pluginIcon_dark.svg` is an optional, alternative Plugin Logo for use solely with dark IDE UI Themes. - ## Adding Plugin Logo Files to a Plugin Project The Plugin Logo files must be in the `META-INF` folder of the plugin distribution file, i.e., the `*.jar` or `*.zip` file you upload to the plugin repository and install into a JetBrains IDE. @@ -94,4 +91,4 @@ To include Plugin Logo files in your distribution file, place the Plugin Logo fi Note that this requirement is the same regardless of using DevKit or Gradle for developing a plugin. For example: -![Plugin Logo Files in META-INF folder](img/resource_directory_structure.png){:width="450px"} +![Plugin Logo Files in META-INF folder](resource_directory_structure.png){width="450"} \ No newline at end of file diff --git a/basics/plugin_structure/plugin_listeners.md b/topics/basics/plugin_structure/plugin_listeners.md similarity index 92% rename from basics/plugin_structure/plugin_listeners.md rename to topics/basics/plugin_structure/plugin_listeners.md index 1a98bb85c..4526c65d5 100644 --- a/basics/plugin_structure/plugin_listeners.md +++ b/topics/basics/plugin_structure/plugin_listeners.md @@ -1,13 +1,16 @@ ---- -title: Plugin Listeners ---- +[//]: # (title: Plugin Listeners) + -> **NOTE** Defining listeners in `plugin.xml` is supported starting with version 2019.3 of the platform. + > Defining listeners in `plugin.xml` is supported starting with version 2019.3 of the platform. + > + {type="note"} -> **NOTE** Listener implementations must be stateless and may not implement life-cycle (e.g., `Disposable`). + > Listener implementations must be stateless and may not implement life-cycle (e.g., `Disposable`). + > + {type="note"} -_Listeners_ allow plugins to declaratively subscribe to events delivered through the message bus (see [Messaging infrastructure](/reference_guide/messaging_infrastructure.md) for details). +_Listeners_ allow plugins to declaratively subscribe to events delivered through the message bus (see [Messaging infrastructure](messaging_infrastructure.md) for details). You can define both application- and project-level listeners. @@ -97,4 +100,4 @@ Registration of listeners can be restricted using the following attributes: - `os` - allows to restrict listener to given OS, e.g., `os="windows"` for Windows only (2020.1 and later) - `activeInTestMode` - set to `false` to disable listener if `com.intellij.openapi.application.Application.isUnitTestMode()`==`true` - `activeInHeadlessMode` - set to `false` to disable listener if `com.intellij.openapi.application.Application.isHeadlessEnvironment()`==`true`. - Also, covers `activeInTestMode` as test mode implies headless mode. + Also, covers `activeInTestMode` as test mode implies headless mode. \ No newline at end of file diff --git a/basics/plugin_structure/plugin_services.md b/topics/basics/plugin_structure/plugin_services.md similarity index 88% rename from basics/plugin_structure/plugin_services.md rename to topics/basics/plugin_structure/plugin_services.md index 307fcb12b..69d80c771 100644 --- a/basics/plugin_structure/plugin_services.md +++ b/topics/basics/plugin_structure/plugin_services.md @@ -1,6 +1,5 @@ ---- -title: Plugin Services ---- +[//]: # (title: Plugin Services) + A _service_ is a plugin component loaded on demand when your plugin calls the `getService()` method of [`ServiceManager`](upsource:///platform/core-api/src/com/intellij/openapi/components/ServiceManager.java). @@ -10,24 +9,30 @@ The *IntelliJ Platform* ensures that only one instance of a service is loaded ev A service must have an implementation class that is used for service instantiation. A service may also have an interface class used to obtain the service instance and provide the service's API. -A service needing a shutdown hook/cleanup routine can implement [`Disposable`](upsource:///platform/util/src/com/intellij/openapi/Disposable.java) and perform necessary work in `dispose()` (see [Automatically Disposed Objects](/basics/disposers.md#automatically-disposed-objects)). +A service needing a shutdown hook/cleanup routine can implement [`Disposable`](upsource:///platform/util/src/com/intellij/openapi/Disposable.java) and perform necessary work in `dispose()` (see [Automatically Disposed Objects](disposers.md#automatically-disposed-objects)). #### Types The *IntelliJ Platform* offers three types of services: _application level_ services (global singleton), _project level_ services, and _module level_ services. -For the latter two, a separate instance of the service is created for each instance of its corresponding scope, see [Project Model Introduction](/basics/project_structure.md). +For the latter two, a separate instance of the service is created for each instance of its corresponding scope, see [Project Model Introduction](project_structure.md). -> **NOTE** Please consider not using module-level services because it can increase memory usage for projects with many modules. + > Please consider not using module-level services because it can increase memory usage for projects with many modules. + > + {type="note"} #### Constructor Project/Module level service constructors can have a `Project`/`Module` argument. To improve startup performance, avoid any heavy initializations in the constructor. -> **NOTE** Please note that using constructor injection is deprecated (and not supported in [Light Services](#light-services)) for performance reasons. + > Please note that using constructor injection is deprecated (and not supported in [Light Services](#light-services)) for performance reasons. > Other dependencies should be [acquired only when needed](#retrieving-a-service) in all corresponding methods (see `someServiceMethod()` in [Project Service Sample](#project-service-sample)). + > + {type="note"} ## Light Services -> **NOTE** Light Services are available since IntelliJ Platform 2019.3. + > Light Services are available since IntelliJ Platform 2019.3. + > + {type="note"} A service not going to be overridden does not need to be registered in `plugin.xml` (see [Declaring a Service](#declaring-a-service)). Instead, annotate service class with [`@Service`](upsource:///platform/core-api/src/com/intellij/openapi/components/Service.java). @@ -37,7 +42,7 @@ Restrictions: * Service class must be `final`. * Constructor injection is not supported (since it is deprecated). -* If service is a [PersistentStateComponent](/basics/persisting_state_of_components.md), roaming must be disabled (`roamingType = RoamingType.DISABLED`). +* If service is a [PersistentStateComponent](persisting_state_of_components.md), roaming must be disabled (`roamingType = RoamingType.DISABLED`). See [Project Level Service](#project-service-sample) below for a sample. @@ -123,4 +128,4 @@ If this number exceeds the maximum number of simultaneously opened projects allo * Download the included sample plugin project located [here](https://github.com/JetBrains/intellij-sdk-code-samples/tree/master/max_opened_projects). * Start *IntelliJ IDEA*, on the starting page, click *Open Project*, and then use the *Open Project* dialog box to open the project. * On the main menu, choose *Run \| Run* or press Shift+F10. -* If necessary, change the [Run/Debug Configurations](https://www.jetbrains.com/help/idea/run-debug-configuration-plugin.html). +* If necessary, change the [Run/Debug Configurations](https://www.jetbrains.com/help/idea/run-debug-configuration-plugin.html). \ No newline at end of file diff --git a/basics/project_structure.md b/topics/basics/project_structure.md similarity index 82% rename from basics/project_structure.md rename to topics/basics/project_structure.md index 2aca055bf..7511d2c1c 100644 --- a/basics/project_structure.md +++ b/topics/basics/project_structure.md @@ -1,6 +1,5 @@ ---- -title: Project Structure ---- +[//]: # (title: Project Structure) + @@ -8,10 +7,9 @@ title: Project Structure This topic considers the concept of projects based on the IntelliJ Platform and related subjects, such as _modules_, _facets_, _libraries_, and _SDK_. The project structure and Java classes available to manage projects and modules are discussed. -> **NOTE** Internal changes related to a significant redesign of the representation of project models are included in 2020.3 release; please see [blog post](https://blog.jetbrains.com/platform/2020/10/new-implementation-of-project-model-interfaces-in-2020-3/) for details. This shouldn’t affect any plugins using the IntelliJ API properly and which don’t access internal classes. - -* bullet list -{:toc} + > Internal changes related to a significant redesign of the representation of project models are included in 2020.3 release; please see [blog post](https://blog.jetbrains.com/platform/2020/10/new-implementation-of-project-model-interfaces-in-2020-3/) for details. This shouldn’t affect any plugins using the IntelliJ API properly and which don’t access internal classes. + > + {type="note"} ## Project and Its Components This section briefly discusses the IDEA project structure, project components, and related terms. @@ -59,8 +57,8 @@ Facets are documented under [Facet](https://www.jetbrains.com/help/idea/adding-s ## Additional Information For more information on each of these entities, see: -- [Project](/reference_guide/project_model/project.md) -- [Module](/reference_guide/project_model/module.md) -- [SDK](/reference_guide/project_model/sdk.md) -- [Library](/reference_guide/project_model/library.md) -- [External system integration](/reference_guide/frameworks_and_external_apis/external_system_integration.md) (for projects imported from Gradle or similar build systems) +- [Project](project.md) +- [Module](module.md) +- [SDK](sdk.md) +- [Library](library.md) +- [External system integration](external_system_integration.md) (for projects imported from Gradle or similar build systems) \ No newline at end of file diff --git a/basics/project_view.md b/topics/basics/project_view.md similarity index 63% rename from basics/project_view.md rename to topics/basics/project_view.md index 80269b57b..faf77eeb6 100644 --- a/basics/project_view.md +++ b/topics/basics/project_view.md @@ -1,6 +1,5 @@ ---- -title: Project View ---- +[//]: # (title: Project View) + -* [Modifying Project View Structure](/tutorials/tree_structure_view.md) +* [Modifying Project View Structure](tree_structure_view.md) \ No newline at end of file diff --git a/basics/psi_cookbook.md b/topics/basics/psi_cookbook.md similarity index 79% rename from basics/psi_cookbook.md rename to topics/basics/psi_cookbook.md index 77ad9298a..f3d76d237 100644 --- a/basics/psi_cookbook.md +++ b/topics/basics/psi_cookbook.md @@ -1,12 +1,13 @@ ---- -title: PSI Cookbook ---- +[//]: # (title: PSI Cookbook) + This page gives recipes for the most common operations for working with the PSI (Program Structure Interface). -Unlike [Developing Custom Language Plugins](/reference_guide/custom_language_support.md), it talks about working with the PSI of existing languages (such as Java). +Unlike [Developing Custom Language Plugins](custom_language_support.md), it talks about working with the PSI of existing languages (such as Java). -> **TIP** Please see also [Working with PSI efficiently](/reference_guide/performance/performance.md#working-with-psi-efficiently). + > Please see also [Working with PSI efficiently](performance.md#working-with-psi-efficiently). + > + {type="tip"} ### How do I find a file if I know its name but don't know the path? @@ -55,4 +56,4 @@ or ### How do I find the methods overriding a specific method? -`OverridingMethodsSearch.search()` +`OverridingMethodsSearch.search()` \ No newline at end of file diff --git a/basics/run_configurations/run_configuration_execution.md b/topics/basics/run_configurations/run_configuration_execution.md similarity index 99% rename from basics/run_configurations/run_configuration_execution.md rename to topics/basics/run_configurations/run_configuration_execution.md index 733b32ed0..fd33ecaaa 100644 --- a/basics/run_configurations/run_configuration_execution.md +++ b/topics/basics/run_configurations/run_configuration_execution.md @@ -1,6 +1,5 @@ ---- -title: Execution ---- +[//]: # (title: Execution) + The standard execution of a run action goes through the following steps: @@ -64,4 +63,4 @@ Two common filter implementations you may want to reuse are [`RegexpFilter`](ups If you have an existing run configuration that you need to execute, the easiest way to do so is to use [`ProgramRunnerUtil.executeConfiguration()`](upsource:///platform/execution-impl/src/com/intellij/execution/ProgramRunnerUtil.java). The method takes a [`Project`](upsource:///platform/core-api/src/com/intellij/openapi/project/Project.java), a [`RunnerAndConfigurationSettings`](upsource:///platform/lang-api/src/com/intellij/execution/RunnerAndConfigurationSettings.java), as well as an [`Executor`](upsource:///platform/lang-api/src/com/intellij/execution/Executor.java). To get the `RunnerAndConfigurationSettings` for an existing configuration, you can use, for example, `RunManager.getConfigurationSettings(ConfigurationType)`. -As the last parameter, you normally pass either `DefaultRunExecutor.getRunExecutorInstance()` or `DefaultDebugExecutor.getDebugExecutorInstance()`. +As the last parameter, you normally pass either `DefaultRunExecutor.getRunExecutorInstance()` or `DefaultDebugExecutor.getDebugExecutorInstance()`. \ No newline at end of file diff --git a/basics/run_configurations/run_configuration_management.md b/topics/basics/run_configurations/run_configuration_management.md similarity index 97% rename from basics/run_configurations/run_configuration_management.md rename to topics/basics/run_configurations/run_configuration_management.md index 54d4d4853..eff706299 100644 --- a/basics/run_configurations/run_configuration_management.md +++ b/topics/basics/run_configurations/run_configuration_management.md @@ -1,19 +1,15 @@ ---- -title: Run Configuration Management ---- +[//]: # (title: Run Configuration Management) + This document describes the primary classes to work with run configurations and everyday use cases. -* Dummy table of contents -{:toc} - ## Configuration Type The starting point for implementing any run configuration type is the [`ConfigurationType`](upsource:///platform/lang-api/src/com/intellij/execution/configurations/ConfigurationType.java) interface. The list of available configuration types is shown when a user opens the _'Edit run configurations'_ dialog and executes _'Add'_ action: -![Create](/basics/img/create-1.png) +![Create](create-1.png) Every type there is represented as an instance of [`ConfigurationType`](upsource:///platform/lang-api/src/com/intellij/execution/configurations/ConfigurationType.java) and registered like below: @@ -30,7 +26,7 @@ In addition to that, you need to call the [`addFactory()`](upsource:///platform/ All run configurations are created by the [`ConfigurationFactory`](upsource:///platform/lang-api/src/com/intellij/execution/configurations/ConfigurationFactory.java) registered for a particular `ConfigurationType`. It's possible that one `ConfigurationType` [has more than one](upsource:///platform/lang-api/src/com/intellij/execution/configurations/ConfigurationType.java) `ConfigurationFactory`: -![Configuration Factory](/basics/img/create-3.png) +![Configuration Factory](create-3.png) The key API of [`ConfigurationFactory`](upsource:///platform/lang-api/src/com/intellij/execution/configurations/ConfigurationFactory.java), and the only method that you're required to implement, is the [`createTemplateConfiguration`](upsource:///platform/lang-api/src/com/intellij/execution/configurations/ConfigurationFactory.java) method. This method is called once per project to create the template run configuration. @@ -47,7 +43,7 @@ A _'run configuration'_ here is some named profile which can be executed, e.g., Here is an example of a Java run configuration defined for a particular project: -![Run Configuration](/basics/img/create-2.png) +![Run Configuration](create-2.png) When implementing a run configuration, you may want to use one of the common base classes: @@ -107,4 +103,4 @@ Note that, to support the automatic naming of configurations created from contex ## Running from the Gutter -Take a look at [`RunLineMarkerContributor`](upsource:///platform/execution-impl/src/com/intellij/execution/lineMarker/RunLineMarkerContributor.java) and its implementations. +Take a look at [`RunLineMarkerContributor`](upsource:///platform/execution-impl/src/com/intellij/execution/lineMarker/RunLineMarkerContributor.java) and its implementations. \ No newline at end of file diff --git a/topics/basics/settings.md b/topics/basics/settings.md new file mode 100644 index 000000000..63869671a --- /dev/null +++ b/topics/basics/settings.md @@ -0,0 +1,10 @@ +[//]: # (title: Settings) + + + +## Introduction to Settings +[Settings](https://www.jetbrains.com/help/idea/configuring-project-and-ide-settings.html) are but one application of the IntelliJ Platform [Persistence Model](persistence.md). +For more information, see: +* [Settings Guide](settings_guide.md) for information about Settings Extension Points and implementations. +* [Custom Settings Groups](settings_groups.md) for information about creating custom Settings groups and parent-child relationships. +* [Settings Tutorial](settings_tutorial.md) for step-by-step instructions for creating a simple set of custom Settings. \ No newline at end of file diff --git a/topics/basics/templates.md b/topics/basics/templates.md new file mode 100644 index 000000000..f618b0422 --- /dev/null +++ b/topics/basics/templates.md @@ -0,0 +1,9 @@ +[//]: # (title: Templates) + + + +* [Live Templates](live_templates.md) + * [Adding Live Templates to a Plugin](template_support.md) + * [Creating New Functions for Live Templates](new_macros.md) + * Surround Templates +* File Templates \ No newline at end of file diff --git a/basics/testing_plugins/light_and_heavy_tests.md b/topics/basics/testing_plugins/light_and_heavy_tests.md similarity index 79% rename from basics/testing_plugins/light_and_heavy_tests.md rename to topics/basics/testing_plugins/light_and_heavy_tests.md index a10e19fb9..a9774b138 100644 --- a/basics/testing_plugins/light_and_heavy_tests.md +++ b/topics/basics/testing_plugins/light_and_heavy_tests.md @@ -1,6 +1,5 @@ ---- -title: Light and Heavy Tests ---- +[//]: # (title: Light and Heavy Tests) + Plugin tests run in a real, rather than mocked, *IntelliJ Platform* environment and use real implementations for most application and project components/services. @@ -13,7 +12,9 @@ Dependently on the loading and execution time, we make a difference between *hea Light and heavy tests use different base classes or fixture classes, as described below. -> **NOTE** Because of the performance difference, we recommend plugin developers to write *light* tests whenever possible. + > Because of the performance difference, we recommend plugin developers to write *light* tests whenever possible. + > + {type="note"} ## Light Tests @@ -22,18 +23,23 @@ The standard way of writing a light test is to extend the following classes: * [`LightPlatformCodeInsightFixtureTestCase`](upsource:///platform/testFramework/src/com/intellij/testFramework/fixtures/LightPlatformCodeInsightFixtureTestCase.java) for tests that don't have any Java dependencies. * [`LightCodeInsightFixtureTestCase`](upsource:///java/testFramework/src/com/intellij/testFramework/fixtures/LightCodeInsightFixtureTestCase.java) for tests that require the Java PSI or any related functionality. -> **NOTE** In 2019.2, `LightPlatformCodeInsightFixtureTestCase` has been renamed to `BasePlatformTestCase` and `LightCodeInsightFixtureTestCase` to `LightJavaCodeInsightFixtureTestCase` respectively. + > In 2019.2, `LightPlatformCodeInsightFixtureTestCase` has been renamed to `BasePlatformTestCase` and `LightCodeInsightFixtureTestCase` to `LightJavaCodeInsightFixtureTestCase` respectively. + > + {type="note"} When writing a light test, you can specify the project's requirements that you need to have in your test, such as the module type, the configured SDK, facets, libraries, etc. You do so by extending the [`LightProjectDescriptor`](upsource:///platform/testFramework/src/com/intellij/testFramework/LightProjectDescriptor.java) class and returning your project descriptor from `getProjectDescriptor()`. Before executing each test, the project will be reused if the test case returns the same project descriptor (usually stored in static final field) as the previous one, or recreated if the descriptor is different (`equals() = false`). - ## Heavy Tests -> **NOTE** If you need to set up a multi-module project for your tests, you **must** write a heavy test. + > If you need to set up a multi-module project for your tests, you **must** write a heavy test. + > + {type="note"} -> **NOTE** In 2019.3, `PlatformTestCase` has been renamed to `HeavyPlatformTestCase` reflecting its "heavy test" characteristics. + > In 2019.3, `PlatformTestCase` has been renamed to `HeavyPlatformTestCase` reflecting its "heavy test" characteristics. + > + {type="note"} The setup code for a multi-module Java project looks something like that: @@ -44,4 +50,4 @@ final TestFixtureBuilder projectBuilder = IdeaTestFixtur final JavaModuleFixtureBuilder moduleFixtureBuilder = projectBuilder.addModule(JavaModuleFixtureBuilder.class); myFixture = JavaTestFixtureFactory.getFixtureFactory().createCodeInsightFixture(projectBuilder.getFixture()); -``` +``` \ No newline at end of file diff --git a/basics/testing_plugins/test_project_and_testdata_directories.md b/topics/basics/testing_plugins/test_project_and_testdata_directories.md similarity index 77% rename from basics/testing_plugins/test_project_and_testdata_directories.md rename to topics/basics/testing_plugins/test_project_and_testdata_directories.md index fe42e3986..372d1fa5a 100644 --- a/basics/testing_plugins/test_project_and_testdata_directories.md +++ b/topics/basics/testing_plugins/test_project_and_testdata_directories.md @@ -1,6 +1,5 @@ ---- -title: Test Project and Testdata Directories ---- +[//]: # (title: Test Project and Testdata Directories) + The test fixture creates a *test project* environment. @@ -9,8 +8,10 @@ The test project files exist either in a temporary directory or in an in-memory [`LightPlatformCodeInsightFixtureTestCase`](upsource:///platform/testFramework/src/com/intellij/testFramework/fixtures/LightPlatformCodeInsightFixtureTestCase.java) (renamed to `BasePlatformTestCase` in 2019.2) uses an in-memory implementation; if you set up the test environment by calling `IdeaTestFixtureFactory.createCodeInsightFixture()`, you can specify the implementation to use. -> **WARNING** If your tests use the in-memory implementation, and you abort the execution of your tests, the persisted filesystem caches may get out of sync with the in-memory structures, and you may get spurious errors in your tests. -> If you get an unexpected error after a series of successful runs, **try rerunning the test**, and if that doesn't help, **delete the "system" subdirectory** in your [sandbox directory](/basics/ide_development_instance.md#the-development-instance-sandbox-directory). + > If your tests use the in-memory implementation, and you abort the execution of your tests, the persisted filesystem caches may get out of sync with the in-memory structures, and you may get spurious errors in your tests. +> If you get an unexpected error after a series of successful runs, **try rerunning the test**, and if that doesn't help, **delete the "system" subdirectory** in your [sandbox directory](ide_development_instance.md#the-development-instance-sandbox-directory). + > + {type="warning"} In your plugin, you usually store the test data for your tests (such as files on which plugin features will be executed and expected output files) in the `testdata` directory. This is just a directory under your plugin's content root, but not under a source root. @@ -19,11 +20,15 @@ Files in `testdata` usually are not valid source code and must not be compiled. To specify the location of `testdata`, you must override the `getTestDataPath()` method. The default implementation assumes running as part of the *IntelliJ Platform* source tree and is not appropriate for third-party plugins. -> **NOTE** A very common pattern in *IntelliJ Platform* tests is to use the test method's name being executed as the base for building the `testdata` file paths. + > A very common pattern in *IntelliJ Platform* tests is to use the test method's name being executed as the base for building the `testdata` file paths. > This allows us to reuse most of the code between different test methods that test various aspects of the same feature, and this approach is also recommended for third-party plugin tests. > The name of the test method can be retrieved using `UsefulTestCase.getTestName()`. + > + {type="note"} -> **NOTE** If your plugin builds on top of Java support, please see [Tests Prerequisites](/tutorials/writing_tests_for_plugins/tests_prerequisites.md) for setting up your test environment to obtain required _Mock JDK_ automatically. + > If your plugin builds on top of Java support, please see [Tests Prerequisites](tests_prerequisites.md) for setting up your test environment to obtain required _Mock JDK_ automatically. + > + {type="note"} To copy files or directories from your `testdata` directory to the test project directory, you can use the `copyFileToProject()` and `copyDirectoryToProject()` methods in the [`CodeInsightTestFixture`](upsource:///platform/testFramework/src/com/intellij/testFramework/fixtures/CodeInsightTestFixture.java) class. @@ -35,7 +40,9 @@ The latter copies multiple files to the test project directory and opens the *fi Alternatively, you can use one of the other methods which take parameters annotated with [`@TestDataFile`](upsource:///platform/testFramework/src/com/intellij/testFramework/TestDataFile.java). These methods copy the specified files from the `testdata` directory to the test project directory, open the first of the specified files in the in-memory editor, and then perform the requested operation such as highlighting or code completion. -> **TIP** The IDE supports smart navigation between test code and related test data file(s); see this [blog post](https://blog.jetbrains.com/platform/2017/10/improvements-in-testing-intellij-platform-plugins/) for more details. + > The IDE supports smart navigation between test code and related test data file(s); see this [blog post](https://blog.jetbrains.com/platform/2017/10/improvements-in-testing-intellij-platform-plugins/) for more details. + > + {type="tip"} ### Special Markup When a file is opened in the in-memory editor, special markup in the file content can specify the caret position or selection. @@ -43,4 +50,4 @@ When a file is opened in the in-memory editor, special markup in the file conten You can use one of the following markers: * `` specifies the position where the caret should be placed. * `` and `` specify the start and end of the selected text range. -* `` and `` specify the column selection's start and end points. +* `` and `` specify the column selection's start and end points. \ No newline at end of file diff --git a/basics/testing_plugins/testing_highlighting.md b/topics/basics/testing_plugins/testing_highlighting.md similarity index 96% rename from basics/testing_plugins/testing_highlighting.md rename to topics/basics/testing_plugins/testing_highlighting.md index 5e1778bbd..90cd34fae 100644 --- a/basics/testing_plugins/testing_highlighting.md +++ b/topics/basics/testing_plugins/testing_highlighting.md @@ -1,6 +1,5 @@ ---- -title: Testing Highlighting ---- +[//]: # (title: Testing Highlighting) + When writing plugin tests, a common task is testing various kinds of highlighting (inspections, annotators, parser error highlighting, etc.). @@ -47,7 +46,7 @@ The tag can also have the following optional attributes: * `effectType` expected effect type for the highlighting (see [`EffectType`](upsource:///platform/core-api/src/com/intellij/openapi/editor/markup/EffectType.java)) * `fontType` expected font style for the highlighting (0 - normal, 1 - bold, 2 - italic, 3 - bold italic) -> **NOTE** *Nested* tags are **supported**: + > *Nested* tags are **supported**: > ```warning_highlightwarning_and_info_highlightwarning_highlight``` > *Overlapping* tags (annotations) are currently **not supported** in the test framework (but display correctly in the editor, albeit this is not an officially supported scenario): -> ```warning_highlightwarning-and_info_highlightinfo_highlight``` +> ```warning_highlightwarning-and_info_highlightinfo_highlight``` \ No newline at end of file diff --git a/basics/testing_plugins/testing_plugins.md b/topics/basics/testing_plugins/testing_plugins.md similarity index 90% rename from basics/testing_plugins/testing_plugins.md rename to topics/basics/testing_plugins/testing_plugins.md index d6f14402c..06d6c9a2e 100644 --- a/basics/testing_plugins/testing_plugins.md +++ b/topics/basics/testing_plugins/testing_plugins.md @@ -1,8 +1,5 @@ ---- -title: Testing Plugins -redirect_from: - - /basics/testing_plugins.html ---- +[//]: # (title: Testing Plugins) + Most of the tests in the *IntelliJ Platform* codebase are *model level functional tests*. @@ -36,4 +33,4 @@ Another consequence of our testing approach is what our test framework does not * [Writing Tests](writing_tests.md) * [Testing Highlighting](testing_highlighting.md) -Check out [this step-by-step tutorial](/tutorials/writing_tests_for_plugins.md) teaching how to write and run automated tests for your custom language plugin (source code included). +Check out [this step-by-step tutorial](writing_tests_for_plugins.md) teaching how to write and run automated tests for your custom language plugin (source code included). \ No newline at end of file diff --git a/basics/testing_plugins/tests_and_fixtures.md b/topics/basics/testing_plugins/tests_and_fixtures.md similarity index 95% rename from basics/testing_plugins/tests_and_fixtures.md rename to topics/basics/testing_plugins/tests_and_fixtures.md index 0aebeb463..09feef72d 100644 --- a/basics/testing_plugins/tests_and_fixtures.md +++ b/topics/basics/testing_plugins/tests_and_fixtures.md @@ -1,6 +1,5 @@ ---- -title: Tests and Fixtures ---- +[//]: # (title: Tests and Fixtures) + The *IntelliJ Platform* testing infrastructure is not tied to any specific test framework. @@ -11,4 +10,4 @@ When writing your tests, you have the choice between using a standard base class With the former approach, you can use classes such as [`LightPlatformCodeInsightFixtureTestCase`](upsource:///platform/testFramework/src/com/intellij/testFramework/fixtures/LightPlatformCodeInsightFixtureTestCase.java) (renamed to [`BasePlatformTestCase`](upsource:///platform/testFramework/src/com/intellij/testFramework/fixtures/BasePlatformTestCase.java) in 2019.2). -With the latter approach, you use the [`IdeaTestFixtureFactory`](upsource:///platform/testFramework/src/com/intellij/testFramework/fixtures/IdeaTestFixtureFactory.java) class to create instances of fixtures for the test environment, and you need to call the fixture creation and setup methods from the test setup method used by your test framework. +With the latter approach, you use the [`IdeaTestFixtureFactory`](upsource:///platform/testFramework/src/com/intellij/testFramework/fixtures/IdeaTestFixtureFactory.java) class to create instances of fixtures for the test environment, and you need to call the fixture creation and setup methods from the test setup method used by your test framework. \ No newline at end of file diff --git a/basics/testing_plugins/writing_tests.md b/topics/basics/testing_plugins/writing_tests.md similarity index 94% rename from basics/testing_plugins/writing_tests.md rename to topics/basics/testing_plugins/writing_tests.md index 7c18ad7aa..451482a98 100644 --- a/basics/testing_plugins/writing_tests.md +++ b/topics/basics/testing_plugins/writing_tests.md @@ -1,6 +1,5 @@ ---- -title: Writing Tests ---- +[//]: # (title: Writing Tests) + In most cases, once you have the necessary files copied to the test project and loaded into the in-memory editor, writing the test itself involves invoking your plugin code and has few dependencies on the test framework. @@ -15,4 +14,4 @@ However, for many common cases, the framework provides helper methods that can m To compare the results of executing the action with the expected results, you can use the `checkResultByFile()` method. The file with the expected results can also contain [markup](test_project_and_testdata_directories.md#special-markup) to specify the expected caret position or selected text range. -Suppose you're testing an action that modifies multiple files (a project-wide refactoring, for example). In that case, you can compare an entire directory under the test project with the expected output using `PlatformTestUtil.assertDirectoriesEqual()`. +Suppose you're testing an action that modifies multiple files (a project-wide refactoring, for example). In that case, you can compare an entire directory under the test project with the expected output using `PlatformTestUtil.assertDirectoriesEqual()`. \ No newline at end of file diff --git a/basics/types_of_plugins.md b/topics/basics/types_of_plugins.md similarity index 88% rename from basics/types_of_plugins.md rename to topics/basics/types_of_plugins.md index 3095f3a5f..5f80c74f5 100644 --- a/basics/types_of_plugins.md +++ b/topics/basics/types_of_plugins.md @@ -1,6 +1,5 @@ ---- -title: Main Types of Plugins ---- +[//]: # (title: Main Types of Plugins) + Products based on the *IntelliJ Platform* can be modified and adjusted for custom purposes by adding plugins. @@ -16,7 +15,7 @@ The most common types of plugins include: ## UI Themes -[UI Themes](/reference_guide/ui_themes/themes_intro.md) give designers the ability to customize the appearance of built-in IDE UI elements. +[UI Themes](themes_intro.md) give designers the ability to customize the appearance of built-in IDE UI elements. Custom UI Themes can: * substitute icons, @@ -41,7 +40,7 @@ Custom language support provides basic functionality for working with a particul Plugins can also augment existing (bundled) custom languages, e.g., by providing additional inspections, intentions, or any other features. -Refer to the [Custom Language Support Tutorial](/tutorials/custom_language_support_tutorial.md) to learn more about the topic. +Refer to the [Custom Language Support Tutorial](custom_language_support_tutorial.md) to learn more about the topic. ## Framework Integration @@ -68,4 +67,4 @@ Refer to the [Gerrit integration](https://plugins.jetbrains.com/plugin/7272?pr=i Plugins in this category apply various changes to the standard user interface of the IDE. Some newly added components are interactive and provide new functionality, while others are limited to visual modifications only. -The [Random Background](https://plugins.jetbrains.com/plugin/9692-random-background) plugin may serve as an example. +The [Random Background](https://plugins.jetbrains.com/plugin/9692-random-background) plugin may serve as an example. \ No newline at end of file diff --git a/basics/virtual_file_system.md b/topics/basics/virtual_file_system.md similarity index 90% rename from basics/virtual_file_system.md rename to topics/basics/virtual_file_system.md index 2eae58e60..bfd282094 100644 --- a/basics/virtual_file_system.md +++ b/topics/basics/virtual_file_system.md @@ -1,9 +1,8 @@ ---- -title: Virtual File System ---- +[//]: # (title: Virtual File System) + -The virtual file system (VFS) is a component of the *IntelliJ Platform* that encapsulates most of its activity for working with files represented as [Virtual File](/basics/architectural_overview/virtual_file.md). +The virtual file system (VFS) is a component of the *IntelliJ Platform* that encapsulates most of its activity for working with files represented as [Virtual File](virtual_file.md). It serves the following main purposes: @@ -23,8 +22,10 @@ If the information is available in the snapshot, the snapshot data is returned. The contents of files and the lists of files in directories are stored in the snapshot only if that specific information was accessed. Otherwise, only file metadata like name, length, timestamp, attributes are stored. -> **NOTE** This means that the state of the file system and the file contents displayed in the IntelliJ Platform UI comes from the snapshot, which may not always match the disk's actual contents. + > This means that the state of the file system and the file contents displayed in the IntelliJ Platform UI comes from the snapshot, which may not always match the disk's actual contents. > For example, in some cases, deleted files can still be visible in the UI for some time before the deletion is picked up by the IntelliJ Platform. + > + {type="note"} The snapshot is updated from disk during _refresh operations_, which generally happen asynchronously. All write operations made through the VFS are synchronous - i.e., the contents are saved to disk immediately. @@ -62,7 +63,7 @@ The synchronous flag simply means that the calling thread will be blocked until Both synchronous and asynchronous refreshes can be initiated from any thread. If a refresh is initiated from a background thread, the calling thread must not hold a read action, because otherwise, a deadlock would occur. -See [IntelliJ Platform Architectural Overview](/basics/architectural_overview/general_threading_rules.md) for more details on the threading model and read/write actions. +See [IntelliJ Platform Architectural Overview](general_threading_rules.md) for more details on the threading model and read/write actions. The same threading requirements also apply to functions like [`LocalFileSystem.refreshAndFindFileByPath()`](upsource:///platform/analysis-api/src/com/intellij/openapi/vfs/LocalFileSystem.java), which perform a partial refresh if the file with the specified path is not found in the snapshot. @@ -81,10 +82,12 @@ VFS events are always fired in the event dispatch thread and in a write action. The most efficient way to listen to VFS events is to implement [`BulkFileListener`](upsource:///platform/core-api/src/com/intellij/openapi/vfs/newvfs/BulkFileListener.java) and to subscribe with it to the [`VirtualFileManager.VFS_CHANGES`](upsource:///platform/core-api/src/com/intellij/openapi/vfs/VirtualFileManager.java) topic. A non-blocking variant [`AsyncFileListener`](upsource:///platform/core-api/src/com/intellij/openapi/vfs/AsyncFileListener.java) is also available in 2019.2 or later. -See [How do I get notified when VFS changes?](/basics/architectural_overview/virtual_file.md#how-do-i-get-notified-when-vfs-changes) for implementation details. +See [How do I get notified when VFS changes?](virtual_file.md#how-do-i-get-notified-when-vfs-changes) for implementation details. -> **WARNING** VFS listeners are application level and will receive events for changes happening in *all* the projects opened by the user. + > VFS listeners are application level and will receive events for changes happening in *all* the projects opened by the user. > You may need to filter out events that aren't relevant to your task (e.g., via [`ProjectFileIndex.isInContent()`](upsource:///platform/projectModel-api/src/com/intellij/openapi/roots/ProjectFileIndex.java)). + > + {type="warning"} VFS events are sent both before and after each change, and you can access the old contents of the file in the before event. Note that events caused by a refresh are sent after the changes have already occurred on disk. @@ -94,4 +97,4 @@ However, it is still present in the VFS snapshot, and you can access its last co Note that a refresh operation fires events only for changes in files that have been loaded in the snapshot. For example, if you accessed a `VirtualFile` for a directory but never loaded its contents using [`VirtualFile.getChildren()`](upsource:///platform/core-api/src/com/intellij/openapi/vfs/VirtualFile.java), you may not get `fileCreated` notifications when files are created in that directory. -If you loaded only a single file in a directory using `VirtualFile.findChild()`, you will get notifications for changes to that file, but you may not get created/deleted notifications for other files in the same directory. +If you loaded only a single file in a directory using `VirtualFile.findChild()`, you will get notifications for changes to that file, but you may not get created/deleted notifications for other files in the same directory. \ No newline at end of file diff --git a/topics/info b/topics/info new file mode 100644 index 000000000..dd201bc8a --- /dev/null +++ b/topics/info @@ -0,0 +1 @@ +Store your code snippets here \ No newline at end of file diff --git a/topics/intellij-sdk-docs-original_CODE_OF_CONDUCT.md b/topics/intellij-sdk-docs-original_CODE_OF_CONDUCT.md new file mode 100644 index 000000000..535f06104 --- /dev/null +++ b/topics/intellij-sdk-docs-original_CODE_OF_CONDUCT.md @@ -0,0 +1,8 @@ +[//]: # (title: Code of Conduct) + + + +## Code of Conduct + +This project and the corresponding community is governed by the [JetBrains Open Source and Community Code of Conduct](https://confluence.jetbrains.com/display/ALL/JetBrains+Open+Source+and+Community+Code+of+Conduct). +Please make sure you read it. \ No newline at end of file diff --git a/topics/intellij-sdk-docs-original_CONTRIBUTING.md b/topics/intellij-sdk-docs-original_CONTRIBUTING.md new file mode 100644 index 000000000..09e024057 --- /dev/null +++ b/topics/intellij-sdk-docs-original_CONTRIBUTING.md @@ -0,0 +1,150 @@ +[//]: # (title: Contributing to the IntelliJ Platform SDK) + + + +This document describes our contribution guidelines for the open-source IntelliJ Platform SDK documentation and sample code. +Before you begin contributing content to the SDK, please read this page thoroughly as well as the [Code of Conduct](intellij-sdk-docs-original_CODE_OF_CONDUCT.md) and [License](https://github.com/JetBrains/intellij-sdk-docs/blob/master/LICENSE.txt) documents. +For information about contributing to the IntelliJ Platform itself, please visit [Contributing to the IntelliJ Platform](platform_contributions.md). + +Here are some useful things to know before authoring SDK content and submitting your Pull Request. + +## Setting Up the Documentation Build Environment + +This site runs via [Jekyll](https://jekyllrb.com), which is a popular static site generator, written in Ruby. +It can be hosted locally to ensure that any changes are correct. +Once set up, running the site is as easy as calling `rake preview`. + +Alternatively, the site can also be hosted in a [Docker container](https://www.docker.com). +On Mac and Windows, this means the site is hosted in a virtual machine. +Docker maintains this container, building it based on the instructions in the [`Dockerfile`](https://github.com/JetBrains/intellij-sdk-docs/blob/master/Dockerfile). +All dependencies (Ruby, etc.) are automatically installed when building the image, which reduces the manual configuration steps. +The Docker image is also used to build the [published site](https://www.jetbrains.org/intellij/sdk/docs/index.html), so it is a known working environment. + +### Developing Documentation with Docker + +Follow these steps to work with Docker: + +* Firstly, install Docker, using the [Docker Toolbox](https://www.docker.com/docker-toolbox). +* On Windows and Mac, start the Docker host virtual machine (start the "Docker Quickstart Terminal" or run "Kitematic." See the Getting Started guides on [docker.com](https://www.docker.com) for more details). +* Clone the [`intellij-sdk-docs`](https://github.com/JetBrains/intellij-sdk-docs) repository to the local machine, and [initialize the `sdkdocs-template` submodule](#documentation-repository-submodules). +* Change the current directory to the parent directory of the git repository. +* Run `docker build -t intellij-sdk-docs .` to build the Docker image from the current folder, and give it the tag `intellij-sdk-docs`. + * Note that this must be run from a command prompt that has the various `DOCKER_*` environment variables set up, such as the Docker Quickstart Terminal. +* Run `docker run -p 4000:4000 -v $PWD:/usr/src/app intellij-sdk-docs`. This command will: + * Start the Docker container called `intellij-sdk-docs`. + * Forward port 4000 from the Docker container to port 4000 on the Docker client. + + > For Windows and Mac, this means port 4000 of the Docker container is forwarded to port 4000 of the Docker virtual machine, not `localhost`. + > For Linux, the Docker client is the host machine, so `localhost:4000` is forwarded to port 4000 on the Docker container. + > + > To hit the container's port 4000 from Windows or the Mac, it is necessary to hit the IP address of the Docker client (virtual machine). + > Use `docker-machine ip default` to get the IP address of the Docker client. + > Use `X.X.X.X:4000` to hit the client in the virtual machine, which is mapped to the container's port 4000. + > + > Alternatively, modify the virtual machine's settings to forward port 4000 automatically to `localhost`. + > See this [blog post](https://acaird.github.io/computers/2014/11/16/docker-virtualbox-host-networking) for more details. + > + {type="note"} + + * Mount the current directory (`$PWD` is a Unix style environment variable. + You can use `%CD%` on Windows, or specify the full path) as `/usr/src/app` inside the Docker container. + The Docker image will see the `intellij-sdk-docs` repository as the folder `/usr/src/app`. + + > If running on Windows in an MSYS bash script (e.g., the "Docker Quickstart Terminal"), the path to the local folder needs to be properly escaped, or the MSYS environment will translate the paths to standard Windows path, and causing an error such as `invalid value "C:\\Users\\...;C:\\Program Files\\Git\\usr\\src\\app" for flag -v`. + > To fix this problem, prefix the full path with double slashes, e.g., `-v //c/Users/...`, or `docker run -p 4000:4000 -v /$PWD:/usr/src/app intellij-sdk-docs` (note the leading slash before `$PWD`). + > + {type="note"} + + * Run the commands in the Dockerfile's `CMD` instruction to execute: + * `rake bootstrap`, which ensures all of the prerequisites are installed, + * `rake preview`, which builds the site and starts to host it. +* Finally, you can access the newly created site by visiting [http://localhost:4000/intellij/sdk/docs/](http://localhost:4000/intellij/sdk/docs/), or by using the IP address of the Docker client virtual machine (see the note above). + +### Developing Documentation Locally + +To build the documentation site, you need: + +* Ruby 2 - Jekyll is a Ruby application. +* Ruby 2 DevKit (for Windows) - Some of Jekyll's dependencies need to be compiled, and require the DevKit to be installed. +* `gem install bundler` - the site uses [Bundler](https://bundler.io) to manage gem dependencies within the repository, rather than globally installing to the local operating system. + Run this command to install the Bundler toolset globally. + +#### macOS + +macOS comes with Ruby already installed. +The only steps required are: + +* `gem install bundler` + +#### Windows + +* Install [Ruby 2](https://rubyinstaller.org) and the [Ruby 2 DevKit](https://rubyinstaller.org/downloads/) (one of the gems needs to build a native component) + * After installing the DevKit, make sure to edit the `config.yml` file to point to the Ruby installation + +This installation is easier if you use [Chocolatey](https://chocolatey.org), a package manager for Windows: + +* `choco install ruby` +* `choco install ruby2.devkit` + * After installing the DevKit, make sure to edit the `config.yml` file to point to the Ruby installation. + * By default, this is `C:\tools\DevKit\config.yml` + * Add the line `- C:\tools\ruby21` (including the leading minus sign) + + > Before running the `rake bootstrap` step listed below, please run the `devkitvars.bat` file from the DevKit. +> E.g. `C:\tools\DevKit\devkitvars.bat` + > + {type="note"} + +### Bootstrapping the Documentation Build Environment + +1. Ensure Bundler is installed - `gem install bundler`. +2. On Windows, ensure the `devkitvars.bat` file has been run in the current command prompt (e.g., `c:\tools\DevKit\devkitvars.bat`). +3. Clone the documentation site. +4. Initialize and update the `sdkdocs-template` submodule - `git submodule init` and `git submodule update`. +5. `rake bootstrap` - this uses Bundler to download all required gems. +6. `rake preview` - this will build the site, and host it in a local webserver. + +### Building and Previewing the Site + +To build and test the site, run `rake preview`. +This will build the site and host it using the config provided. +The URL of the hosted website is displayed on the screen and depends on the `baseurl` field defined in `_config.yml`. + + > You must use `localhost` as hostname, _NOT_ 0.0.0.0, otherwise fonts fail to load. + > + {type="note"} + +## Documentation Repository Submodules +The `sdkdocs-template` directory is a Git submodule, and it contains a submodule to the private `webhelp-template` repository. +The `sdkdocs-template` repository contains build scripts and compiled and minified JS and CSS that allow the site to run. +The private `webhelp-template` repository contains the code to build the JS and CSS. +It is currently closed source, but the plan is to make it open-source at some point, in which case it is likely the two repositories will be merged. + +After cloning, a submodule needs to be initialized and updated: + +```sh +git submodule init +git submodule update +``` + +Initialization creates a `.gitmodules` file, register a submodule in the `sdkdocs-template` folder and check out the files. +Note that when a repository is added as a submodule, it doesn't get a `.git` folder, but instead gets a `.git` file that points to the actual location of the `.git` folder. + +A submodule can be updated using standard git commands such as `git pull`. +It can be switched to a different branch using `git checkout`, and any changes to the currently checked out revision need to be committed back into the main repository using git commands. +A submodule is initially cloned at a specific revision, and not as part of a branch.update + +If changes are made to the submodule, they should be made on a branch to a clone, and a Pull Request sent. +Changes can be made and committed, and the hosting repository will need to commit a pointer to the current version of the submodule. + +If there are any problems with the `sdkdocs-template`, please [raise an issue](https://github.com/JetBrains/sdkdocs-template/issues). + +## Creating IntelliJ Platform SDK Content +Content contributions to the IntelliJ Platform SDK are welcome. +Please download or clone the open-source SDK project from [GitHub](https://github.com/JetBrains/intellij-sdk-docs), make additions or changes, and submit a pull request. +Before creating or altering content, please consult these guides: +* [SDK Documentation Style Guide](sdk_style.md). + This guide describes documentation conventions in terms of Markdown syntax. + Always test documentation changes using a [preview](#building-and-previewing-the-site) of the site. +* [SDK Code Sample Guidelines](sdk_code_guidelines.md). + Conventions for code sample organization, project settings, and naming conventions are described in this document. + Always test code changes by building and testing the SDK code sample. \ No newline at end of file diff --git a/intro/about.md b/topics/intro/about.md similarity index 77% rename from intro/about.md rename to topics/intro/about.md index 3662884c6..d68fe48f9 100644 --- a/intro/about.md +++ b/topics/intro/about.md @@ -1,35 +1,36 @@ ---- -title: About This Guide ---- +[//]: # (title: About This Guide) + This guide is split into several parts, similar to a textbook. Each one builds on the content of the previous section, but it is not necessary to read the guide in order. The [Key Topics](key_topics.md) page aims to link to the pages that are necessary to be able to understand the architecture and get started building plugins. -> **NOTE** While browsing this guide, you will notice that there are topics that are greyed out. + > While browsing this guide, you will notice that there are topics that are greyed out. > Unfortunately, the guide is not complete and contains placeholders for specific topics. > We are working on increasing the coverage, but if you get stuck due to missing content, please see the [Getting Help](getting_help.md) section for details on how to get moving again. > > The guide is also [Open Source on GitHub](https://github.com/JetBrains/intellij-sdk-docs), and Pull Requests for new content or updates are always gratefully received. > A Pull Request does not need to be fully comprehensive - if a little update would help you, it will help other developers too! All pull requests will be reviewed before being accepted, so don't worry about inaccuracies. -> Please see the [Contributing](/CONTRIBUTING.md) page for details on building the guide locally and contributing. +> Please see the [Contributing](intellij-sdk-docs-original_CONTRIBUTING.md) page for details on building the guide locally and contributing. + > + {type="note"} -#### [Part I - Plugins](/basics/basics.md) +#### [Part I - Plugins](basics.md) Describes how to create a plugin that can extend the _IntelliJ Platform_. Includes details on how to set up the project, register extension points, target specific versions of the _IntelliJ Platform_, and how to package, deploy, and test your plugins. -#### [Part II - Base Platform](/platform/fundamentals.md) +#### [Part II - Base Platform](fundamentals.md) Describes the foundational layer of the architecture, which provides many features and utilities, such as the component model, the user interface, documents and editors, the virtual file system, settings, threading, and background tasks. The Base Platform layer mainly comprises the functionality of the _IntelliJ Platform_ that does not target language features or parsing. -#### [Part III - Project Model](/basics/project_structure.md) +#### [Part III - Project Model](project_structure.md) Documents the Project Model, which represents the files and configuration of the currently loaded project, as well as the build system used to build the project. -#### [Part IV - PSI](/basics/architectural_overview/psi.md) +#### [Part IV - PSI](psi.md) The Program Structure Interface builds the syntactic and semantic models for lots of different file types. This section describes how to work with the PSI, navigating and manipulating the syntax trees, and also looks at the powerful references system, which allows a syntax tree node to reference an item in the semantic model. @@ -40,16 +41,16 @@ It also details how PSI creates and uses indexes. Describes how to extend and interact with various features that use the PSI layer, such as code completion, navigation, Alt+Enter items, intentions, refactorings, and more. See also the section on Custom Languages below for language-specific features that are only applicable when adding support for a new language. -#### [Part VI - Testing](/basics/testing_plugins/testing_plugins.md) +#### [Part VI - Testing](testing_plugins.md) Describes the available infrastructure for writing automated tests covering the functionality of plugins. -#### [Part VII - Custom Languages](/reference_guide/custom_language_support.md) +#### [Part VII - Custom Languages](custom_language_support.md) Plugins frequently extend support for existing languages, such as adding inspections to Java files. This section describes how to add support to the _IntelliJ Platform_ for a new language that isn't supported by default, creating parsers, syntactic and semantic models, and all the features that build on top. -#### [Part VIII - Product Specific](/products/dev_alternate_products.md) +#### [Part VIII - Product Specific](dev_alternate_products.md) A lot of the functionality in the _IntelliJ Platform_ is language and product agnostic. For example, code inspections work the same in Java as they do in Ruby; it is just the syntax trees and semantic information that is different. @@ -59,14 +60,14 @@ This section describes product-specific features, such as specific project model Documents how to use the _IntelliJ Platform_ to create a new, custom IDE, rather than plugins to an existing product, e.g., WebStorm, or Android Studio. -#### [Part X - Plugin Repository](/appendix/plugin_repository_obsolete.md) +#### [Part X - Plugin Repository](plugin_repository_obsolete.md) This part has been moved to [JetBrains Marketplace documentation](https://plugins.jetbrains.com/docs/marketplace/about-marketplace.html). -#### [Appendix I - Resources](/appendix/resources/useful_links.md) +#### [Appendix I - Resources](useful_links.md) Links to useful resources, such as the IntelliJ Community Edition source code, the Plugin Development forum, and the JetBrains Platform Slack. -#### [Appendix II - API Changes](/reference_guide/api_changes_list.md) +#### [Appendix II - API Changes](api_changes_list.md) -Provides a list of [backward-incompatible](/reference_guide/api_changes_list.md) API changes as well as [notable changes and new features](/reference_guide/api_notable/api_notable.md) in each major release of the IntelliJ Platform. +Provides a list of [backward-incompatible](api_changes_list.md) API changes as well as [notable changes and new features](api_notable.md) in each major release of the IntelliJ Platform. \ No newline at end of file diff --git a/topics/intro/content_updates.md b/topics/intro/content_updates.md new file mode 100644 index 000000000..9a4aaed4b --- /dev/null +++ b/topics/intro/content_updates.md @@ -0,0 +1,86 @@ +[//]: # (title: Content Updates) + +This page lists notable additions and updates to the SDK documentation and code samples. + +Follow [JBPlatform](https://twitter.com/JBPlatform/) on Twitter and visit [JetBrains Platform Blog](https://blog.jetbrains.com/platform/) for the latest announcements. + +See [Recently Updated](recently_updated.md) ([RSS](https://github.com/JetBrains/intellij-sdk-docs/commits/master.atom)) for a detailed changelog. + +## 2020 + +### December + +IntelliJ Platform Explorer +: Explore usages of [Extension Points](extension_point_list.md) in open-source plugins using [IntelliJ Platform Explorer](https://jb.gg/ipe). + +### November + +Extension Point List +: All EPs [available in IJ Platform and Android](extension_point_list.md) can now be browsed conveniently. + +### August + +README added to Code Samples +: All code samples used in this guide now come with `README` making it easier to browse them. They can be conveniently accessed via a [separate GitHub repository](https://github.com/JetBrains/intellij-sdk-code-samples). + +### June-20 + +Dynamic Plugins update +: Added new sections _Code_ and _Troubleshooting_ to [Dynamic Plugins](dynamic_plugins.md). + +GitHub IntelliJ Platform Plugin Template +: Create new plugins with a preconfigured project scaffold and CI in [one click](github_template.md). + +Disposer & Disposable +: Added [reference](disposers.md) discussing resource cleanup/management. + +### May-20 + +Settings (Preferences) +: Added [guide](settings_guide.md) and [tutorial](settings_tutorial.md) on integrating with IDE Settings dialog. + +UI Inspector +: Inspect Swing components and associated data (like `AnAction` for menu item) using [UI Inspector](internal_ui_inspector.md). + +### March-20 + +JCEF Support (_Experimental Feature_) +: Allows [embedding](jcef.md) Chromium-based browser in the IDE. + +### February-20 + +All Code Samples converted to Gradle +: [All samples](https://github.com/JetBrains/intellij-sdk-docs/tree/master/code_samples) now use the [recommended solution](gradle_build_system.md) of setting up plugin projects. + +### January-20 + +Custom Language Support Tutorial converted to Gradle +: The [corresponding tutorial](custom_language_support_tutorial.md) and [Testing a Custom Language Plugin](writing_tests_for_plugins.md) have been updated and enhanced as well. + +Targeting specific IDEs +: [Part VIII - Product Specific](plugin_compatibility.md) has been expanded massively, now also covering each IDE with its own dedicated page. + +## 2019 + +### December-19 + +Dynamic Plugins support +: Added starting point [Dynamic Plugins](dynamic_plugins.md) for migrating plugins (IntelliJ Platform 2020.1 and later). + +Plugin Components migration +: Components being a legacy feature, the [updated page](plugin_components.md) describes migrating them to modern replacement API. + +### October-19 + +Part X - Plugin Repository moved +: All contents have been moved to [JetBrains Marketplace](https://plugins.jetbrains.com/docs/marketplace/about-marketplace.html) documentation. + +### July-19 + +New page: Optimizing Performance +: [How to improve performance](performance.md) working with PSI, indexing, and avoiding UI freezes. + +### May-19 + +New Page: Kotlin UI DSL +: [Describes preferred way](kotlin_ui_dsl.md) of building UI/dialogs for IntelliJ Platform 2019.2 and later. \ No newline at end of file diff --git a/intro/getting_help.md b/topics/intro/getting_help.md similarity index 84% rename from intro/getting_help.md rename to topics/intro/getting_help.md index 1a17a7501..feabd0bf7 100644 --- a/intro/getting_help.md +++ b/topics/intro/getting_help.md @@ -1,6 +1,5 @@ ---- -title: Getting Help ---- +[//]: # (title: Getting Help) + ## Problems with the Guide @@ -10,7 +9,9 @@ If the problem is easily solved, you can also submit a [Pull Request on GitHub]( If you just want to share feedback on the guide, again, [raise an issue](https://youtrack.jetbrains.com/newIssue?project=IJSDK&clearDraft=true&c=), even if it’s for a discussion, ideas on improvements or suggestions. -> **NOTE** Please don't use the **IJSDK** YouTrack project for plugin or product support requests - it's intended for the SDK and the documentation, and you'll get a better response using one of the methods below. + > Please don't use the **IJSDK** YouTrack project for plugin or product support requests - it's intended for the SDK and the documentation, and you'll get a better response using one of the methods below. + > + {type="note"} ## Problems with Code - Support Issues @@ -24,4 +25,4 @@ Of course, all issues will be used to try and improve this guide. ## Problems with Products -If you have a problem with an IntelliJ Platform-based product, such as IntelliJ IDEA, WebStorm, Rider, etc., please raise an issue on [YouTrack](https://youtrack.jetbrains.com), assigning it to the correct project for the product. +If you have a problem with an IntelliJ Platform-based product, such as IntelliJ IDEA, WebStorm, Rider, etc., please raise an issue on [YouTrack](https://youtrack.jetbrains.com), assigning it to the correct project for the product. \ No newline at end of file diff --git a/intro/intellij_platform.md b/topics/intro/intellij_platform.md similarity index 94% rename from intro/intellij_platform.md rename to topics/intro/intellij_platform.md index b9e4f48f5..605ec55b3 100644 --- a/intro/intellij_platform.md +++ b/topics/intro/intellij_platform.md @@ -1,6 +1,5 @@ ---- -title: What is the IntelliJ Platform? ---- +[//]: # (title: What is the IntelliJ Platform?) + The _IntelliJ Platform_ is not a product in and of itself but provides a platform for building IDEs. @@ -22,7 +21,6 @@ PSI powers a lot of functionality, from quick navigating to files, types, and sy The IntelliJ Platform includes parsers and a PSI model for many languages, and its extensible nature means that it is possible to add support for other languages. - ## Plugins Products built on the IntelliJ Platform are extensible applications, with the platform being responsible for creating components and the injection of dependencies into classes. @@ -31,7 +29,7 @@ It is also possible to host your repositories and distribute plugins separately. Plugins can extend the platform in many ways, from adding a simple menu item to adding support for a complete language, build system, and debugger. Many of the existing functionality in the IntelliJ Platform is written as plugins that can be included or excluded depending on the needs of the end product. -See the [Quick Start Guide](/basics/basics.md) for more details. +See the [Quick Start Guide](basics.md) for more details. The IntelliJ Platform is a JVM application, written mostly in Java and Kotlin. You should be experienced with these languages, large libraries written in them, their associated tooling, and large open-source projects to write plugins for products based on the IntelliJ Platform. @@ -46,7 +44,7 @@ Instead, the platform is considered to be an almost complete overlap with the In The version of the IntelliJ Platform is defined by the version of the corresponding release of IntelliJ IDEA Community Edition. For example, to build a plugin against IntelliJ IDEA (2019.1.1), build #191.6707.61 means specifying the same build number tag to get the correct Intellij Platform files from the `intellij-community` repository. -See the [build number ranges](/basics/getting_started/build_number_ranges.md) page for more information about build numbers corresponding to version numbering. +See the [build number ranges](build_number_ranges.md) page for more information about build numbers corresponding to version numbering. Typically, an IDE that is based on the IntelliJ Platform will include the `intellij-community` repository as a Git submodule and provide configuration to describe which plugins from the `intellij-community`, and which custom plugins will make up the product. This is how the IDEA Ultimate team works, and they contribute code to both the custom plugins and the IntelliJ Platform itself. @@ -57,7 +55,9 @@ IntelliJ IDEA Ultimate is a superset of the IntelliJ IDEA Community Edition but Similarly, other products such as WebStorm and DataGrip are based on the IntelliJ IDEA Community Edition, but with a different set of plugins included and excluding other default plugins. This allows plugins to target multiple products, as each product will include base functionality and a selection of plugins from the IntelliJ IDEA Community Edition repository. -> **TIP** Qualifying Open Source projects can [apply for free licenses](https://www.jetbrains.com/community/opensource/) of JetBrains products. + > Qualifying Open Source projects can [apply for free licenses](https://www.jetbrains.com/community/opensource/) of JetBrains products. + > + {type="tip"} The following IDEs are based on the IntelliJ Platform: * JetBrains IDEs @@ -88,4 +88,4 @@ This means that creating a plugin for Rider involves two parts - a plugin that l Fortunately, many plugins can simply work with the ReSharper backend. The Rider takes care of displaying the results of inspections and code completion, and many plugins can be written that don't require an IntelliJ UI component. -More details can be found in the *Part VIII - Product Specific* section. +More details can be found in the *Part VIII - Product Specific* section. \ No newline at end of file diff --git a/intro/key_topics.md b/topics/intro/key_topics.md similarity index 51% rename from intro/key_topics.md rename to topics/intro/key_topics.md index bc0590e57..ef1d9a91c 100644 --- a/intro/key_topics.md +++ b/topics/intro/key_topics.md @@ -1,6 +1,5 @@ ---- -title: Key Topics ---- +[//]: # (title: Key Topics) + The _IntelliJ Platform_ is extensive and very capable, and its size and scope can initially be very daunting. @@ -8,17 +7,17 @@ This page is intended to list the key topics that a plugin author would be inter ## Essential Concepts -- [Creating Your First Plugin](/basics/getting_started.md). -- [Testing plugins](/basics/testing_plugins/testing_plugins.md). +- [Creating Your First Plugin](getting_started.md). +- [Testing plugins](testing_plugins.md). - Component model - the _IntelliJ Platform_ is a component-based application and is responsible for creating components and injecting dependencies. Understanding this is necessary for building plugins. -- [Extension points](/basics/plugin_structure/plugin_extensions.md) - how to register components with extension points, and how to find out what extension points are available. -- [Virtual files](/basics/architectural_overview/virtual_file.md) - all file access should go through the Virtual File System, which abstracts and caches the file system. +- [Extension points](plugin_extensions.md) - how to register components with extension points, and how to find out what extension points are available. +- [Virtual files](virtual_file.md) - all file access should go through the Virtual File System, which abstracts and caches the file system. It means you can work with files that are on the local file system, in a zip file or are old versions from version control. ## Code Model -The _IntelliJ Platform_'s code model is called the PSI - the [Program Structure Interface](/basics/architectural_overview/psi.md). +The _IntelliJ Platform_'s code model is called the PSI - the [Program Structure Interface](psi.md). The PSI parses code, builds indexes, and creates a semantic model. ## Common Extension Points @@ -26,7 +25,7 @@ The PSI parses code, builds indexes, and creates a semantic model. The _IntelliJ Platform_ is extremely exceptionally, and most features and services can be extended. Some of the common extension points are: -* [Actions](/tutorials/action_system.md) - menu and toolbar items -* [Code inspections](/tutorials/code_inspections.md) - code analysis that looks at the syntax trees and semantic models and highlight issues in the editor. -* [Intentions](/tutorials/code_intentions.md) - context-specific actions that are available in the Alt+Enter menu when the text caret is at a particular location. -* [Code completion](/reference_guide/custom_language_support/code_completion.md). +* [Actions](action_system.md) - menu and toolbar items +* [Code inspections](code_inspections.md) - code analysis that looks at the syntax trees and semantic models and highlight issues in the editor. +* [Intentions](code_intentions.md) - context-specific actions that are available in the Alt+Enter menu when the text caret is at a particular location. +* [Code completion](code_completion.md). \ No newline at end of file diff --git a/intro/sdk_code_guidelines.md b/topics/intro/sdk_code_guidelines.md similarity index 87% rename from intro/sdk_code_guidelines.md rename to topics/intro/sdk_code_guidelines.md index 440181437..3c36d8e52 100644 --- a/intro/sdk_code_guidelines.md +++ b/topics/intro/sdk_code_guidelines.md @@ -1,14 +1,10 @@ ---- -title: Guidelines for Creating IntelliJ Platform SDK Code Samples ---- +[//]: # (title: Guidelines for Creating IntelliJ Platform SDK Code Samples) + This document describes the coding guidelines used for authoring open-source IntelliJ Platform SDK code samples. -Before you begin, please read this page thoroughly, as well as the [Code of Conduct](/CODE_OF_CONDUCT.md) and [License](https://github.com/JetBrains/intellij-sdk-docs/blob/master/LICENSE.txt) documents. -For information about contributing to the IntelliJ Platform itself, visit [Contributing to the IntelliJ Platform](/basics/platform_contributions.md). - - * Dummy list item - {:toc} +Before you begin, please read this page thoroughly, as well as the [Code of Conduct](intellij-sdk-docs-original_CODE_OF_CONDUCT.md) and [License](https://github.com/JetBrains/intellij-sdk-docs/blob/master/LICENSE.txt) documents. +For information about contributing to the IntelliJ Platform itself, visit [Contributing to the IntelliJ Platform](platform_contributions.md). ## Objectives Keep the following considerations in mind while authoring an SDK code sample: @@ -40,8 +36,10 @@ Use the standard intellij-community copyright notice in all sample plugins autho Copyright 2000-2020 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file." ``` -> **NOTE** The copyright statement must appear at the top of every source file. + > The copyright statement must appear at the top of every source file. > Use the [IntelliJ Platform SDK](https://github.com/JetBrains/intellij-sdk-docs/tree/master/.idea/copyright) copyright profile. + > + {type="note"} ## Directory Naming Conventions for SDK Plugins For _basic_ samples, the plugin directory name is derived from the IntelliJ Platform extension points demonstrated. @@ -59,7 +57,7 @@ Instead, concatenate a long name into camelCase such as `maxOpenedProjects` ## Group and Artifact ID When creating a Gradle-based IntelliJ Platform plugin, the plugin's Maven coordinates (`Group ID`, `Artifact ID`, `Version`) are defined. -The `Group ID` for the SDK plugins is always `org.intellij.sdk`. +The `Group ID` for SDK plugins is always `org.intellij.sdk`. The `Artifact ID` is a brief derivative of the plugin directory name. An `Artifact ID` should not contain symbols. @@ -118,17 +116,17 @@ code_samples/ ``` ## build.gradle Conventions -New SDK code samples should be developed [using Gradle](/tutorials/build_system.md). +New SDK code samples should be developed [using Gradle](gradle_build_system.md). As of this writing, the use of Gradle in SDK code samples still relies heavily on the `plugin.xml` for specifying the plugin configuration. At a later, second phase, the SDK code samples will transition to rely more on the Gradle configuration. -The default contents of a `build.gradle` file are produced by the [New Project Wizard](/tutorials/build_system/prerequisites.md#creating-a-gradle-based-intellij-platform-plugin-with-new-project-wizard). +The default contents of a `build.gradle` file are produced by the [New Project Wizard](gradle_prerequisites.md#creating-a-gradle-based-intellij-platform-plugin-with-new-project-wizard). A consistent structure for an SDK code sample's `build.gradle` file is essential for clarity and is based on the default produced by the project wizard. Comments in SDK code sample `build.gradle` files should only draw attention to the parts of the Gradle configuration that are unique for a plugin. For SDK code samples, a few alterations are needed to the default `build.gradle` file produced by the plugin wizard: * Maintain the Gradle properties `version` (`project.version`) and `group` (`project.group`). - See the [Plugin Gradle Properties](/tutorials/build_system/prerequisites.md#plugin-gradle-properties-and-plugin-configuration-file-elements) section for how these Gradle properties relate to the elements in `plugin.xml`. + See the [Plugin Gradle Properties](gradle_prerequisites.md#plugin-gradle-properties-and-plugin-configuration-file-elements) section for how these Gradle properties relate to the elements in `plugin.xml`. * Add the following statement to the [Setup DSL](https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md#setup-dsl) (`intellij{}`) section: ```groovy // Prevents patching attributes in plugin.xml @@ -141,7 +139,7 @@ For SDK code samples, a few alterations are needed to the default `build.gradle` ``` ## plugin.xml Conventions -A consistent structure for the [`plugin.xml`](/basics/plugin_structure/plugin_configuration_file.md) configuration file of an SDK code sample is important because we want to draw attention to the unique parts of the file for a plugin. +A consistent structure for the [`plugin.xml`](plugin_configuration_file.md) configuration file of an SDK code sample is important because we want to draw attention to the unique parts of the file for a plugin. Comment profusely about unique elements and configurations, and comment sparingly for the rest. The sequence of elements in an SDK code sample `plugin.xml` file is: @@ -160,7 +158,7 @@ The sequence of elements in an SDK code sample `plugin.xml` file is: SDK code samples are reviewed before every major release (20XX.1) to ensure compatibility with the latest IntelliJ Platform. Add this attribute if a plugin sample is deprecated with a release of the IntelliJ Platform. * `` Include at least one dependency with the module `com.intellij.modules.platform` to indicate basic plugin compatibility with IntelliJ Platform-based products. - Add `` elements containing module FQNs as needed to describe more specialized [Compatibility with Multiple Products](/basics/getting_started/plugin_compatibility.md), and any other [Plugin Dependencies](/basics/plugin_structure/plugin_dependencies.md). + Add `` elements containing module FQNs as needed to describe more specialized [Compatibility with Multiple Products](plugin_compatibility.md), and any other [Plugin Dependencies](plugin_dependencies.md). * `` is a concise explanation of what is being demonstrated and how a user would access the functionality. If the plugin by default overrides IDE behavior (such as `tree_structure_provider`) it must be noted in the description. * `` is an ordered list by version numbers with a brief description of changes for each version. @@ -168,7 +166,7 @@ The sequence of elements in an SDK code sample `plugin.xml` file is: Set the attributes: * `email` omit this attribute. * `url` to the JetBrains Plugins Repository `"https://plugins.jetbrains.com"` -* The remainder of the [plugin configuration elements](/basics/plugin_structure/plugin_configuration_file.md) should only appear a specific plugin needs them. +* The remainder of the [plugin configuration elements](plugin_configuration_file.md) should only appear if they are needed by a specific plugin. ## Testing IntelliJ Platform SDK code samples should be built and tested against the `since-build` version. @@ -181,4 +179,4 @@ Here the term "IDE" means the IntelliJ Platform-based IDE in which the plugin is * The correct information about the plugin should display in the **Preferences \| Plugins** panel. * If applicable, the plugin UI, such as tool windows, menu additions, etc. should display correctly. * The functionality of the plugin should be tested with a sample file. -* If applicable, the plugin should pass unit tests. +* If applicable, the plugin should pass unit tests. \ No newline at end of file diff --git a/intro/sdk_style.md b/topics/intro/sdk_style.md similarity index 73% rename from intro/sdk_style.md rename to topics/intro/sdk_style.md index 30aeb6bbb..117da2230 100644 --- a/intro/sdk_style.md +++ b/topics/intro/sdk_style.md @@ -1,21 +1,16 @@ ---- -title: Style Guide for SDK Documents ---- +[//]: # (title: Style Guide for SDK Documents) + This document describes the writing style used in authoring open-source IntelliJ Platform SDK documentation. -Before you begin, please read this page thoroughly, as well as the [Code of Conduct](/CODE_OF_CONDUCT.md) and [License](https://github.com/JetBrains/intellij-sdk-docs/blob/master/LICENSE.txt) documents. -For information about contributing to the IntelliJ Platform itself, please visit [Contributing to the IntelliJ Platform](/basics/platform_contributions.md). +Before you begin, please read this page thoroughly, as well as the [Code of Conduct](intellij-sdk-docs-original_CODE_OF_CONDUCT.md) and [License](https://github.com/JetBrains/intellij-sdk-docs/blob/master/LICENSE.txt) documents. +For information about contributing to the IntelliJ Platform itself, please visit [Contributing to the IntelliJ Platform](platform_contributions.md). First and foremost, we should keep in mind our audience and their objectives: _Someone reading technical content is usually looking to answer a specific question. That question might be broad or narrowly-focused, but either way, our goal is to provide answers without distraction._ The style of the _Intellij Platform SDK_ documentation is captured by using a markup language named [_Markdown_](https://github.github.com/gfm/). -The following sections describe the SDK documentation style in terms of the Markdown formats: - -* bullet list -{:toc} ## Documentation Markup By default, when building the site, all files are copied to the destination `_site` folder. @@ -34,44 +29,11 @@ If the Markdown file doesn't contain a header, it won't be converted. In other words, to convert a `.md` file to HTML, it should look like this: ```yaml ---- ---- +[//]: # (title: Style Guide for SDK Documents) -Lorem ipsum... -``` - -The two lines at the top of the file are the markers of the YAML _front matter_. -Fields can be added in between these markers, and are used when generating the HTML. -Typically, this header is empty, although it is required by Jekyll (if omitted, the file isn't converted). - -The YAML header can contain data that is used when generating the site. -For example, the page title can be specified as a simple piece of Markdown - `# Title`, or it can be specified in the YAML, and the page template displays it appropriately: - -> **NOTE** The page copyright notice should appear immediately below the YAML header, as shown below. -> Use the [IntelliJ Platform SDK](https://github.com/JetBrains/intellij-sdk-docs/tree/master/.idea/copyright) copyright profile. - -```yaml ---- title: The Title Of The Page ---- - +[//]: # (title: Style Guide for SDK Documents) -Lorem ipsum... -``` - -The YAML header can also include [redirect](#redirects) information. - -Line spacing around headings in Markdown files generally doesn't affect the HTML conversion, but it does make Markdown pages more readable for authors: -* No space between a heading and the first content below it. -* One space before a heading if it is the same level or a sub-heading of the previous section. -* Two spaces before a heading that is higher-level than the heading of the previous section. - -### Redirects -The documentation site is set up to include the [jekyll-redirect-from](https://github.com/jekyll/jekyll-redirect-from) plugin, which generates "dummy" pages that automatically redirect to a given page. -For example, to specify that the `index.html` page be generated to redirect to `README.md`, the `README.md` file should include the following in the YAML header: - -```yaml ---- redirect_from: - /index.html --- @@ -85,19 +47,9 @@ Redirects enable the site URL to show the `README.html` file automatically - `ht It is also useful to redirect when renaming or moving files. Multiple redirects can be added to the YAML header. -> **NOTE** Please update all existing internal links to the new page location. - -### Table of Contents for a Page -The site is configured to use the [Kramdown Markdown converter](https://kramdown.gettalong.org), which adds some extra features over traditional Markdown. -For example, "attribute lists" that can apply attributes to the generated elements. - -One useful attribute is `{:toc}`, which can be applied to a list item, which will get replaced with a list of links to header items. -E.g., the following list item will be replaced by links to all of the header items in the page: - -```md - * Dummy list item - {:toc} -``` + > Please update all existing internal links to the new page location. + > + {type="note"} ## Content Style Further Kramdown features are described on the [converter page](https://kramdown.gettalong.org/converter/html.html), and attribute lists are described on the [syntax page](https://kramdown.gettalong.org/syntax.html). @@ -133,28 +85,28 @@ For example, `## Introduction` gets the ID of `introduction`, and can be linked #### General Links General Markdown links have the default Markdown link style: -* `[Gradle](https://gradle.org)` ([Gradle](https://gradle.org)) links to an external site, such as companies, articles, etc. +* `[Gradle](https://gradle.org)`{disable-links} ([Gradle](https://gradle.org)) links to an external site, such as companies, articles, etc. * Linking to pages within the SDK documentation: - * `[SDK doc page in current directory](Page2.md)` links to an SDK doc page in the same directory as the current page. + * `[SDK doc page in current directory]()`{disable-links} links to an SDK doc page in the same directory as the current page. Note that the extension is `.md`, _NOT_ `.html`. - * `[SDK page in another folder](/Folder2/Page2.md)` links to a page in another folder. + * `[SDK page in another folder](Page2.md)`{disable-links} links to a page in another folder. Note the URL is navigating from the project root. This format works even if the site is hosted in a sub-folder. Relative links also work (`../Folder2/Page2.md`). * Linking to specific _sections_ on pages in the SDK documentation. The anchor name will be all lower case, and spaces are replaced with `-`, e.g. `## Page setup` becomes `#page-setup`. Once the anchor (`#`) character of the link is entered, the IDE code completion feature shows the available sections. - * `[Link to a section on the current page](#another-section)` links to a heading on the current page. - * `[Link to the section on another page](Page2.md#another-section)` links to a heading on another page. + * `[Link to a section on the current page](#another-section)`{disable-links} links to a heading on the current page. + * `[Link to the section on another page](#another-section)`{disable-links} links to a heading on another page. #### Links to IntelliJ Platform Source Links to files in the IntelliJ Platform (`intellij-community`) repository use `upsource:///` instead of the full URL to the repository. The `upsource:///` URI effectively points to the root of the `intellij-community` repository. -* `[_README.md_](upsource:///README.md)` links to general, non-code information files, use _italic_ style. ([_README.md_](upsource:///README.md)) +* `[_README.md_](upsource:///README.md)`{disable-links} links to general, non-code information files, use _italic_ style. ([_README.md_](upsource:///README.md)) Examples of this file type include _LICENSE.txt_ and _README.md_. -* `[`\`plugin.xml\``](upsource:///platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java)` links to declarative source code files, use `code` style. ([`plugin.xml`](upsource:///platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java)) +* `[`\`plugin.xml\``](upsource:///platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java)`{disable-links} links to declarative source code files, use `code` style. ([`plugin.xml`](upsource:///platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java)) Examples of this file type include: `settings.gradle`, `plugin.xml` or `theme_basics.theme.json`. -* `[`\`AnAction\``](upsource:///platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java)` links to source files for code objects like interfaces and classes, use `code` style but without the file extension. [`AnAction`](upsource:///platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java) +* `[`\`AnAction\``](upsource:///platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java)`{disable-links} links to source files for code objects like interfaces and classes, use `code` style but without the file extension. [`AnAction`](upsource:///platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java) Examples of this file type includeJava and Kotlin. * Note the use of \`\` characters surrounding the class name in the link. * When linking to an API in this manner, the FQN isn't necessary in the link. @@ -195,7 +147,9 @@ Source code is represented by using [GitHub Flavoured Markdown](https://help.git Here is the list of [supported languages](https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers), and also [Kotlin](https://kotlinlang.org), of course. -> **NOTE** Source code blocks must have one blank line before and after them, and must have a language specification for highlighting. + > Source code blocks must have one blank line before and after them, and must have a language specification for highlighting. + > + {type="note"} Whole files can be imported on a page using an include statement within code fences. Search the documentation for `% include` to get the correct include statement syntax. @@ -208,7 +162,6 @@ The advantage is the code can come from the `code_samples` directory, so it will The disadvantage is the file may contain a large class, too large for the documentation page to be useful. In any case, please keep code samples concise and avoid any unnecessary "surrounding" code or import statements. - -[![official JetBrains project](https://jb.gg/badges/official-flat-square.svg)](https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub) -[![Twitter Follow](https://img.shields.io/twitter/follow/JBPlatform?style=flat-square)](https://twitter.com/JBPlatform/) -[![Slack](https://img.shields.io/badge/Slack-%23intellij--platform-blue)](https://plugins.jetbrains.com/slack) +[![official JetBrains project](https://jb.gg/badges/official-flat-square.svg)](https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub) [![Twitter Follow](https://img.shields.io/twitter/follow/JBPlatform?style=flat-square)](https://twitter.com/JBPlatform/) [![Slack](https://img.shields.io/badge/Slack-%23intellij--platform-blue)](https://plugins.jetbrains.com/slack) Welcome to the _IntelliJ Platform_ SDK - the primary source of documentation for extending the _IntelliJ Platform_ by creating plugins, custom language support, or building a custom IDE. @@ -20,26 +14,28 @@ Watch [Busy plugin developers series. Episode 0](https://www.youtube.com/watch?v * [**About this Guide**](about.md) * [**Key Topics**](key_topics.md) * [**Getting Help**](getting_help.md) -* [**Creating Your First Plugin**](/basics/getting_started.md) -* [**Useful Links**](/appendix/resources/useful_links.md) -* [**Marketing**](/appendix/resources/marketing.md) +* [**Creating Your First Plugin**](getting_started.md) +* [**Useful Links**](useful_links.md) +* [**Marketing**](marketing.md) ## Updates See [Content Updates](content_updates.md) for the latest changes. Follow [JBPlatform](https://twitter.com/JBPlatform/) on Twitter and visit [JetBrains Platform Blog](https://blog.jetbrains.com/platform/) for the latest announcements. -Are you upgrading your plugin to the latest platform release? Make sure to check [Incompatible Changes](/reference_guide/api_changes_list.md) as well as [Notable Changes and Features](/reference_guide/api_notable/api_notable.md). +Are you upgrading your plugin to the latest platform release? Make sure to check [Incompatible Changes](api_changes_list.md) as well as [Notable Changes and Features](api_notable.md). -[Dynamic Plugins](/basics/plugin_structure/dynamic_plugins.md) are available in 2020.1. +[Dynamic Plugins](dynamic_plugins.md) are available in 2020.1. We've also published our roadmap for the IntelliJ Platform for 2020: [Part I](https://blog.jetbrains.com/idea/2019/12/intellij-platform-roadmap-for-2020/) [Part II](https://blog.jetbrains.com/idea/2020/01/intellij-based-ide-features-roadmap-for-2020/) -> **NOTE** If your plugin depends on Java functionality and targets 2019.2 or later, please make sure to follow the steps from this [blog post](https://blog.jetbrains.com/platform/2019/06/java-functionality-extracted-as-a-plugin/). + > If your plugin depends on Java functionality and targets 2019.2 or later, please make sure to follow the steps from this [blog post](https://blog.jetbrains.com/platform/2019/06/java-functionality-extracted-as-a-plugin/). + > + {type="note"} ## Open Source This guide is Open Source and licensed under Apache 2.0. The source (as Markdown) is [hosted on GitHub](https://github.com/JetBrains/intellij-sdk-docs). -Please see [CONTRIBUTING.md](/CONTRIBUTING.md) for details on hosting the docs locally and contributing. +Please see [CONTRIBUTING.md](intellij-sdk-docs-original_CONTRIBUTING.md) for details on hosting the docs locally and contributing. -Please see [Getting Help](getting_help.md) if you encounter bugs in this guide or require help with missing content. +Please see [Getting Help](getting_help.md) if you encounter bugs in this guide or require help with missing content. \ No newline at end of file diff --git a/platform/fundamentals.md b/topics/platform/fundamentals.md similarity index 52% rename from platform/fundamentals.md rename to topics/platform/fundamentals.md index 36bf3b98d..8b8ab20f2 100644 --- a/platform/fundamentals.md +++ b/topics/platform/fundamentals.md @@ -1,14 +1,10 @@ ---- -title: Fundamentals -redirect_from: - - /reference_guide.html - - /basics/architectural_overview.html ---- +[//]: # (title: Fundamentals) + This section describes the low-level fundamental building blocks of the _IntelliJ Platform_: * The component model - how the application is hosted and composed. Lifetime and dependency management. -* [Disposers](/basics/disposers.md) - managing object lifetimes and resource cleanup -* [Threading models](/basics/architectural_overview/general_threading_rules.md) -* [Messaging](/reference_guide/messaging_infrastructure.md) +* [Disposers](disposers.md) - managing object lifetimes and resource cleanup +* [Threading models](general_threading_rules.md) +* [Messaging](messaging_infrastructure.md) \ No newline at end of file diff --git a/products/android_studio.md b/topics/products/android_studio.md similarity index 80% rename from products/android_studio.md rename to topics/products/android_studio.md index 2dfb31c07..fd7be9768 100644 --- a/products/android_studio.md +++ b/topics/products/android_studio.md @@ -1,21 +1,19 @@ ---- -title: Android Studio Plugin Development ---- +[//]: # (title: Android Studio Plugin Development) + ## Introduction Android Studio plugins extend or add functionality to the [Android Studio IDE](https://developer.android.com/studio). -Plugins can be written in Kotlin or Java, or a mix of both, and are created using IntelliJ IDEA and the [IntelliJ Platform](/intro/intellij_platform.md). +Plugins can be written in Kotlin or Java, or a mix of both, and are created using IntelliJ IDEA and the [IntelliJ Platform](intellij_platform.md). It's also helpful to be familiar with [Java Swing](https://docs.oracle.com/javase/8/javase-clienttechnologies.htm). Once completed, plugins can be packaged and distributed at [JetBrains Plugin Repository](https://plugins.jetbrains.com). Android Studio plugins are not Android modules or apps to run in the Android operating system, such as smartphones or tablets. ## Configuring IntelliJ Platform Projects for Android Studio Plugin Development -To create a new Android Studio plugin project, follow the tutorial on the [Getting Started with Gradle](/tutorials/build_system/prerequisites.md) page. +To create a new Android Studio plugin project, follow the tutorial on the [Getting Started with Gradle](gradle_prerequisites.md) page. The tutorial produces a skeleton project suitable to use as a starting point for an Android Studio plugin. -On the [New Project Configuration Screen](/tutorials/build_system/prerequisites.md#new-project-configuration-screen) of the New Project Wizard tutorial, choose Gradle from the product category pane as described in the tutorial, **not** _Android_. - +On the [New Project Configuration Screen](gradle_prerequisites.md#new-project-configuration-screen) of the New Project Wizard tutorial, choose Gradle from the product category pane as described in the tutorial, **not** _Android_. Some minor modifications to the skeleton project are needed, as discussed below. ### Matching Versions of the IntelliJ Platform with the Android Studio Version @@ -27,14 +25,14 @@ An example is shown below. In this case, the (BRANCH.BUILD.FIX) version of the IntelliJ Platform is `191.8026.42`, which corresponds to the IntelliJ IDEA version 2019.1.4. The [`build.gradle` configuration steps](#configuring-the-plugin-buildgradle-file) section below explains how to set the IntelliJ Platform version to match the target version of Android Studio. -![Example Android Studio About Dialog](img/android_studio_build.png){:width="600px"} +![Example Android Studio About Dialog](android_studio_build.png){width="600"} ### Configuring the Plugin build.gradle File -The use-case of developing for a non-IntelliJ IDEA IDE is reviewed in the [Plugins Targeting Alternate IntelliJ Platform-Based IDEs](/tutorials/build_system/gradle_guide.md#plugins-targeting-alternate-intellij-platform-based-ides) section of the [Configuring Gradle for IntelliJ Platform Plugins](/tutorials/build_system/gradle_guide.md) page. +The use-case of developing for a non-IntelliJ IDEA IDE is reviewed in the [Plugins Targeting Alternate IntelliJ Platform-Based IDEs](gradle_guide.md#plugins-targeting-alternate-intellij-platform-based-ides) section of the [Configuring Gradle for IntelliJ Platform Plugins](gradle_guide.md) page. The particular example in that section discusses configuring a plugin project for PhpStorm, so the details for an Android Studio plugin project are reviewed here. Here are the steps to configure the `build.gradle` file for developing a plugin to target Android Studio: -* The Gradle plugin attributes describing the configuration of the [IntelliJ Platform used to build the plugin project](/tutorials/build_system/gradle_guide.md#configuring-the-gradle-plugin-for-building-intellij-platform-plugin-projects) must be explicitly set. +* The Gradle plugin attributes describing the configuration of the [IntelliJ Platform used to build the plugin project](gradle_guide.md#configuring-the-gradle-plugin-for-building-intellij-platform-plugin-projects) must be explicitly set. Continuing with the example [above](#matching-versions-of-the-intellij-platform-with-the-android-studio-version), set the `intellij.version` value to `191.8026.42`. Alternatively, specify `intellij.localPath` to refer to a local installation of Android Studio. * Android Studio plugin projects that use APIs from the `android` plugin must declare a dependency on that plugin. @@ -67,9 +65,9 @@ When using APIs from the `android` plugin, declare a dependency: org.jetbrains.android ``` -As discussed in the [Plugin Dependencies](/basics/getting_started/plugin_compatibility.md#declaring-plugin-dependencies) section of this guide, a plugin's dependency on [Modules Specific to Functionality](/basics/getting_started/plugin_compatibility.md#modules-specific-to-functionality) must be declared in `plugin.xml`. +As discussed in the [Plugin Dependencies](plugin_compatibility.md#declaring-plugin-dependencies) section of this guide, a plugin's dependency on [Modules Specific to Functionality](plugin_compatibility.md#modules-specific-to-functionality) must be declared in `plugin.xml`. When using Android Studio-specific features (APIs), a dependency on `com.intellij.modules.androidstudio` must be declared as shown in the code snippet below. -Otherwise, if only general IntelliJ Platform features (APIs) are used, then a dependency on `com.intellij.modules.platform` must be declared as discussed in [Plugin Compatibility with IntelliJ Platform Products](/basics/getting_started/plugin_compatibility.md). +Otherwise, if only general IntelliJ Platform features (APIs) are used, then a dependency on `com.intellij.modules.platform` must be declared as discussed in [Plugin Compatibility with IntelliJ Platform Products](plugin_compatibility.md). ```xml com.intellij.modules.androidstudio @@ -90,4 +88,4 @@ When learning new development configurations, it is helpful to have some represe ## FAQ ### How To Sync Gradle Project -Use `com.android.tools.idea.gradle.project.sync.GradleSyncInvoker.requestProjectSync()` for programmatic synchronization. +Use `com.android.tools.idea.gradle.project.sync.GradleSyncInvoker.requestProjectSync()` for programmatic synchronization. \ No newline at end of file diff --git a/products/app_code.md b/topics/products/app_code.md similarity index 61% rename from products/app_code.md rename to topics/products/app_code.md index 5f1a98810..b110232c3 100644 --- a/products/app_code.md +++ b/topics/products/app_code.md @@ -1,36 +1,41 @@ ---- -title: AppCode Plugin Development ---- +[//]: # (title: AppCode Plugin Development) + ## Introduction Plugin projects targeting [AppCode](https://www.jetbrains.com/objc/) can be developed using IntelliJ IDEA with the `gradle-intellij-plugin`. -> **TIP** Qualifying Open Source projects can [apply for free licenses](https://www.jetbrains.com/community/opensource/) of JetBrains products. + > Qualifying Open Source projects can [apply for free licenses](https://www.jetbrains.com/community/opensource/) of JetBrains products. + > + {type="tip"} ## Configuring Plugin Projects Targeting AppCode -> **WARNING** When targeting 2020.3, please see this [migration guide](https://blog.jetbrains.com/clion/2020/12/migration-guide-for-plugins-2020-3/). + > When targeting 2020.3, please see this [migration guide](https://blog.jetbrains.com/clion/2020/12/migration-guide-for-plugins-2020-3/). + > + {type="warning"} The Gradle configuration of AppCode plugin projects uses neither Product-Specific nor IntelliJ IDEA Attributes. Instead, configure AppCode plugin projects to use the `intellij.localPath` attribute. -> **NOTE** AppCode plugin development requires installing AppCode locally. + > AppCode plugin development requires installing AppCode locally. + > + {type="note"} The table below summarizes the `gradle-intellij-plugin` attributes to set in the plugin project's `build.gradle` file. Click on an entry in the table's *Attribute* column to go to the documentation about that attribute. | `gradle-intellij-plugin` Attribute | Attribute Value | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| [`intellij.localPath`][properties] | Path to locally installed target version of AppCode. For example, for macOS:
`/Users//Library/Application Support/JetBrains/Toolbox/apps/AppCode/ch-0/193.5662.55/AppCode.app/Contents`. | -| [`runIde.ideDirectory`][dsl] | Path to locally installed target version of AppCode. For example, for macOS:
`/Users//Library/Application Support/JetBrains/Toolbox/apps/AppCode/ch-0/193.5662.55/AppCode.app/Contents`. | +| [`intellij.localPath`][properties] | Path to locally installed target version of AppCode. For example, for macOS:
`/Users//Library/Application Support/JetBrains/Toolbox/apps/AppCode/ch-0/193.5662.55/AppCode.app/Contents`. | +| [`runIde.ideDirectory`][dsl] | Path to locally installed target version of AppCode. For example, for macOS:
`/Users//Library/Application Support/JetBrains/Toolbox/apps/AppCode/ch-0/193.5662.55/AppCode.app/Contents`. | [properties]: https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md#intellij-platform-properties [dsl]: https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md#running-dsl The dependency on the AppCode APIs must be declared in the `plugin.xml` file. -As described in [Modules Specific to Functionality](/basics/getting_started/plugin_compatibility.md#modules-specific-to-functionality) table, the `` tags must declare `com.intellij.modules.appcode`. +As described in [Modules Specific to Functionality](plugin_compatibility.md#modules-specific-to-functionality) table, the `` tags must declare `com.intellij.modules.appcode`. ## Available AppCode APIs -Use the [Exploring APIs as a Consumer](/basics/getting_started/plugin_compatibility.md#exploring-apis-as-a-consumer) process to identify the libraries in AppCode. -Test your plugin with any version of AppCode you wish to support. +Use the [Exploring APIs as a Consumer](plugin_compatibility.md#exploring-apis-as-a-consumer) process to identify the libraries in AppCode. +Test your plugin with any version of AppCode you wish to support. \ No newline at end of file diff --git a/products/clion.md b/topics/products/clion.md similarity index 75% rename from products/clion.md rename to topics/products/clion.md index 542028244..705e0edac 100644 --- a/products/clion.md +++ b/topics/products/clion.md @@ -1,17 +1,20 @@ ---- -title: CLion Plugin Development ---- +[//]: # (title: CLion Plugin Development) + ## Introduction [CLion](https://www.jetbrains.com/clion/) is an IntelliJ Platform-based product. Plugin projects for CLion can be developed using IntelliJ IDEA with the `gradle-intellij-plugin`. -> **TIP** Qualifying Open Source projects can [apply for free licenses](https://www.jetbrains.com/community/opensource/) of JetBrains products. + > Qualifying Open Source projects can [apply for free licenses](https://www.jetbrains.com/community/opensource/) of JetBrains products. + > + {type="tip"} ## Configuring Plugin Projects Targeting CLion -> **WARNING** When targeting 2020.3, please see this [migration guide](https://blog.jetbrains.com/clion/2020/12/migration-guide-for-plugins-2020-3/). + > When targeting 2020.3, please see this [migration guide](https://blog.jetbrains.com/clion/2020/12/migration-guide-for-plugins-2020-3/). + > + {type="warning"} The configuration of CLion plugin projects follows the methods described in [Configuring Plugin Projects using a Product-Specific Attribute](dev_alternate_products.md#configuring-plugin-projects-using-a-product-specific-attribute), and [Configuring the plugin.xml File](dev_alternate_products.md#configuring-pluginxml). @@ -30,7 +33,7 @@ Click on an entry in the table's *Attribute* column to go to the documentation a [dsl]: https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md#running-dsl The dependency on the CLion APIs must be declared in the `plugin.xml` file. -As described in [Modules Specific to Functionality](/basics/getting_started/plugin_compatibility.md#modules-specific-to-functionality) table, the `` elements should contain the CLion module, as illustrated in the `plugin.xml` snippet below: +As described in [Modules Specific to Functionality](plugin_compatibility.md#modules-specific-to-functionality) table, the `` elements should contain the CLion module, as illustrated in the `plugin.xml` snippet below: ```xml @@ -38,10 +41,10 @@ As described in [Modules Specific to Functionality](/basics/getting_started/plug ``` ## Available CLion APIs -Use the [Exploring APIs as a Consumer](/basics/getting_started/plugin_compatibility.md#exploring-apis-as-a-consumer) process to identify the JAR files under the External Library `Gradle:com.jetbrains:clion:`. +Use the [Exploring APIs as a Consumer](plugin_compatibility.md#exploring-apis-as-a-consumer) process to identify the JAR files under the External Library `Gradle:com.jetbrains:clion:`. Test your plugin with versions of CLion you intend to support. ## Open Source Plugins for CLion When learning new APIs, it is helpful to have some representative projects for reference: * [C/C++ Coverage](https://github.com/zero9178/C-Cpp-Coverage-for-CLion) -* [C/C++ Single File Execution](https://github.com/corochann/SingleFileExecutionPlugin) +* [C/C++ Single File Execution](https://github.com/corochann/SingleFileExecutionPlugin) \ No newline at end of file diff --git a/products/data_grip.md b/topics/products/data_grip.md similarity index 68% rename from products/data_grip.md rename to topics/products/data_grip.md index 9b6fb70b2..0bd02621d 100644 --- a/products/data_grip.md +++ b/topics/products/data_grip.md @@ -1,30 +1,33 @@ ---- -title: DataGrip Plugin Development ---- +[//]: # (title: DataGrip Plugin Development) + ## Introduction [DataGrip](https://www.jetbrains.com/datagrip/) is an IntelliJ Platform-based product. Plugin projects targeting DataGrip can be developed using IntelliJ IDEA with the `gradle-intellij-plugin`. -> **TIP** Qualifying Open Source projects can [apply for free licenses](https://www.jetbrains.com/community/opensource/) of JetBrains products. + > Qualifying Open Source projects can [apply for free licenses](https://www.jetbrains.com/community/opensource/) of JetBrains products. + > + {type="tip"} ## Configuring Plugin Projects Targeting DataGrip The configuration of DataGrip plugin projects follows the methods described in [Configuring Plugin Projects using the IntelliJ IDEA Product Attribute](dev_alternate_products.md#configuring-plugin-projects-using-the-intellij-idea-product-attribute), and [Configuring the plugin.xml File](dev_alternate_products.md#configuring-pluginxml). -> **NOTE** DataGrip plugin development may require setting an additional Gradle attribute: `runIde.jvmArgs`. See table below. + > DataGrip plugin development may require setting an additional Gradle attribute: `runIde.jvmArgs`. See table below. + > + {type="note"} The table below summarizes the `gradle-intellij-plugin` attributes to set in the plugin project's `build.gradle` file. Click on an entry in the table's *Attribute* column to go to the documentation about that attribute. -To see how these attributes appear in a similar `build.gradle` file for PhpStorm, see [Configuring build.gradle using the IntelliJ IDEA Product Attribute](/products/dev_alternate_products.md#configuring-buildgradle-using-the-intellij-idea-product-attribute). +To see how these attributes appear in a similar `build.gradle` file for PhpStorm, see [Configuring build.gradle using the IntelliJ IDEA Product Attribute](dev_alternate_products.md#configuring-buildgradle-using-the-intellij-idea-product-attribute). | `gradle-intellij-plugin` Attribute | Attribute Value | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`intellij.type`][properties] | `IU` for IntelliJ IDEA Ultimate.
(`IC` is incompatible with the required `DatabaseTools` plugin.) | +| [`intellij.type`][properties] | `IU` for IntelliJ IDEA Ultimate.
(`IC` is incompatible with the required `DatabaseTools` plugin.) | | [`intellij.version`][properties] | `2019.3` Set to the same version as the DataGrip target version, as set by `runIde.ideDirectory`. | | [`intellij.plugins`][properties] | `plugins 'DatabaseTools'` Dependency on the bundled `DatabaseTools` plugin. | -| [`runIde.ideDirectory`][dsl] | Path to locally installed target version of DataGrip. For example, for macOS:
`/Users//Library/Application Support/JetBrains/Toolbox/apps/datagrip/ch-0/193.5233.139/DataGrip.app/Contents`. | -| [`runIde.jvmArgs`][dsl] | `jvmArgs '-Didea.platform.prefix=DataGrip'`
Only required for `gradle-intellij-plugin` 0.4.16 or earlier. | +| [`runIde.ideDirectory`][dsl] | Path to locally installed target version of DataGrip. For example, for macOS:
`/Users//Library/Application Support/JetBrains/Toolbox/apps/datagrip/ch-0/193.5233.139/DataGrip.app/Contents`. | +| [`runIde.jvmArgs`][dsl] | `jvmArgs '-Didea.platform.prefix=DataGrip'`
Only required for `gradle-intellij-plugin` 0.4.16 or earlier. | [properties]: https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md#intellij-platform-properties [dsl]: https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md#running-dsl @@ -35,10 +38,10 @@ It is not required for building plugins and manually installing them in DataGrip Benign, but redundant attribute if used for later versions of the `gradle-intellj-plugin`. The dependency on the DataGrip APIs must be declared in the `plugin.xml` file. -As described in [Modules Specific to Functionality](/basics/getting_started/plugin_compatibility.md#modules-specific-to-functionality) table, the `` tags must declare `com.intellij.database`. +As described in [Modules Specific to Functionality](plugin_compatibility.md#modules-specific-to-functionality) table, the `` tags must declare `com.intellij.database`. **Note** that DataGrip plugins must also declare a dependency on `com.intellij.modules.platform` because `com.intellij.database` is not recognized as a module. -Consequently, without the `com.intellij.modules.platform` declaration the plugin is assumed to be a [legacy plugin](/basics/getting_started/plugin_compatibility.md#declaring-plugin-dependencies) and will not load in DataGrip. +Consequently, without the `com.intellij.modules.platform` declaration the plugin is assumed to be a [legacy plugin](plugin_compatibility.md#declaring-plugin-dependencies) and will not load in DataGrip. ## Available DataGrip APIs -Use the [Exploring APIs as a Consumer](/basics/getting_started/plugin_compatibility.md#exploring-apis-as-a-consumer) process to identify the libraries in `DatabaseTools`. -Test your plugin with any version of DataGrip you wish to support. +Use the [Exploring APIs as a Consumer](plugin_compatibility.md#exploring-apis-as-a-consumer) process to identify the libraries in `DatabaseTools`. +Test your plugin with any version of DataGrip you wish to support. \ No newline at end of file diff --git a/products/dev_alternate_products.md b/topics/products/dev_alternate_products.md similarity index 82% rename from products/dev_alternate_products.md rename to topics/products/dev_alternate_products.md index 94cc27a19..c77d4dcfe 100644 --- a/products/dev_alternate_products.md +++ b/topics/products/dev_alternate_products.md @@ -1,25 +1,23 @@ ---- -title: Plugins Targeting IntelliJ Platform-Based IDEs ---- +[//]: # (title: Plugins Targeting IntelliJ Platform-Based IDEs) + ## Introduction -Plugin projects can target IDEs other than IntelliJ IDEA, as long as the products are based on the [IntelliJ Platform](/intro/intellij_platform.md). +Plugin projects can target IDEs other than IntelliJ IDEA, as long as the products are based on the [IntelliJ Platform](intellij_platform.md). Such plugins are developed much like plugin projects that target IntelliJ IDEA. They can be written in Kotlin or Java, or a mix of both. Once completed, the plugins can be packaged and distributed at [JetBrains Plugin Repository](https://plugins.jetbrains.com). Project configuration attributes common to projects targeting products other than IntelliJ IDEA are described here. Details particular to an IntelliJ Platform-based product are described on the individual product pages in Part VIII. -All of the Gradle configuration attributes described here are discussed in-depth on the [Configuring Gradle for IntelliJ Platform Plugins](/tutorials/build_system/gradle_guide.md) and the `gradle-intellij-plugin` [README](https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md) pages. +All of the Gradle configuration attributes described here are discussed in-depth on the [Configuring Gradle for IntelliJ Platform Plugins](gradle_guide.md) and the `gradle-intellij-plugin` [README](https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md) pages. -> **TIP** Qualifying Open Source projects can [apply for free licenses](https://www.jetbrains.com/community/opensource/) of JetBrains products. - -* bullet list -{:toc} + > Qualifying Open Source projects can [apply for free licenses](https://www.jetbrains.com/community/opensource/) of JetBrains products. + > + {type="tip"} ## Getting Started -To create a new Gradle plugin project, follow the tutorial on the [Getting Started with Gradle](/tutorials/build_system/prerequisites.md) page. +To create a new Gradle plugin project, follow the tutorial on the [Getting Started with Gradle](gradle_prerequisites.md) page. The tutorial produces a skeleton Gradle project suitable to use as a starting point. Modifications are needed to the skeleton project's `build.gradle` and `plugin.xml` files, as described below, and on the individual product pages in Part VIII. @@ -39,7 +37,7 @@ If the `gradle-intellij-plugin` supports a target product directly, there will b Specifying the target as a product-specific `intellij.type` attribute has two advantages: * The APIs available to the plugin will be limited to only what is defined in the target product. (Unless additional plugin dependencies are specified.) -* The default [Development Instance](/basics/ide_development_instance.md) for running the plugin will be the target product. +* The default [Development Instance](ide_development_instance.md) for running the plugin will be the target product. A `build.gradle` snippet setting a plugin project to target PyCharm is shown below. The `gradle-intellij-plugin` will fetch the matching build of PyCharm Professional to define the APIs available, and use that build of PyCharm (and associated JetBrains runtime) as the Development Instance. @@ -63,7 +61,7 @@ Understanding the relationship between build numbers is critical when using this * _targetIDE_ is the (version-specific) IntelliJ Platform-based IDE in which the plugin is intended to run, such as PhpStorm. * _baseIntelliJPlatformVersion_ is the (version-specific) IntelliJ Platform used in the build of the _targetIDE_. The IntelliJ Platform is defined by a specific build of the IntelliJ IDEA Community Edition. - The Gradle plugin attribute [`intellij.version`](/tutorials/build_system/gradle_guide.md#intellij-platform-configuration) is set to be _baseIntelliJPlatformVersion_. + The Gradle plugin attribute [`intellij.version`](gradle_guide.md#intellij-platform-configuration) is set to be _baseIntelliJPlatformVersion_. For API compatibility, the IntelliJ Platform version used in the _targetIDE_ dictates the _baseIntelliJPlatformVersion_ used for developing a plugin. @@ -76,7 +74,7 @@ Next to **Build #** is the BRANCH.BUILD.FIX version of the _targetIDE_. In the example shown below, the (BRANCH.BUILD.FIX) version is `192.7142.41`, and the product version is 2019.2.4. The version of the IntelliJ Platform used to build this product version is BRANCH.BUILD, or `192.7142` -![Example PhpStorm Splash Screen](img/phpstorm_build.png){:width="500px"} +![Example PhpStorm Splash Screen](phpstorm_build.png){width="500"} If the product version isn't clear on the _About_ screen, consult the individual product pages in Part VIII. @@ -94,15 +92,15 @@ This information is used to configure the plugin project's `build.gradle` and `p Configuring a Gradle plugin project for using _baseIntelliJPlatformVersion_ requires changing some of the default settings in the `build.gradle` file. Changes need to be made in two tasks: `intellij {}` and `runIde {}`. -The Gradle plugin attributes describing the configuration of the [IntelliJ Platform used to build the plugin project](/tutorials/build_system/gradle_guide.md#configuring-the-gradle-plugin-for-building-intellij-platform-plugin-projects) must be explicitly set in the `intellij {}` task. +The Gradle plugin attributes describing the configuration of the [IntelliJ Platform used to build the plugin project](gradle_guide.md#configuring-the-gradle-plugin-for-building-intellij-platform-plugin-projects) must be explicitly set in the `intellij {}` task. The `intellij.type` is "IU" because although the IntelliJ IDEA Community Edition defines the IntelliJ Platform, the PHP plugin is only compatible with IntelliJ IDEA Ultimate. The `intellij.version` is _baseIntelliJPlatformVersion_. -Any [dependencies](/tutorials/build_system/gradle_guide.md#plugin-dependencies) on _targetIDE_-specific plugins or modules must be declared in the `intellij {}` task. +Any [dependencies](gradle_guide.md#plugin-dependencies) on _targetIDE_-specific plugins or modules must be declared in the `intellij {}` task. Use the Gradle plugin attribute `intellij.plugins` to declare a dependency. See the specific product pages in Part VIII for the _targetIDE_ plugin or module name. -The best practice is to modify the `runIde {}` task to use a local installation of _targetIDE_ as the [IDE Development Instance](/basics/ide_development_instance.md). +The best practice is to modify the `runIde {}` task to use a local installation of _targetIDE_ as the [IDE Development Instance](ide_development_instance.md). Set the `runIde.ideDirectory` attribute to the (user-specific) absolute path of the _targetIDE_ application. The exact path format varies by operating system. @@ -127,12 +125,14 @@ This snippet is an example for configuring the Setup and Running DSLs in a `buil ``` ## Configuring plugin.xml -As discussed on the [Plugin Dependencies](/basics/getting_started/plugin_compatibility.md#declaring-plugin-dependencies) page of this guide, a plugin's dependency on [Modules Specific to Functionality](/basics/getting_started/plugin_compatibility.md#modules-specific-to-functionality) must be declared in `plugin.xml`. +As discussed on the [Plugin Dependencies](plugin_compatibility.md#declaring-plugin-dependencies) page of this guide, a plugin's dependency on [Modules Specific to Functionality](plugin_compatibility.md#modules-specific-to-functionality) must be declared in `plugin.xml`. When using features (APIs) specific to the target product, a dependency on the target product module must be declared, as shown in the code snippet below. -Otherwise, if only general IntelliJ Platform features (APIs) are used, then a dependency on `com.intellij.modules.platform` must be declared as discussed in [Plugin Compatibility with IntelliJ Platform Products](/basics/getting_started/plugin_compatibility.md). +Otherwise, if only general IntelliJ Platform features (APIs) are used, then a dependency on `com.intellij.modules.platform` must be declared as discussed in [Plugin Compatibility with IntelliJ Platform Products](plugin_compatibility.md). -> **NOTE** In the particular case of a plugin project declaring dependencies only on other plugins, it must also declare a dependency on `com.intellij.modules.platform`. + > In the particular case of a plugin project declaring dependencies only on other plugins, it must also declare a dependency on `com.intellij.modules.platform`. > Otherwise, the plugin project is considered to be legacy and will only load in IntelliJ IDEA. + > + {type="note"} Continuing with the example of developing a plugin for PhpStorm: @@ -140,4 +140,4 @@ Continuing with the example of developing a plugin for PhpStorm: com.jetbrains.php com.intellij.modules.platform -``` +``` \ No newline at end of file diff --git a/products/goland.md b/topics/products/goland.md similarity index 76% rename from products/goland.md rename to topics/products/goland.md index 8e12d7200..5b974f126 100644 --- a/products/goland.md +++ b/topics/products/goland.md @@ -1,27 +1,28 @@ ---- -title: GoLand Plugin Development ---- +[//]: # (title: GoLand Plugin Development) + ## Introduction [GoLand](https://www.jetbrains.com/go/) is an IntelliJ Platform-based product. Plugin projects for GoLand can be developed using IntelliJ IDEA with the `gradle-intellij-plugin`. -> **TIP** Qualifying Open Source projects can [apply for free licenses](https://www.jetbrains.com/community/opensource/) of JetBrains products. + > Qualifying Open Source projects can [apply for free licenses](https://www.jetbrains.com/community/opensource/) of JetBrains products. + > + {type="tip"} ## Configuring Plugin Projects Targeting GoLand The configuration of GoLand plugin projects follows the methods described in [Configuring Plugin Projects using the IntelliJ IDEA Product Attribute](dev_alternate_products.md#configuring-plugin-projects-using-the-intellij-idea-product-attribute), and [Configuring the plugin.xml File](dev_alternate_products.md#configuring-pluginxml). The table below summarizes the `gradle-intellij-plugin` attributes to set in the plugin project's `build.gradle` file. Click on an entry in the table's *Attribute* column to go to the documentation about that attribute. -To see how these attributes appear in a similar `build.gradle` file for PhpStorm, see [Configuring build.gradle using the IntelliJ IDEA Product Attribute](/products/dev_alternate_products.md#configuring-buildgradle-using-the-intellij-idea-product-attribute). +To see how these attributes appear in a similar `build.gradle` file for PhpStorm, see [Configuring build.gradle using the IntelliJ IDEA Product Attribute](dev_alternate_products.md#configuring-buildgradle-using-the-intellij-idea-product-attribute). | `gradle-intellij-plugin` Attribute | Attribute Value | | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`intellij.type`][properties] | `IU` for IntelliJ IDEA Ultimate. The Go plugin isn't compatible with IntelliJ IDEA Community Edition. | | [`intellij.version`][properties] | Set to the same `IU` BRANCH.BUILD as the GoLand target version, e.g. `193.5233.102`. | -| [`intellij.plugins`][properties] | `org.jetbrains.plugins.go:193.5233.102.83` for the Go plugin.
See below for Go plugin version information. | -| [`runIde.ideDirectory`][dsl] | Path to locally installed target version of GoLand. For example, on macOS:
`/Users//Library/Application Support/JetBrains/Toolbox/apps/Goland/ch-0/193.5233.112/GoLand.app/Contents`. | +| [`intellij.plugins`][properties] | `org.jetbrains.plugins.go:193.5233.102.83` for the Go plugin.
See below for Go plugin version information. | +| [`runIde.ideDirectory`][dsl] | Path to locally installed target version of GoLand. For example, on macOS:
`/Users//Library/Application Support/JetBrains/Toolbox/apps/Goland/ch-0/193.5233.112/GoLand.app/Contents`. | [properties]: https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md#intellij-platform-properties [dsl]: https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md#running-dsl @@ -30,7 +31,7 @@ The Go plugin version is explicitly declared because it isn't bundled with Intel Select a [version](https://plugins.jetbrains.com/plugin/9568-go/versions) of the Go plugin compatible with the IntelliJ Idea Ultimate version. The dependency on the Go plugin APIs must be declared in the `plugin.xml` file. -As described in [Modules Specific to Functionality](/basics/getting_started/plugin_compatibility.md#modules-specific-to-functionality) table, the `` tags must declare `com.intellij.modules.go`. +As described in [Modules Specific to Functionality](plugin_compatibility.md#modules-specific-to-functionality) table, the `` tags must declare `com.intellij.modules.go`. The `plugin.xml` file must also declare a dependency on `com.intellij.modules.platform` as explained in [Configuring the plugin.xml File](dev_alternate_products.md#configuring-pluginxml). The dependency declaration is illustrated in the `plugin.xml` snippet below: @@ -42,10 +43,10 @@ The dependency declaration is illustrated in the `plugin.xml` snippet below: ``` ## Available GoLand APIs -Use the [Exploring APIs as a Consumer](/basics/getting_started/plugin_compatibility.md#exploring-apis-as-a-consumer) process to identify the library `intellij-go-.jar`, where `` corresponds to the version of the Go plugin. +Use the [Exploring APIs as a Consumer](plugin_compatibility.md#exploring-apis-as-a-consumer) process to identify the library `intellij-go-.jar`, where `` corresponds to the version of the Go plugin. Test your plugin with any version of GoLand you intend to support. ## Open Source Plugins for GoLand When learning new APIs, it is helpful to have some representative projects for reference: * [Go Method Generator](https://github.com/pkondratev/Intellij-go-method-generator) -* [Go Builder Generator](https://github.com/OddCN/go-builder-generator-idea-plugin) +* [Go Builder Generator](https://github.com/OddCN/go-builder-generator-idea-plugin) \ No newline at end of file diff --git a/topics/products/idea.md b/topics/products/idea.md new file mode 100644 index 000000000..c9040aa02 --- /dev/null +++ b/topics/products/idea.md @@ -0,0 +1,12 @@ +[//]: # (title: IntelliJ IDEA) + + + + > Qualifying Open Source projects can [apply for free licenses](https://www.jetbrains.com/community/opensource/) of JetBrains products. + > + {type="tip"} + +Please see "Java" entry in table [Modules Specific to Functionality](plugin_compatibility.md#modules-specific-to-functionality) on how to use Java specific functionality. + +* [Tomcat Integration](tomcat_integration.md) +* [Spring API](spring_api.md) \ No newline at end of file diff --git a/products/phpstorm/existing_plugins.md b/topics/products/phpstorm/existing_plugins.md similarity index 98% rename from products/phpstorm/existing_plugins.md rename to topics/products/phpstorm/existing_plugins.md index f3cb71395..24b5b8a33 100644 --- a/products/phpstorm/existing_plugins.md +++ b/topics/products/phpstorm/existing_plugins.md @@ -1,8 +1,5 @@ ---- -title: Example PhpStorm Third-Party Plugins -redirect_from: - - /phpstorm/existing_plugins.html ---- +[//]: # (title: Example PhpStorm Third-Party Plugins) + This page lists some example PhpStorm plugins created by third-party developers. @@ -71,4 +68,4 @@ Nette is a family of mature and stand-alone components for PHP that create a fra The PHP Annotations plugin extends PhpStorm to support annotations in PHPDoc blocks. * [PHP Annotations in PhpStorm Plugins Repository](https://plugins.jetbrains.com/plugin/7320-php-annotations) -* [GitHub](https://github.com/Haehnchen/idea-php-annotation-plugin) +* [GitHub](https://github.com/Haehnchen/idea-php-annotation-plugin) \ No newline at end of file diff --git a/products/phpstorm/php_open_api.md b/topics/products/phpstorm/php_open_api.md similarity index 98% rename from products/phpstorm/php_open_api.md rename to topics/products/phpstorm/php_open_api.md index d735f19fc..b419a55ab 100644 --- a/products/phpstorm/php_open_api.md +++ b/topics/products/phpstorm/php_open_api.md @@ -1,8 +1,5 @@ ---- -title: PHP Open API -redirect_from: - - /phpstorm/php_open_api.html ---- +[//]: # (title: PHP Open API) + ## Dependency in `plugin.xml` @@ -49,7 +46,6 @@ public interface PhpTypeProvider4 { @Nullable PhpType getType(PsiElement element); - /** * @param expression to complete - Here you can use index lookups * @param project well so you can reach the PhpIndex based stuff @@ -58,7 +54,6 @@ public interface PhpTypeProvider4 { @Nullable PhpType complete(String expression, Project project); - /** * Here you can extend the signature lookups * @param expression Signature expression to decode. You can use PhpIndex.getBySignature() to look up expression internals. diff --git a/products/phpstorm/php_open_api_breaking_changes.md b/topics/products/phpstorm/php_open_api_breaking_changes.md similarity index 86% rename from products/phpstorm/php_open_api_breaking_changes.md rename to topics/products/phpstorm/php_open_api_breaking_changes.md index f2a7a81e3..6b47129bc 100644 --- a/products/phpstorm/php_open_api_breaking_changes.md +++ b/topics/products/phpstorm/php_open_api_breaking_changes.md @@ -1,6 +1,5 @@ ---- -title: Incompatible PHP OpenAPI Changes in PhpStorm ---- +[//]: # (title: Incompatible PHP OpenAPI Changes in PhpStorm) + The following pages list the breaking changes in IDE releases with required/recommended steps to take by plugin authors. diff --git a/products/phpstorm/php_open_api_breaking_changes_202.md b/topics/products/phpstorm/php_open_api_breaking_changes_202.md similarity index 97% rename from products/phpstorm/php_open_api_breaking_changes_202.md rename to topics/products/phpstorm/php_open_api_breaking_changes_202.md index f082c3dd7..86fa4a972 100644 --- a/products/phpstorm/php_open_api_breaking_changes_202.md +++ b/topics/products/phpstorm/php_open_api_breaking_changes_202.md @@ -1,6 +1,5 @@ ---- -title: Incompatible PHP OpenAPI changes in PhpStorm 2020.2 ---- +[//]: # (title: Incompatible PHP OpenAPI changes in PhpStorm 2020.2) + ## Union Types Support @@ -54,4 +53,4 @@ After 2020.2: for (ClassReference classReference : returnType.getClassReferences()) { handleReference(classReference); } -``` +``` \ No newline at end of file diff --git a/products/phpstorm/php_open_api_breaking_changes_203.md b/topics/products/phpstorm/php_open_api_breaking_changes_203.md similarity index 98% rename from products/phpstorm/php_open_api_breaking_changes_203.md rename to topics/products/phpstorm/php_open_api_breaking_changes_203.md index 7d6c1434b..756b0a613 100644 --- a/products/phpstorm/php_open_api_breaking_changes_203.md +++ b/topics/products/phpstorm/php_open_api_breaking_changes_203.md @@ -1,6 +1,5 @@ ---- -title: Incompatible PHP OpenAPI changes in PhpStorm 2020.3 ---- +[//]: # (title: Incompatible PHP OpenAPI changes in PhpStorm 2020.3) + ## PHP 8 Support diff --git a/products/phpstorm/phpstorm.md b/topics/products/phpstorm/phpstorm.md similarity index 78% rename from products/phpstorm/phpstorm.md rename to topics/products/phpstorm/phpstorm.md index ef6d55801..2df6852f6 100644 --- a/products/phpstorm/phpstorm.md +++ b/topics/products/phpstorm/phpstorm.md @@ -1,10 +1,5 @@ ---- -title: PhpStorm Plugin Development -redirect_from: - - /phpstorm/phpstorm.html - - /phpstorm/setting_up_environment.html - - /products/phpstorm/setting_up_environment.html ---- +[//]: # (title: PhpStorm Plugin Development) + ## Introduction @@ -22,22 +17,24 @@ The IntelliJ IDEA Ultimate Edition (with the PHP plugin) must be used for develo However, this IntelliJ IDEA Ultimate configuration runs the risk of accidentally using some APIs that are not available in PhpStorm. The recommended best practice is to use PhpStorm for testing. -> **NOTE** The OpenAPI is available for PhpStorm 6 and above. + > The OpenAPI is available for PhpStorm 6 and above. + > + {type="note"} -Configuration of a Gradle-based PhpStorm plugin project is used as a tutorial in the section [Configuring Plugin Projects using the IntelliJ IDEA Product Attribute](/products/dev_alternate_products.md#configuring-plugin-projects-using-the-intellij-idea-product-attribute). +Configuration of a Gradle-based PhpStorm plugin project is used as a tutorial in the section [Configuring Plugin Projects using the IntelliJ IDEA Product Attribute](dev_alternate_products.md#configuring-plugin-projects-using-the-intellij-idea-product-attribute). Many techniques are discussed, such as choosing a version of IntelliJ IDEA Ultimate given a targeted version of PhpStorm. The table below summarizes the `gradle-intellij-plugin` attributes to set in the `build.gradle` file for a PhpStorm plugin project: The table below summarizes the `gradle-intellij-plugin` attributes to set in the plugin project's `build.gradle` file. Click on an entry in the table's *Attribute* column to go to the documentation about that attribute. -To see how these attributes appear in the `build.gradle` file for PhpStorm, see [Configuring build.gradle using the IntelliJ IDEA Product Attribute](/products/dev_alternate_products.md#configuring-buildgradle-using-the-intellij-idea-product-attribute). +To see how these attributes appear in the `build.gradle` file for PhpStorm, see [Configuring build.gradle using the IntelliJ IDEA Product Attribute](dev_alternate_products.md#configuring-buildgradle-using-the-intellij-idea-product-attribute). | `gradle-intellij-plugin` Attribute | Attribute Value | | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`intellij.type`][properties] | `IU` for IntelliJ IDEA Ultimate. The required PHP plugin isn't compatible with IntelliJ IDEA Community Edition. | | [`intellij.version`][properties] | Set to the same `IU` BRANCH.BUILD as the PhpStorm target version, e.g. `193.5233.102`. | -| [`intellij.plugins`][properties] | `com.jetbrains.php:193.5233.102` for the PHP plugin.
See below for PHP plugin version information. | -| [`runIde.ideDirectory`][dsl] | Path to locally installed target version of PhpStorm. For example, on macOS:
`/Users//Library/Application Support/JetBrains/Toolbox/apps/PhpStorm/ch-0/193.5233.101/PhpStorm.app/Contents`. | +| [`intellij.plugins`][properties] | `com.jetbrains.php:193.5233.102` for the PHP plugin.
See below for PHP plugin version information. | +| [`runIde.ideDirectory`][dsl] | Path to locally installed target version of PhpStorm. For example, on macOS:
`/Users//Library/Application Support/JetBrains/Toolbox/apps/PhpStorm/ch-0/193.5233.101/PhpStorm.app/Contents`. | [properties]: https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md#intellij-platform-properties [dsl]: https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md#running-dsl @@ -45,4 +42,4 @@ To see how these attributes appear in the `build.gradle` file for PhpStorm, see The PHP plugin version is explicitly declared because it isn't bundled with IntelliJ IDEA Ultimate Edition. Select a [version](https://plugins.jetbrains.com/plugin/6610-php/versions) of the PHP plugin compatible with the `intellij.version`. -The dependency on the PHP plugin APIs must be declared in the `plugin.xml` file, as shown in the tutorial [Configuring plugin.xml](/products/dev_alternate_products.md#configuring-pluginxml) section. +The dependency on the PHP plugin APIs must be declared in the `plugin.xml` file, as shown in the tutorial [Configuring plugin.xml](dev_alternate_products.md#configuring-pluginxml) section. \ No newline at end of file diff --git a/products/pycharm.md b/topics/products/pycharm.md similarity index 93% rename from products/pycharm.md rename to topics/products/pycharm.md index b22ff8802..b7e344284 100644 --- a/products/pycharm.md +++ b/topics/products/pycharm.md @@ -1,13 +1,14 @@ ---- -title: PyCharm Plugin Development ---- +[//]: # (title: PyCharm Plugin Development) + ## Introduction [PyCharm](https://www.jetbrains.com/pycharm/) is an IntelliJ Platform-based product. Plugin projects for PyCharm can be developed using IntelliJ IDEA with the `gradle-intellij-plugin`. -> **TIP** Qualifying Open Source projects can [apply for free licenses](https://www.jetbrains.com/community/opensource/) of JetBrains products. + > Qualifying Open Source projects can [apply for free licenses](https://www.jetbrains.com/community/opensource/) of JetBrains products. + > + {type="tip"} ## Configuring Plugin Projects Targeting PyCharm The configuration of PyCharm plugin projects follows the methods described in [Configuring Plugin Projects using a Product-Specific Attribute](dev_alternate_products.md#configuring-plugin-projects-using-a-product-specific-attribute), and [Configuring the plugin.xml File](dev_alternate_products.md#configuring-pluginxml). @@ -42,4 +43,4 @@ These are considered stable APIs, but care should be taken to test your plugin w ## Open Source Plugins for PyCharm When learning new development configurations, it is helpful to have some representative projects for reference: -* [Flake8 Support](https://github.com/jansorg/pycharm-flake8) Adds support for flake8's # noqa comments in PyCharm. +* [Flake8 Support](https://github.com/jansorg/pycharm-flake8) Adds support for flake8's # noqa comments in PyCharm. \ No newline at end of file diff --git a/products/rider.md b/topics/products/rider.md similarity index 88% rename from products/rider.md rename to topics/products/rider.md index 861911c13..efd0e9649 100644 --- a/products/rider.md +++ b/topics/products/rider.md @@ -1,18 +1,19 @@ ---- -title: Rider Plugin Development ---- +[//]: # (title: Rider Plugin Development) + ## Introduction Rider plugins are generally used to expose the functionality of a ReSharper plugin. -[Rider](https://www.jetbrains.com/rider/) uses the IntelliJ Platform somewhat [differently](/intro/intellij_platform.md#rider) than other Platform-based based IDEs. +[Rider](https://www.jetbrains.com/rider/) uses the IntelliJ Platform somewhat [differently](intellij_platform.md#rider) than other Platform-based based IDEs. Rider uses the IntelliJ Platform to provide the user interface for a C# and .NET IDE but uses ReSharper to provide the language-specific features. -> **TIP** Qualifying Open Source projects can [apply for free licenses](https://www.jetbrains.com/community/opensource/) of JetBrains products. + > Qualifying Open Source projects can [apply for free licenses](https://www.jetbrains.com/community/opensource/) of JetBrains products. + > + {type="tip"} ## IntelliJ IDEA Configuration for Rider Plugin Development Although there is no dedicated Rider SDK, the [ReSharper DevGuide](https://www.jetbrains.com/help/resharper/sdk/Products/Rider.html) addresses the subject of plugins for Rider. -The documentation describes the [configuration](https://www.jetbrains.com/help/resharper/sdk/Products/Rider.html#plugin-project-jvm) of `build.gradle` and `settings.gradle` files to build a Rider plugin using the [Gradle project system](/tutorials/build_system.md) in IntelliJ IDEA. +The documentation describes the [configuration](https://www.jetbrains.com/help/resharper/sdk/Products/Rider.html#plugin-project-jvm) of `build.gradle` and `settings.gradle` files to build a Rider plugin using the [Gradle project system](gradle_build_system.md) in IntelliJ IDEA. ## Developing Rider Plugins with the IDEA and ReSharper SDKs Before starting a new Rider plugin project, review the article [Writing plugins for ReSharper and Rider](https://blog.jetbrains.com/dotnet/2019/02/14/writing-plugins-resharper-rider/). @@ -40,4 +41,4 @@ This list is intended to provide some representative projects. * [TestLinker](https://github.com/matkoch/TestLinker/) * [Xao](https://github.com/hmemcpy/ReSharper.Xao/) * [Azure Toolkit for Rider](https://github.com/JetBrains/azure-tools-for-intellij) -* [T4 language support for both ReSharper and Rider](https://github.com/JetBrains/ForTea) +* [T4 language support for both ReSharper and Rider](https://github.com/JetBrains/ForTea) \ No newline at end of file diff --git a/products/rubymine.md b/topics/products/rubymine.md similarity index 76% rename from products/rubymine.md rename to topics/products/rubymine.md index f1a57d6fc..030c1f523 100644 --- a/products/rubymine.md +++ b/topics/products/rubymine.md @@ -1,27 +1,28 @@ ---- -title: RubyMine Plugin Development ---- +[//]: # (title: RubyMine Plugin Development) + ## Introduction [RubyMine](https://www.jetbrains.com/ruby/) is an IntelliJ Platform-based product. Plugin projects for RubyMine can be developed using IntelliJ IDEA with the `gradle-intellij-plugin`. -> **TIP** Qualifying Open Source projects can [apply for free licenses](https://www.jetbrains.com/community/opensource/) of JetBrains products. + > Qualifying Open Source projects can [apply for free licenses](https://www.jetbrains.com/community/opensource/) of JetBrains products. + > + {type="tip"} ## Configuring Plugin Projects Targeting RubyMine The configuration of RubyMine plugin projects follows the methods described in [Configuring Plugin Projects using the IntelliJ IDEA Product Attribute](dev_alternate_products.md#configuring-plugin-projects-using-the-intellij-idea-product-attribute), and [Configuring the plugin.xml File](dev_alternate_products.md#configuring-pluginxml). The table below summarizes the `gradle-intellij-plugin` attributes to set in the `build.gradle` file for a RubyMine plugin project. Click on an entry in the table's *Attribute* column to go to the documentation about that attribute. -To see how these attributes appear in a similar `build.gradle` file for PhpStorm, see [Configuring build.gradle using the IntelliJ IDEA Product Attribute](/products/dev_alternate_products.md#configuring-buildgradle-using-the-intellij-idea-product-attribute). +To see how these attributes appear in a similar `build.gradle` file for PhpStorm, see [Configuring build.gradle using the IntelliJ IDEA Product Attribute](dev_alternate_products.md#configuring-buildgradle-using-the-intellij-idea-product-attribute). | `gradle-intellij-plugin` Attribute | Attribute Value | | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`intellij.type`][properties] | `IU` for IntelliJ IDEA Ultimate. | | [`intellij.version`][properties] | Set to the same `IU` BRANCH.BUILD as the RubyMine target version, e.g. `192.7142.36`. | -| [`intellij.plugins`][properties] | `org.jetbrains.plugins.ruby:2019.2.20191029` for the Ruby plugin.
See below for Ruby plugin version information. | -| [`runIde.ideDirectory`][dsl] | Path to locally installed target version of RubyMine. For example, on macOS:
`/Users//Library/Application Support/JetBrains/Toolbox/apps/RubyMine/ch-0/192.7142.37/RubyMine.app/Contents`. | +| [`intellij.plugins`][properties] | `org.jetbrains.plugins.ruby:2019.2.20191029` for the Ruby plugin.
See below for Ruby plugin version information. | +| [`runIde.ideDirectory`][dsl] | Path to locally installed target version of RubyMine. For example, on macOS:
`/Users//Library/Application Support/JetBrains/Toolbox/apps/RubyMine/ch-0/192.7142.37/RubyMine.app/Contents`. | [properties]: https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md#intellij-platform-properties [dsl]: https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md#running-dsl @@ -32,7 +33,7 @@ The Ruby plugin isn't bundled with `IU`, so the Ruby plugin version must be expl The correct Ruby plugin version is also determined from the Ruby plugin version page. The dependency on the Ruby plugin APIs must be declared in the `plugin.xml` file. -As described in [Modules Specific to Functionality](/basics/getting_started/plugin_compatibility.md#modules-specific-to-functionality) table, the `` elements must contain `com.intellij.modules.ruby`. +As described in [Modules Specific to Functionality](plugin_compatibility.md#modules-specific-to-functionality) table, the `` elements must contain `com.intellij.modules.ruby`. The dependency declaration is illustrated in the `plugin.xml` snippet below: ```xml @@ -41,11 +42,11 @@ The dependency declaration is illustrated in the `plugin.xml` snippet below: ``` ## Available RubyMine APIs -Use the [Exploring APIs as a Consumer](/basics/getting_started/plugin_compatibility.md#exploring-apis-as-a-consumer) process to identify the library `ruby.jar`. +Use the [Exploring APIs as a Consumer](plugin_compatibility.md#exploring-apis-as-a-consumer) process to identify the library `ruby.jar`. Test your plugin with any version of RubyMine you intend to support. ## Open Source Plugins for RubyMine When learning new APIs, it is helpful to have some representative projects for reference: * [Ruby-Doc-Adder](https://github.com/aristotll/RubyDocAdder) * [Ruby Dynamic Code Insight](https://github.com/JetBrains/ruby-type-inference) -* [Railways](https://github.com/basgren/railways) +* [Railways](https://github.com/basgren/railways) \ No newline at end of file diff --git a/products/webstorm.md b/topics/products/webstorm.md similarity index 70% rename from products/webstorm.md rename to topics/products/webstorm.md index a9e28a44d..9d6632806 100644 --- a/products/webstorm.md +++ b/topics/products/webstorm.md @@ -1,46 +1,47 @@ ---- -title: WebStorm Plugin Development ---- +[//]: # (title: WebStorm Plugin Development) + ## Introduction [WebStorm](https://www.jetbrains.com/webstorm/) is an IntelliJ Platform-based product. Plugin projects for WebStorm can be developed using IntelliJ IDEA with the `gradle-intellij-plugin`. -> **TIP** Qualifying Open Source projects can [apply for free licenses](https://www.jetbrains.com/community/opensource/) of JetBrains products. + > Qualifying Open Source projects can [apply for free licenses](https://www.jetbrains.com/community/opensource/) of JetBrains products. + > + {type="tip"} ## Configuring Plugin Projects Targeting WebStorm The configuration of WebStorm plugin projects follows the methods described in [Configuring Plugin Projects using the IntelliJ IDEA Product Attribute](dev_alternate_products.md#configuring-plugin-projects-using-the-intellij-idea-product-attribute) and [Configuring the plugin.xml File](dev_alternate_products.md#configuring-pluginxml) for PhpStorm. The table below summarizes the `gradle-intellij-plugin` attributes to set in the plugin project's `build.gradle` file. Click on an entry in the table's *Attribute* column to go to the documentation about that attribute. -To see how these attributes appear in a similar `build.gradle` file for PhpStorm, see [Configuring build.gradle using the IntelliJ IDEA Product Attribute](/products/dev_alternate_products.md#configuring-buildgradle-using-the-intellij-idea-product-attribute). +To see how these attributes appear in a similar `build.gradle` file for PhpStorm, see [Configuring build.gradle using the IntelliJ IDEA Product Attribute](dev_alternate_products.md#configuring-buildgradle-using-the-intellij-idea-product-attribute). | `gradle-intellij-plugin` Attribute | Attribute Value | | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`intellij.type`][properties] | `IU` for IntelliJ IDEA Ultimate.
(`IC` is incompatible with the required `JavaScriptLanguage` plugin. | +| [`intellij.type`][properties] | `IU` for IntelliJ IDEA Ultimate.
(`IC` is incompatible with the required `JavaScriptLanguage` plugin. | | [`intellij.version`][properties] | `192.7142.36` Set to the same BRANCH.BUILD as the WebStorm target version. | | [`intellij.plugins`][properties] | Dependency on the `JavaScriptLanguage` plugin. | -| [`runIde.ideDirectory`][dsl] | Path to locally installed target version of WebStorm. For example, for macOS:
`/Users//Library/Application Support/JetBrains/Toolbox/apps/WebStorm/ch-0/192.7142.35/WebStorm.app/Contents`. | +| [`runIde.ideDirectory`][dsl] | Path to locally installed target version of WebStorm. For example, for macOS:
`/Users//Library/Application Support/JetBrains/Toolbox/apps/WebStorm/ch-0/192.7142.35/WebStorm.app/Contents`. | [properties]: https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md#intellij-platform-properties [dsl]: https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md#running-dsl The dependency on the WebStorm APIs must be declared in the `plugin.xml` file. -As described in [Modules Specific to Functionality](/basics/getting_started/plugin_compatibility.md#modules-specific-to-functionality) table, the `` tags must declare `JavaScriptLanguage`. +As described in [Modules Specific to Functionality](plugin_compatibility.md#modules-specific-to-functionality) table, the `` tags must declare `JavaScriptLanguage`. **Note** that for WebStorm, the `plugin.xml` file must also declare a dependency on `com.intellij.modules.platform` because `JavaScriptLanguage` is not recognized as a module. -Consequently, without the `com.intellij.modules.platform` declaration the plugin is assumed to be a [legacy plugin](/basics/getting_started/plugin_compatibility.md#declaring-plugin-dependencies) and will not load in WebStorm. +Consequently, without the `com.intellij.modules.platform` declaration the plugin is assumed to be a [legacy plugin](plugin_compatibility.md#declaring-plugin-dependencies) and will not load in WebStorm. ## Available WebStorm APIs -Use the [Exploring APIs as a Consumer](/basics/getting_started/plugin_compatibility.md#exploring-apis-as-a-consumer) process to identify the libraries `JavaScriptLanguage.jar`, and `javascript-openapi.jar`. +Use the [Exploring APIs as a Consumer](plugin_compatibility.md#exploring-apis-as-a-consumer) process to identify the libraries `JavaScriptLanguage.jar`, and `javascript-openapi.jar`. Test your plugin with any version of WebStorm you wish to support. ### Javascript Testframework -To use existing test base classes, specify `com.jetbrains.intellij.javascript:javascript-test-framework:$VERSION$` as `testImplementation` dependency explicitly (see [IntelliJ Platform Artifacts Repositories](/reference_guide/intellij_artifacts.md#gradle-example-for-an-individual-module-from-the-intellij-platform)) (2020.3 and later). +To use existing test base classes, specify `com.jetbrains.intellij.javascript:javascript-test-framework:$VERSION$` as `testImplementation` dependency explicitly (see [IntelliJ Platform Artifacts Repositories](intellij_artifacts.md#gradle-example-for-an-individual-module-from-the-intellij-platform)) (2020.3 and later). ## Open Source Plugins for WebStorm When learning new plugin development it is helpful to have some representative projects for reference: * [JS Toolbox](https://github.com/andresdominguez/jsToolbox) * [Require.js](https://github.com/Fedott/WebStormRequireJsPlugin) * [deep-js-completion](https://github.com/klesun/deep-js-completion) -* [Run Configuration for TypeScript](https://plugins.jetbrains.com/plugin/10841-run-configuration-for-typescript) +* [Run Configuration for TypeScript](https://plugins.jetbrains.com/plugin/10841-run-configuration-for-typescript) \ No newline at end of file diff --git a/topics/recently_updated.md b/topics/recently_updated.md new file mode 100644 index 000000000..1b91ffb9e --- /dev/null +++ b/topics/recently_updated.md @@ -0,0 +1,5 @@ +[//]: # (title: Recently Updated) + + + +## This page intentionally left blank \ No newline at end of file diff --git a/reference_guide/api_notable/api_notable.md b/topics/reference_guide/api_notable/api_notable.md similarity index 63% rename from reference_guide/api_notable/api_notable.md rename to topics/reference_guide/api_notable/api_notable.md index c6b374b7c..8e04900e3 100644 --- a/reference_guide/api_notable/api_notable.md +++ b/topics/reference_guide/api_notable/api_notable.md @@ -1,15 +1,16 @@ ---- -title: Notable Changes and Features in IntelliJ Platform and Plugins API ---- +[//]: # (title: Notable Changes and Features in IntelliJ Platform and Plugins API) + The following pages list notable changes and new features in IDE releases. Plugin authors are encouraged to verify their compatible releases take advantage of the latest API additions. -> **TIP** Follow [JBPlatform](https://twitter.com/JBPlatform/) on Twitter and visit [JetBrains Platform Blog](https://blog.jetbrains.com/platform/) for the latest announcements. + > Follow [JBPlatform](https://twitter.com/JBPlatform/) on Twitter and visit [JetBrains Platform Blog](https://blog.jetbrains.com/platform/) for the latest announcements. + > + {type="tip"} * [**Changes in 2021.***](api_notable_list_2021.md) * [**Changes in 2020.***](api_notable_list_2020.md) * [**Changes in 2019.***](api_notable_list_2019.md) -* [**Changes in 2018.***](api_notable_list_2018.md) +* [**Changes in 2018.***](api_notable_list_2018.md) \ No newline at end of file diff --git a/reference_guide/api_notable/api_notable_list_2018.md b/topics/reference_guide/api_notable/api_notable_list_2018.md similarity index 90% rename from reference_guide/api_notable/api_notable_list_2018.md rename to topics/reference_guide/api_notable/api_notable_list_2018.md index 30b9039fa..9cc80e658 100644 --- a/reference_guide/api_notable/api_notable_list_2018.md +++ b/topics/reference_guide/api_notable/api_notable_list_2018.md @@ -1,6 +1,5 @@ ---- -title: Notable Changes in IntelliJ Platform and Plugins API 2018.* ---- +[//]: # (title: Notable Changes in IntelliJ Platform and Plugins API 2018.*) + ## 2018.3 @@ -24,4 +23,4 @@ _Run Anything_ (**Double CTRL**) : Allows executing predefined activities using a popup with smart completion, e.g., [Gradle Tasks](https://www.jetbrains.com/help/idea/gradle.html#gradle_tasks), executing Run Configurations, ... see [`RunAnythingProvider`](upsource:///platform/lang-impl/src/com/intellij/ide/actions/runAnything/activity/RunAnythingProvider.java) JPS: Report exception in IDE -: Ability to report exceptions from the build process. [Issue](https://youtrack.jetbrains.com/issue/IDEA-187115) +: Ability to report exceptions from the build process. [Issue](https://youtrack.jetbrains.com/issue/IDEA-187115) \ No newline at end of file diff --git a/reference_guide/api_notable/api_notable_list_2019.md b/topics/reference_guide/api_notable/api_notable_list_2019.md similarity index 90% rename from reference_guide/api_notable/api_notable_list_2019.md rename to topics/reference_guide/api_notable/api_notable_list_2019.md index 187fd51e0..8daba4443 100644 --- a/reference_guide/api_notable/api_notable_list_2019.md +++ b/topics/reference_guide/api_notable/api_notable_list_2019.md @@ -1,6 +1,5 @@ ---- -title: Notable Changes in IntelliJ Platform and Plugins API 2019.* ---- +[//]: # (title: Notable Changes in IntelliJ Platform and Plugins API 2019.*) + ## 2019.3 @@ -8,13 +7,13 @@ title: Notable Changes in IntelliJ Platform and Plugins API 2019.* ### Notable Changes in IntelliJ Platform 2019.3 `PlatformTestCase` renamed to `HeavyPlatformTestCase` -: Now reflects its "heavy test" characteristics (see [Light and Heavy Tests](/basics/testing_plugins/light_and_heavy_tests.md)). +: Now reflects its "heavy test" characteristics (see [Light and Heavy Tests](light_and_heavy_tests.md)). Support for transitive optional plugin dependencies : Optional `plugin.xml` configuration files can now specify ``. [Issue](https://youtrack.jetbrains.com/issue/IDEA-209769) Theme/Keymap plugins do not require restart -: (Un)Installing or enabling/disabling [Theme](/reference_guide/ui_themes/themes_intro.md) or [Keymap](https://plugins.jetbrains.com/search?tags=Keymap) plugins doesn't require an IDE restart anymore. +: (Un)Installing or enabling/disabling [Theme](themes_intro.md) or [Keymap](https://plugins.jetbrains.com/search?tags=Keymap) plugins doesn't require an IDE restart anymore. Run task once (per project) : Use `com.intellij.ide.util.RunOnceUtil` to run a task exactly once for application or per project. @@ -31,7 +30,6 @@ Unbundled plugins : Several plugins (Heroku integration, RubyMotion support, Java Applets Support) for no longer actively maintained technology have been moved to a [separate repository](https://github.com/JetBrains/intellij-obsolete-plugins/). If your plugin depends on them, users will need to install them from the [JetBrains Plugins Repository](https://plugins.jetbrains.com). - ## 2019.2 ### Notable Changes in IntelliJ Platform 2019.2 @@ -61,7 +59,7 @@ New API for Editor Inlay Hints : Use new dedicated extension point `com.intellij.highlightingPassFactory`. `com.intellij.openapi.fileTypes.FileTypeFactory` deprecated -: When registering file type via file extension, pattern or exact file name matching, use extension point `com.intellij.fileType` instead (see [Sample](/tutorials/custom_language_support/language_and_filetype.md#b-register-file-type-20192-or-later)). +: When registering file type via file extension, pattern or exact file name matching, use extension point `com.intellij.fileType` instead (see [Sample](language_and_filetype.md#register-the-filetype-directly)). `@org.jetbrains.annotations.ApiStatus.NonExtendable` : Indicates that the annotated API class, interface, or method must not get extended, implemented, or overridden by external plugins but can only be obtained or instantiated for classes and interfaces, or called for methods. @@ -75,7 +73,6 @@ New API for Editor Inlay Hints `com.intellij.openapi.projectRoots.SdkType#getInvalidHomeMessage` : Returns dedicated message when invalid SDK path was chosen (e.g., JRE instead of JDK). - ### Notable Changes in IntelliJ IDEA 2019.2 Java functionality extracted as a plugin @@ -84,14 +81,12 @@ Java functionality extracted as a plugin Unbundled plugins : Several plugins (J2ME, JsTestDriver, Struts 1.x) for no longer actively maintained technology have been moved to a [separate repository](https://github.com/JetBrains/intellij-obsolete-plugins/). If your plugin depends on them, users will need to install them from the [JetBrains Plugins Repository](https://plugins.jetbrains.com). - - ## 2019.1 ### Notable Changes in IntelliJ Platform 2019.1 `com.intellij.testFramework.InspectionTestCase` changed to light test -: Use dedicated `ProjectDescriptor` or rollback project setup changes in `tearDown()` (see [Light and Heavy Tests](/basics/testing_plugins/light_and_heavy_tests.md)). +: Use dedicated `ProjectDescriptor` or rollback project setup changes in `tearDown()` (see [Light and Heavy Tests](light_and_heavy_tests.md)). `@org.jetbrains.annotations.ApiStatus.AvailableSince` : External annotations for the IntelliJ Platform are generated and attached to plugin projects automatically (replacing `@since` Javadoc). @@ -106,4 +101,4 @@ Unbundled plugins : Assert references are created for the given underlying `PsiElement`. [Issue](https://youtrack.jetbrains.com/issue/IDEA-203954) `CachedValue` more strict assertions -: Enabled in tests and EAP/internal mode, see [`CachedValueStabilityChecker`](upsource:///platform/core-impl/src/com/intellij/util/CachedValueStabilityChecker.java) Javadoc. +: Enabled in tests and EAP/internal mode, see [`CachedValueStabilityChecker`](upsource:///platform/core-impl/src/com/intellij/util/CachedValueStabilityChecker.java) Javadoc. \ No newline at end of file diff --git a/reference_guide/api_notable/api_notable_list_2020.md b/topics/reference_guide/api_notable/api_notable_list_2020.md similarity index 86% rename from reference_guide/api_notable/api_notable_list_2020.md rename to topics/reference_guide/api_notable/api_notable_list_2020.md index 8fed31899..4344a9abe 100644 --- a/reference_guide/api_notable/api_notable_list_2020.md +++ b/topics/reference_guide/api_notable/api_notable_list_2020.md @@ -1,6 +1,5 @@ ---- -title: Notable Changes in IntelliJ Platform and Plugins API 2020.* ---- +[//]: # (title: Notable Changes in IntelliJ Platform and Plugins API 2020.*) + We've published our roadmap for the IntelliJ Platform for 2020: [Part I](https://blog.jetbrains.com/idea/2019/12/intellij-platform-roadmap-for-2020/) [Part II](https://blog.jetbrains.com/idea/2020/01/intellij-based-ide-features-roadmap-for-2020/) @@ -19,14 +18,14 @@ Reparsing of `IReparseableLeafElementType` : For elements whose `IElementType` implements this interface, platform attempts reparse when a modification is made right before or after the leaf element preventing reparsing the whole file. Generating HTML fragments -: Use `com.intellij.openapi.util.text.HtmlBuilder` for generating formatted content, e.g., for [Documentation](/reference_guide/custom_language_support/documentation.md). +: Use `com.intellij.openapi.util.text.HtmlBuilder` for generating formatted content, e.g., for [Documentation](documentation.md). Extensible HTML Lexer/Parser : Implement `com.intellij.html.embedding.HtmlEmbeddedContentSupport` and register in `com.intellij.html.embeddedContentSupport` extension point to embed arbitrary tokens into any tag or attribute. Please note that old API from `com.intellij.lexer.BaseHtmlLexer` is no longer working. Action System -: New features in [Action System](/basics/action_system.md): `` works now for `` as well, `` provides alternative names when searching for actions, and groups can be excluded from search results. +: New features in [Action System](basic_action_system.md): `` works now for `` as well, `` provides alternative names when searching for actions, and groups can be excluded from search results. Welcome Screen customization : To provide additional custom tabs, implement `com.intellij.openapi.wm.WelcomeTabFactory` and register in `com.intellij.welcomeTabFactory` extension point. @@ -43,7 +42,7 @@ Text Editor customization ### Notable Changes in JavaScript Plugin 2020.3 Published Javascript Testframework -: This allows using existing test base classes, see [WebStorm Plugin Development](/products/webstorm.md#javascript-testframework) page for details. +: This allows using existing test base classes, see [WebStorm Plugin Development](webstorm.md#javascript-testframework) page for details. ### Notable Changes In CLion/AppCode 2020.3 @@ -65,7 +64,7 @@ Tooltip descriptions for icons : Register resource bundle via extension point `com.intellij.iconDescriptionBundle` to provide tooltips automatically for all `SimpleColoredComponent` renderers. Specify incompatibility with Module -: A plugin can [mark itself incompatible](/basics/getting_started/plugin_compatibility.md#declaring-incompatibility-with-module) if IDE contains specified module. +: A plugin can [mark itself incompatible](plugin_compatibility.md#declaring-incompatibility-with-module) if IDE contains specified module. `com.intellij.openapi.editor.markup.MarkupModel` methods using `TextAttributesKey` : To support on-the-fly Editor color scheme switching, change calls from methods taking `TextAttributes`. @@ -89,7 +88,7 @@ Delegate Run Anything/Terminal commands to IDE features : Switch to matching IDE feature by implementing `com.intellij.terminal.TerminalShellCommandHandler` (extension point `com.intellij.terminal.shellCommandHandler`). [Blog post](https://blog.jetbrains.com/idea/2020/07/run-ide-features-from-the-terminal/) Deprecating JavaFX in favor of JCEF -: We recommend switching to [JCEF](/reference_guide/jcef.md), please see [blog post](https://blog.jetbrains.com/platform/2020/07/javafx-and-jcef-in-the-intellij-platform/) for details. +: We recommend switching to [JCEF](jcef.md), please see [blog post](https://blog.jetbrains.com/platform/2020/07/javafx-and-jcef-in-the-intellij-platform/) for details. ASM Library 8.0.1 : Updated from 7.0.1. @@ -102,7 +101,7 @@ Validating Lexer for editor highlighting ### Notable Changes in IntelliJ Platform 2020.1 Dynamic Plugins -: [Compatible plugins](/basics/plugin_structure/dynamic_plugins.md) can be installed, updated and uninstalled without requiring IDE restart. +: [Compatible plugins](dynamic_plugins.md) can be installed, updated and uninstalled without requiring IDE restart. [`com.intellij.openapi.application.TransactionGuard`](upsource:///platform/core-api/src/com/intellij/openapi/application/TransactionGuard.java) deprecated : Usage is deprecated and can be replaced with `com.intellij.openapi.application.Application.invokeLater()` in most cases, please consult Javadoc for more details. @@ -120,10 +119,10 @@ Configurable status bar widgets : Use extension point `com.intellij.statusBarWidgetFactory` to provide widgets that can be disabled or reordered. JCEF Support (_Experimental Feature_) -: Allows [embedding](/reference_guide/jcef.md) Chromium-based browser in the IDE. +: Allows [embedding](jcef.md) Chromium-based browser in the IDE. Override text presentation for actions depending on menu context -: Set the [``](/basics/action_system.md#setting-the-override-text-element-for-an-action) element within the `` declaration in `plugin.xml`. +: Set the [``](basic_action_system.md#setting-the-override-text-element) element within the `` declaration in `plugin.xml`. Changes in Project Open/Import : **Import from Existing Sources** has been removed from the Welcome Screen, leaving only **Open or Import**, which calls a different extension than the one previously used to contribute a wizard step to **Import from Existing Sources** (which is still available in the **File** menu). To support **Open or Import**, a plugin must provide [`ProjectOpenProcessor`](upsource:///platform/platform-api/src/com/intellij/projectImport/ProjectOpenProcessor.java). @@ -135,4 +134,4 @@ EOL for JetBrains TFS Plugin : Please use [Azure DevOps](https://plugins.jetbrains.com/plugin/7981-azure-devops) plugin instead, see [blog post](https://blog.jetbrains.com/idea/2020/01/end-of-support-for-tfs-2014-and-older/) for more details. Unbundled plugins -: Several plugins (Cloud Foundry, Google App Engine) for no longer actively maintained technology have been unbundled. If your plugin depends on them, users will need to install them from the [JetBrains Plugins Repository](https://plugins.jetbrains.com). +: Several plugins (Cloud Foundry, Google App Engine) for no longer actively maintained technology have been unbundled. If your plugin depends on them, users will need to install them from the [JetBrains Plugins Repository](https://plugins.jetbrains.com). \ No newline at end of file diff --git a/reference_guide/api_notable/api_notable_list_2021.md b/topics/reference_guide/api_notable/api_notable_list_2021.md similarity index 59% rename from reference_guide/api_notable/api_notable_list_2021.md rename to topics/reference_guide/api_notable/api_notable_list_2021.md index ae95956ac..95aac6be1 100644 --- a/reference_guide/api_notable/api_notable_list_2021.md +++ b/topics/reference_guide/api_notable/api_notable_list_2021.md @@ -1,8 +1,7 @@ ---- -title: Notable Changes in IntelliJ Platform and Plugins API 2021.* ---- +[//]: # (title: Notable Changes in IntelliJ Platform and Plugins API 2021.*) + ## 2021.1 -### Notable Changes in IntelliJ Platform 2021.1 +### Notable Changes in IntelliJ Platform 2021.1 \ No newline at end of file diff --git a/reference_guide/color_scheme_management.md b/topics/reference_guide/color_scheme_management.md similarity index 97% rename from reference_guide/color_scheme_management.md rename to topics/reference_guide/color_scheme_management.md index d56ab36bd..9567fc289 100644 --- a/reference_guide/color_scheme_management.md +++ b/topics/reference_guide/color_scheme_management.md @@ -1,6 +1,5 @@ ---- -title: Color Scheme Management ---- +[//]: # (title: Color Scheme Management) + ## Preface @@ -37,7 +36,9 @@ static final TextAttributesKey MY_PREDEFINED_SYMBOL = The rule is the same: if text attributes can not be found by the `MY_PREDEFINED_SYMBOL` key or are empty, the color scheme manager will search for `MY_KEYWORD` and if not found (empty) will further look for `DEFAULT_KEYWORD`. -> **NOTE** A use of fixed default attributes is _strongly discouraged_. + > A use of fixed default attributes is _strongly discouraged_. + > + {type="note"} If you are unsure which base key to use, it's better to pick the most generic one, for example, `DefaultLanguageHighlighterColors.IDENTIFIER`. Remember that using fixed default attributes *will force* a scheme designer to explicitly set up a color for this element. @@ -106,4 +107,4 @@ Anyway, try to stick with a simple key dependency if possible (note that it work For many language text attributes that do not have any values, there will be a line indicating that the attributes are inherited from a specific section/attributes, such as "Keyword (Language Defaults)". If an element has *any* attributes set, only these attributes are used. All attributes from the base element are ignored. -To *restore* the inheritance, unchecks all the boxes, and click *Apply*. +To *restore* the inheritance, unchecks all the boxes, and click *Apply*. \ No newline at end of file diff --git a/topics/reference_guide/custom_language_support.md b/topics/reference_guide/custom_language_support.md new file mode 100644 index 000000000..d1856de32 --- /dev/null +++ b/topics/reference_guide/custom_language_support.md @@ -0,0 +1,39 @@ +[//]: # (title: Custom Language Support) + + + +*IntelliJ Platform* is a powerful platform for building development tools targeting *any* language. +Most of the IDE features consist of language-independent (provided by the platform) and language-specific parts. +Supporting a particular feature for a new language can be achieved with a small amount of effort: +a plugin must implement only the language-specific part. + +This part of the documentation explains the main concepts of the *Language API* and guides you through the sequence of steps that are usually required to develop a custom language plugin. +You can obtain additional information about the *Language API* from the JavaDoc comments for the *Language API* classes and from the Properties language support source code, which is part of the [IntelliJ IDEA Community Edition](https://github.com/JetBrains/intellij-community) source code. + +If you prefer a full example to the detailed descriptions offered in this section, please check out a step-by-step tutorial on how to create custom language support for _Simple Language_: +[Custom Language Support Tutorial](custom_language_support_tutorial.md). +Corresponding steps from the tutorial are linked under the "Examples" section on each page of this reference. + +The webinar [How We Built Comma, the Raku IDE, on the IntelliJ Platform](https://blog.jetbrains.com/platform/2020/01/webinar-recording-how-we-built-comma-the-raku-ide-on-the-intellij-platform/) offers an excellent introduction as well. + +Providing custom language support includes the following major steps: + +* [Registering File Type](registering_file_type.md) +* [Implementing Lexer](implementing_lexer.md) +* [Implementing Parser and PSI](implementing_parser_and_psi.md) +* [Syntax Highlighting and Error Highlighting](syntax_highlighting_and_error_highlighting.md) +* [References and Resolve](references_and_resolve.md) +* [Symbols](symbols.md) +* [Declarations and References](declarations_and_references.md) +* [Navigation](navigation.md) +* [Code Completion](code_completion.md) +* [Find Usages](find_usages.md) +* [Rename Refactoring](rename_refactoring.md) +* [Safe Delete Refactoring](safe_delete_refactoring.md) +* [Code Formatter](code_formatting.md) +* [Code Inspections and Intentions](code_inspections_and_intentions.md) +* [Structure View](structure_view.md) +* [Surround With](surround_with.md) +* [Go to Class and Go to Symbol](go_to_class_and_go_to_symbol.md) +* [Documentation](documentation.md) +* [Additional Minor Features](additional_minor_features.md) \ No newline at end of file diff --git a/reference_guide/custom_language_support/additional_minor_features.md b/topics/reference_guide/custom_language_support/additional_minor_features.md similarity index 94% rename from reference_guide/custom_language_support/additional_minor_features.md rename to topics/reference_guide/custom_language_support/additional_minor_features.md index ea80a3449..1fa697aae 100644 --- a/reference_guide/custom_language_support/additional_minor_features.md +++ b/topics/reference_guide/custom_language_support/additional_minor_features.md @@ -1,6 +1,5 @@ ---- -title: Additional Minor Features ---- +[//]: # (title: Additional Minor Features) + A number of minor features are listed in the following format: @@ -11,7 +10,6 @@ _`com.extensionPoint.class`_ _description text_ - Extension Point class/interfac _- Sample 1_ - Sample implementation - ### Brace Matching EP: `com.intellij.lang.braceMatcher` @@ -24,42 +22,36 @@ Certain types of braces can be marked as structural. Structural braces have higher priority than regular braces: they are matched with each other even if there are unmatched braces of different types between them. An opening non-structural brace is not matched with a closing one if one of them is inside a pair of matched structural braces and another is outside. - ### Comment Code EP: `com.intellij.lang.commenter` [`Commenter`](upsource:///platform/core-api/src/com/intellij/lang/Commenter.java) returns the prefix for the line comment, and the prefix and suffix for the block comment if supported by the language. - [`Commenter`](upsource:///plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/PropertiesCommenter.java) for [Properties language plugin](upsource:///plugins/properties/) -- [Custom Language Support Tutorial: Commenter](/tutorials/custom_language_support/commenter.md) - +- [Custom Language Support Tutorial: Commenter](commenter.md) ### Code Folding EP: `com.intellij.lang.foldingBuilder` [`FoldingBuilder`](upsource:///platform/core-api/src/com/intellij/lang/folding/FoldingBuilder.java) returns the list of foldable text ranges (as an array of [`FoldingDescriptor`](upsource:///platform/core-api/src/com/intellij/lang/folding/FoldingDescriptor.java) objects), the replacement text which is shown for each range when it is folded, and the default state of each folding region (folded or unfolded). -- [Custom Language Support Tutorial: Folding Builder](/tutorials/custom_language_support/folding_builder.md) - +- [Custom Language Support Tutorial: Folding Builder](folding_builder.md) ### Join Lines EP: `com.intellij.joinLinesHandler` [`JoinLinesHandlerDelegate`](upsource:///platform/lang-api/src/com/intellij/codeInsight/editorActions/JoinLinesHandlerDelegate.java) allows extending support smart/semantic *Edit \| Join Lines* (e.g., String literal split on multiple lines). - ### Smart Enter EP: `com.intellij.lang.smartEnterProcessor` [`SmartEnterProcessor`](upsource:///platform/lang-api/src/com/intellij/codeInsight/editorActions/smartEnter/SmartEnterProcessor.java) handles *Edit \| Complete Statement* (e.g., autocomplete missing semicolon/parentheses). - ### Naming Suggestions EP: `com.intellij.nameSuggestionProvider` [`NameSuggestionProvider`](upsource:///platform/lang-api/src/com/intellij/refactoring/rename/NameSuggestionProvider.java) provides name suggestions for the given element, e.g., for Rename refactoring. - ### Semantic Highlight Usages EP: `com.intellij.highlightUsagesHandlerFactory` @@ -70,19 +62,16 @@ EP: `com.intellij.codeInsight.parameterInfo` [`ParameterInfoHandler`](upsource:///platform/lang-api/src/com/intellij/lang/parameterInfo/ParameterInfoHandler.java) provides support for *View \| Parameter Info*. - ### To Do View EP: n/a [`ParserDefinition.getCommentTokens()`](upsource:///platform/core-api/src/com/intellij/lang/ParserDefinition.java) must return the set of tokens treated as comments to populate *To Do View*. - ### Context Info EP: `com.intellij.declarationRangeHandler` [`DeclarationRangeHandler`](upsource:///platform/lang-api/src/com/intellij/codeInsight/hint/DeclarationRangeHandler.java) provides *View \| Context Info* for custom languages with structure view implementation based on a [`TreeBasedStructureViewBuilder`](upsource:///platform/editor-ui-api/src/com/intellij/ide/structureView/TreeBasedStructureViewBuilder.java). - ### Spellchecking EP: `com.intellij.spellchecker.support` @@ -93,8 +82,7 @@ EP: `com.intellij.referenceInjector` [`ReferenceInjector`](upsource:///platform/analysis-api/src/com/intellij/psi/injection/ReferenceInjector.java) allows users to inject pre-defined references (e.g., "Encoding", "File Reference") into `PsiLanguageInjectionHost` elements (IntelliLang plugin required). - ### Color Preview/Chooser EP: `com.intellij.colorProvider` -[`ElementColorProvider`](upsource:///platform/lang-api/src/com/intellij/openapi/editor/ElementColorProvider.java) renders gutter icon for element containing color information. +[`ElementColorProvider`](upsource:///platform/lang-api/src/com/intellij/openapi/editor/ElementColorProvider.java) renders gutter icon for element containing color information. \ No newline at end of file diff --git a/reference_guide/custom_language_support/code_completion.md b/topics/reference_guide/custom_language_support/code_completion.md similarity index 91% rename from reference_guide/custom_language_support/code_completion.md rename to topics/reference_guide/custom_language_support/code_completion.md index 6d8bd9804..72d82d5b5 100644 --- a/reference_guide/custom_language_support/code_completion.md +++ b/topics/reference_guide/custom_language_support/code_completion.md @@ -1,6 +1,5 @@ ---- -title: Code Completion ---- +[//]: # (title: Code Completion) + Two main types of code completion can be provided by custom language plugins: reference completion and contributor-based completion. @@ -18,7 +17,9 @@ The most common way to implement `getVariants()` is to use the same function for #### Symbol Reference Completion -> **WARNING** This API is available starting from 2020.3 and currently in development and thus in experimental state. + > This API is available starting from 2020.3 and currently in development and thus in experimental state. + > + {type="warning"} To provide completion variants by a `PsiSymbolReference` implement [`PsiCompletableReference`](upsource:///platform/analysis-api/src/com/intellij/model/psi/PsiCompletableReference.java). @@ -27,7 +28,9 @@ To provide completion variants by a `PsiSymbolReference` implement Implementing the [`CompletionContributor`](upsource:///platform/analysis-api/src/com/intellij/codeInsight/completion/CompletionContributor.java) interface gives you the greatest control over the operation of code completion for your language. -> **NOTE** Note that the JavaDoc of that class contains a detailed FAQ for implementing code completion. + > Note that the JavaDoc of that class contains a detailed FAQ for implementing code completion. + > + {type="note"} The core scenario of using [`CompletionContributor`](upsource:///platform/analysis-api/src/com/intellij/codeInsight/completion/CompletionContributor.java) consists of calling the `extend()` method and passing in the *pattern* specifying the context in which this completion variant is applicable, as well as a *completion provider* which generates the items to show in the completion list. @@ -36,8 +39,7 @@ If you want to match a composite element, use `withParent()` or `withSuperParent **Examples**: - [`CompletionContributor`](https://github.com/JetBrains/intellij-plugins/blob/master/osmorc/src/org/osmorc/manifest/completion/OsgiManifestCompletionContributor.java) for completing keywords in MANIFEST.MF files. -- [Custom Language Support Tutorial: Completion Contributor](/tutorials/custom_language_support/completion_contributor.md) - +- [Custom Language Support Tutorial: Completion Contributor](completion_contributor.md) ### Lookup Items Items shown in the completion list are represented by instances of the [`LookupElement`](upsource:///platform/analysis-api/src/com/intellij/codeInsight/lookup/LookupElement.java) interface. @@ -50,4 +52,4 @@ For every lookup element, you can specify the following attributes: * Type text. Shown right-aligned in the lookup list and can be used to show the return type or containing class of a method, for example. * Icon * Text attributes. Bold, Strikeout, etc. -* Insert handler. The insert handler is a callback which is called when the item is selected and can be used to perform additional modifications of the text (for example, to put in the parentheses for a method call) +* Insert handler. The insert handler is a callback which is called when the item is selected and can be used to perform additional modifications of the text (for example, to put in the parentheses for a method call) \ No newline at end of file diff --git a/reference_guide/custom_language_support/code_formatting.md b/topics/reference_guide/custom_language_support/code_formatting.md similarity index 96% rename from reference_guide/custom_language_support/code_formatting.md rename to topics/reference_guide/custom_language_support/code_formatting.md index 69e3207ae..8f0595ac9 100644 --- a/reference_guide/custom_language_support/code_formatting.md +++ b/topics/reference_guide/custom_language_support/code_formatting.md @@ -1,6 +1,5 @@ ---- -title: Code Formatter ---- +[//]: # (title: Code Formatter) + The IntelliJ Platform includes a powerful framework for implementing custom language formatters. @@ -61,7 +60,7 @@ If the block before the cursor is incomplete (contains elements that the user wi Code formatting can be suppressed per region via [special comments](https://youtrack.jetbrains.com/issue/IDEA-56995#comment=27-605969). **Example**: -[Custom Language Support Tutorial: Formatter](/tutorials/custom_language_support/formatter.md) +[Custom Language Support Tutorial: Formatter](formatter.md) ### Code Style Settings @@ -69,11 +68,11 @@ To specify the default indent size for the language provided by your plugin, and The return value of `createIndentOptions()` determines the default indent size. **Example**: -[Custom Language Support Tutorial: Code Style Settings](/tutorials/custom_language_support/code_style_settings.md) +[Custom Language Support Tutorial: Code Style Settings](code_style_settings.md) ### Rearranger **New in IntelliJ IDEA 12:** Allows custom languages to provide user-configurable arrangement/grouping rules for element types supported by language plugin. Rules can be refined via modifiers and name, ordering can be applied additionally. -Please see [`Rearranger`](upsource:///platform/code-style-api/src/com/intellij/psi/codeStyle/arrangement/Rearranger.java) and related for JavaDoc. +Please see [`Rearranger`](upsource:///platform/code-style-api/src/com/intellij/psi/codeStyle/arrangement/Rearranger.java) and related for JavaDoc. \ No newline at end of file diff --git a/reference_guide/custom_language_support/code_inspections_and_intentions.md b/topics/reference_guide/custom_language_support/code_inspections_and_intentions.md similarity index 87% rename from reference_guide/custom_language_support/code_inspections_and_intentions.md rename to topics/reference_guide/custom_language_support/code_inspections_and_intentions.md index 00c433cd7..cd2dd53e3 100644 --- a/reference_guide/custom_language_support/code_inspections_and_intentions.md +++ b/topics/reference_guide/custom_language_support/code_inspections_and_intentions.md @@ -1,6 +1,5 @@ ---- -title: Code Inspections and Intentions ---- +[//]: # (title: Code Inspections and Intentions) + ### Inspections @@ -17,16 +16,15 @@ The main differences are: If none of that is required and the analysis only needs to run in the active editor, [Annotator](syntax_highlighting_and_error_highlighting.md#annotator) provides better performance (because it supports incremental analysis) and more flexibility for highlighting errors. **Examples**: -- [Code Inspections Tutorial](/tutorials/code_inspections.md) +- [Code Inspections Tutorial](code_inspections.md) - A [simple inspection](upsource:///plugins/properties/properties-psi-impl/src/com/intellij/codeInspection/TrailingSpacesInPropertyInspection.java) for [Properties language plugin](upsource:///plugins/properties/) - ### Intentions The code intentions for custom languages also use the standard API for intentions. The intention classes need to implement the [`IntentionAction`](upsource:///platform/analysis-api/src/com/intellij/codeInsight/intention/IntentionAction.java) interface and are registered using the `com.intellij.intentionAction` extension point. **Examples:** -- [Code Intentions Tutorial](/tutorials/code_intentions.md) +- [Code Intentions Tutorial](code_intentions.md) - A [simple intention action](upsource:///plugins/groovy/src/org/jetbrains/plugins/groovy/intentions/control/SplitIfIntention.java) for Groovy -- [Custom Language Support Tutorial: Quick Fix](/tutorials/custom_language_support/quick_fix.md) +- [Custom Language Support Tutorial: Quick Fix](quick_fix.md) \ No newline at end of file diff --git a/reference_guide/custom_language_support/declarations_and_references.md b/topics/reference_guide/custom_language_support/declarations_and_references.md similarity index 95% rename from reference_guide/custom_language_support/declarations_and_references.md rename to topics/reference_guide/custom_language_support/declarations_and_references.md index c9b03affa..09d72b031 100644 --- a/reference_guide/custom_language_support/declarations_and_references.md +++ b/topics/reference_guide/custom_language_support/declarations_and_references.md @@ -1,9 +1,10 @@ ---- -title: Declarations and References ---- +[//]: # (title: Declarations and References) + -> **WARNING** This API is available starting from 2020.3 and currently in development and thus in experimental state. + > This API is available starting from 2020.3 and currently in development and thus in experimental state. + > + {type="warning"} ## Declarations @@ -23,7 +24,6 @@ To report a declaration in a PSI element, either: [`PsiSymbolDeclarationProvider`](upsource:///platform/core-api/src/com/intellij/model/psi/PsiSymbolDeclarationProvider.java); - or implement `PsiSymbolDeclaration` directly in the `PsiElement`. - ## References References are implementations of @@ -46,7 +46,6 @@ For convenience, if the reference can possibly be resolved: - to multiple symbols without additional data, then [`SymbolResolveResult.fromSymbol()`](upsource:///platform/core-api/src/com/intellij/model/SymbolResolveResult.java) might be used. - ### Own References Own references are the references found in PSI elements, which are considered as references by the language. @@ -59,7 +58,6 @@ To provide Own references by the `PsiElement`, implement [`PsiElement.getOwnReferences()`](upsource:///platform/core-api/src/com/intellij/psi/PsiElement.java) in the `PsiElement`. If the element contains a single reference, `Collections.singletonList()` can be used - ### External References External references are the references which are not considered as references by the host language. @@ -75,7 +73,6 @@ To allow other plugins to contribute references of `PsiElement`, implement `PsiE To contribute an External reference to the existing `PsiExternalReferenceHost`, implement and register [`PsiSymbolReferenceProvider`](upsource:///platform/core-api/src/com/intellij/model/psi/PsiSymbolReferenceProvider.java). - ### Implicit References Implicit references are the references which should be part of the mechanism to obtain a target by a reference, @@ -89,4 +86,4 @@ At the same time it's possible: - to view documentation of the class targeted by this reference. To provide an Implicit reference, implement and register -[`ImplicitReferenceProvider`](upsource:///platform/core-api/src/com/intellij/model/psi/ImplicitReferenceProvider.java). +[`ImplicitReferenceProvider`](upsource:///platform/core-api/src/com/intellij/model/psi/ImplicitReferenceProvider.java). \ No newline at end of file diff --git a/reference_guide/custom_language_support/documentation.md b/topics/reference_guide/custom_language_support/documentation.md similarity index 97% rename from reference_guide/custom_language_support/documentation.md rename to topics/reference_guide/custom_language_support/documentation.md index 1081529e0..39f0e31a9 100644 --- a/reference_guide/custom_language_support/documentation.md +++ b/topics/reference_guide/custom_language_support/documentation.md @@ -1,6 +1,5 @@ ---- -title: Documentation ---- +[//]: # (title: Documentation) + To provide different kinds of documentation support, the plugin needs to provide an implementation of the [`DocumentationProvider`](upsource:///platform/analysis-api/src/com/intellij/lang/documentation/DocumentationProvider.java) interface and register it in the `com.intellij.lang.documentationProvider` extension point. @@ -13,4 +12,4 @@ When generating complete documentation via `generateDoc()`, use [`DocumentationM Additional custom actions can be added to documentation inlays and documentation popup via `com.intellij.codeInsight.documentation.DocumentationActionProvider` registered in `com.intellij.documentationActionProvider` extension point. (2020.3) **Example**: -[`DocumentationProvider`](upsource:///plugins/properties/src/com/intellij/lang/properties/PropertiesDocumentationProvider.java) for [Properties language plugin](upsource:///plugins/properties/) +[`DocumentationProvider`](upsource:///plugins/properties/src/com/intellij/lang/properties/PropertiesDocumentationProvider.java) for [Properties language plugin](upsource:///plugins/properties/) \ No newline at end of file diff --git a/reference_guide/custom_language_support/find_usages.md b/topics/reference_guide/custom_language_support/find_usages.md similarity index 93% rename from reference_guide/custom_language_support/find_usages.md rename to topics/reference_guide/custom_language_support/find_usages.md index ae717b810..41e69e258 100644 --- a/reference_guide/custom_language_support/find_usages.md +++ b/topics/reference_guide/custom_language_support/find_usages.md @@ -1,6 +1,5 @@ ---- -title: Find Usages ---- +[//]: # (title: Find Usages) + The _Find Usages_ action is a multi-step process, and each step of the process requires involvement from the custom language plugin. @@ -9,7 +8,7 @@ The language plugin participates in the Find Usages process by registering an im **Examples**: - Implementation of [`FindUsagesProvider`](upsource:///plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/findUsages/PropertiesFindUsagesProvider.java) in [Properties language plugin](upsource:///plugins/properties/) -- [Custom Language Support Tutorial: Find Usages](/tutorials/custom_language_support/find_usages_provider.md) +- [Custom Language Support Tutorial: Find Usages](find_usages_provider.md) The steps of the _Find Usages_ action are the following: * Before the _Find Usages_ action can be invoked, the IDE builds an index of words present in every file in the custom language. @@ -36,6 +35,6 @@ The [`ElementDescriptionLocation`](upsource:///platform/core-api/src/com/intelli **Example:** [`ElementDescriptionProvider`](upsource:///plugins/properties/src/com/intellij/lang/properties/PropertiesDescriptionProvider.java) for [Properties language plugin](upsource:///plugins/properties/) -> **TIP** In cases like function parameters and local variables, consider overriding [`PsiElement.getUseScope()`](upsource:///platform/core-api/src/com/intellij/psi/PsiElement.java) to return a narrower scope. + > In cases like function parameters and local variables, consider overriding [`PsiElement.getUseScope()`](upsource:///platform/core-api/src/com/intellij/psi/PsiElement.java) to return a narrower scope. > For instance, you might return just the scope of the nearest function definition. -> This optimization can significantly reduce the number of files that need to be parsed--and references that need to be resolved--when renaming a function parameter or local variable. +> This optimization can significantly reduce the number of files that need to be parsed--and references that need to be resolved--when renaming a function parameter or local variable. \ No newline at end of file diff --git a/reference_guide/custom_language_support/go_to_class_and_go_to_symbol.md b/topics/reference_guide/custom_language_support/go_to_class_and_go_to_symbol.md similarity index 72% rename from reference_guide/custom_language_support/go_to_class_and_go_to_symbol.md rename to topics/reference_guide/custom_language_support/go_to_class_and_go_to_symbol.md index f612ab385..d442dbf14 100644 --- a/reference_guide/custom_language_support/go_to_class_and_go_to_symbol.md +++ b/topics/reference_guide/custom_language_support/go_to_class_and_go_to_symbol.md @@ -1,17 +1,18 @@ ---- -title: Go to Class and Go to Symbol ---- +[//]: # (title: Go to Class and Go to Symbol) + A custom language plugin can provide its own items to be included in the lists shown when the user chooses the _Navigate | Class_ or _Navigate | Symbol_ action. In order to do so, the plugin must provide implementations for the [`ChooseByNameContributor`](upsource:///platform/lang-api/src/com/intellij/navigation/ChooseByNameContributor.java) interface (separate implementations need to be provided for _Class_ and _Symbol_ respectively), and register them in the `com.intellij.gotoClassContributor` and `com.intellij.gotoSymbolContributor` extension points. -> **TIP** Please consider implementing [`ChooseByNameContributorEx`](upsource:///platform/lang-impl/src/com/intellij/navigation/ChooseByNameContributorEx.java) for better performance. + > Please consider implementing [`ChooseByNameContributorEx`](upsource:///platform/lang-impl/src/com/intellij/navigation/ChooseByNameContributorEx.java) for better performance. + > + {type="tip"} Each contributor needs to be able to return a complete list of names to show in the list for a specified project, which will then be filtered by the IDE according to the text typed by the user in the dialog. -Using [File-based or Stub indices](/basics/indexing_and_psi_stubs.md) to obtain matching candidates is highly recommended to improve performance. +Using [File-based or Stub indices](indexing_and_psi_stubs.md) to obtain matching candidates is highly recommended to improve performance. For each name in that list, the contributor needs to provide a list of [`NavigationItem`](upsource:///platform/core-api/src/com/intellij/navigation/NavigationItem.java) instances (typically [`PsiElement`](upsource:///platform/core-api/src/com/intellij/psi/PsiElement.java)), which specify the destinations to jump to when a specific name is selected from the list. **Example:** -- [Custom Language Support Tutorial: Go To Symbol Contributor](/tutorials/custom_language_support/go_to_symbol_contributor.md) +- [Custom Language Support Tutorial: Go To Symbol Contributor](go_to_symbol_contributor.md) \ No newline at end of file diff --git a/reference_guide/custom_language_support/implementing_lexer.md b/topics/reference_guide/custom_language_support/implementing_lexer.md similarity index 93% rename from reference_guide/custom_language_support/implementing_lexer.md rename to topics/reference_guide/custom_language_support/implementing_lexer.md index 8ac0b4cf8..e5f5e8225 100644 --- a/reference_guide/custom_language_support/implementing_lexer.md +++ b/topics/reference_guide/custom_language_support/implementing_lexer.md @@ -1,6 +1,5 @@ ---- -title: Implementing Lexer ---- +[//]: # (title: Implementing Lexer) + The lexer, or [lexical analyzer](https://en.wikipedia.org/wiki/Lexical_analysis), defines how a file's contents are broken into tokens. @@ -42,12 +41,14 @@ Enabling `--charat` option passes the source data for lexing as a [`CharSequence For developing lexers using JFlex, the [GrammarKit plugin](https://plugins.jetbrains.com/plugin/6606-grammar-kit) can be useful. It provides syntax highlighting and other useful features for editing JFlex files. -> **NOTE** Lexers, and in particular JFlex-based lexers, need to be created so that they always match the entire contents of the file, without any gaps between tokens, and generate special tokens for characters which are not valid at their location. + > Lexers, and in particular JFlex-based lexers, need to be created so that they always match the entire contents of the file, without any gaps between tokens, and generate special tokens for characters which are not valid at their location. > Lexers must never abort prematurely because of an invalid character. + > + {type="note"} **Example**: - [`Lexer`](upsource:///plugins/properties/src/com/intellij/lang/properties/parsing/Properties.flex) definition for [Properties language plugin](upsource:///plugins/properties) -- [Custom Language Support Tutorial: Lexer](/tutorials/custom_language_support/lexer_and_parser_definition.md) +- [Custom Language Support Tutorial: Lexer](lexer_and_parser_definition.md) Types of tokens for lexers are defined by instances of [`IElementType`](upsource:///platform/core-api/src/com/intellij/psi/tree/IElementType.java). Many token types common for all languages are defined in the [`TokenType`](upsource:///platform/core-api/src/com/intellij/psi/TokenType.java) interface. @@ -62,4 +63,4 @@ An important feature that can be implemented at the lexer level is mixing langua Suppose a language supports embedding its fragments in another language. In that case, it needs to define the chameleon token types for different types of fragments that can be embedded, and these token types need to implement the [`ILazyParseableElementType`](upsource:///platform/core-api/src/com/intellij/psi/tree/ILazyParseableElementType.java) interface. The enclosing language's lexer needs to return the entire fragment of the embedded language as a single chameleon token, of the type defined by the embedded language. -To parse the contents of the chameleon token, the IDE will call the parser of the embedded language through a call to [`ILazyParseableElementType.parseContents()`](upsource:///platform/core-api/src/com/intellij/psi/tree/ILazyParseableElementType.java). +To parse the contents of the chameleon token, the IDE will call the parser of the embedded language through a call to [`ILazyParseableElementType.parseContents()`](upsource:///platform/core-api/src/com/intellij/psi/tree/ILazyParseableElementType.java). \ No newline at end of file diff --git a/reference_guide/custom_language_support/implementing_parser_and_psi.md b/topics/reference_guide/custom_language_support/implementing_parser_and_psi.md similarity index 96% rename from reference_guide/custom_language_support/implementing_parser_and_psi.md rename to topics/reference_guide/custom_language_support/implementing_parser_and_psi.md index 6ffaa105c..fdcbaa5bd 100644 --- a/reference_guide/custom_language_support/implementing_parser_and_psi.md +++ b/topics/reference_guide/custom_language_support/implementing_parser_and_psi.md @@ -1,6 +1,5 @@ ---- -title: Implementing a Parser and PSI ---- +[//]: # (title: Implementing a Parser and PSI) + Parsing files in IntelliJ Platform is a two-step process. @@ -20,7 +19,7 @@ The top-level node of the PSI tree for a file needs to implement the [`PsiFile`] **Example**: [`ParserDefinition`](upsource:///plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/parsing/PropertiesParserDefinition.java) for [Properties language plugin](upsource:///plugins/properties) -The PSI's lifecycle is described in more detail in [Fundamentals](/platform/fundamentals.md). +The PSI's lifecycle is described in more detail in [Fundamentals](fundamentals.md). The base classes for the PSI implementation, including [`PsiFileBase`](upsource:///platform/core-impl/src/com/intellij/extapi/psi/PsiFileBase.java), the base implementation of [`PsiFile`](upsource:///platform/core-api/src/com/intellij/psi/PsiFile.java), and [`ASTWrapperPsiElement`](upsource:///platform/core-impl/src/com/intellij/extapi/psi/ASTWrapperPsiElement.java), the base implementation of [`PsiElement`](upsource:///platform/core-api/src/com/intellij/psi/PsiElement.java), are provided by *IntelliJ Platform*. @@ -59,7 +58,7 @@ The token set returned from [`ParserDefinition.getCommentTokens()`](upsource:/// To better understand the process of building a PSI tree for a simple expression, you can refer to the following diagram: -![PsiBuilder](img/PsiBuilder.gif) +![PsiBuilder](PsiBuilder.gif) In general, there is no single right way to implement a PSI for a custom language, and the plugin author can choose the PSI structure and set of methods that are the most convenient for the code which uses the PSI (error analysis, refactorings, and so on). However, one base interface needs to be used by a custom language PSI implementation to support features like rename and find usages. @@ -67,7 +66,9 @@ Every element which can be renamed or referenced (a class definition, a method d Several functions which can be used for implementing and using the PSI can be found in the `com.intellij.psi.util` package, and in particular in the [`PsiUtilCore`](upsource:///platform/core-api/src/com/intellij/psi/util/PsiUtilCore.java) and [`PsiTreeUtil`](upsource:///platform/core-api/src/com/intellij/psi/util/PsiTreeUtil.java) classes. -> **TIP** A useful tool for debugging the PSI implementation is the [PsiViewer plugin](https://plugins.jetbrains.com/plugin/227-psiviewer). + > A useful tool for debugging the PSI implementation is the [PsiViewer plugin](https://plugins.jetbrains.com/plugin/227-psiviewer). > It can show you the PSI structure built by your plugin, the properties of every PSI element, and highlight its text range. + > + {type="tip"} -Please see [Indexing and PSI Stubs](/basics/indexing_and_psi_stubs.md) for advanced topics. +Please see [Indexing and PSI Stubs](indexing_and_psi_stubs.md) for advanced topics. \ No newline at end of file diff --git a/reference_guide/custom_language_support/navigation.md b/topics/reference_guide/custom_language_support/navigation.md similarity index 92% rename from reference_guide/custom_language_support/navigation.md rename to topics/reference_guide/custom_language_support/navigation.md index e2c4ae665..dc9655b13 100644 --- a/reference_guide/custom_language_support/navigation.md +++ b/topics/reference_guide/custom_language_support/navigation.md @@ -1,9 +1,10 @@ ---- -title: Navigation ---- +[//]: # (title: Navigation) + -> **WARNING** This API is available starting from 2020.3 and currently in development and thus in experimental state. + > This API is available starting from 2020.3 and currently in development and thus in experimental state. + > + {type="warning"} The _Go to Declaration or Usages_ action is performed in several steps. @@ -15,7 +16,6 @@ such as navigation from `break` keyword to the end of a loop in Java, without sh To provide `PsiElement` for direct navigation, implement and register [`DirectNavigationProvider`](upsource:///platform/core-api/src/com/intellij/navigation/DirectNavigationProvider.java). - ## Symbol Navigation If there is no Direct navigation available under the caret, then the IntelliJ Platform proceeds with `Symbol` navigation. @@ -36,9 +36,8 @@ To provide navigation targets by a `Symbol`, either: [`NavigatableSymbol`](upsource:///platform/core-api/src/com/intellij/navigation/NavigatableSymbol.java) in the `Symbol`. - ## Showing Usages If there are no navigation targets available, then the IntelliJ Platform starts finding usages of the target symbol obtained by resolving a [reference](declarations_and_references.md#references) -or from a [declaration](declarations_and_references.md#declarations). +or from a [declaration](declarations_and_references.md#declarations). \ No newline at end of file diff --git a/reference_guide/custom_language_support/references_and_resolve.md b/topics/reference_guide/custom_language_support/references_and_resolve.md similarity index 84% rename from reference_guide/custom_language_support/references_and_resolve.md rename to topics/reference_guide/custom_language_support/references_and_resolve.md index f7f64c596..00caccdff 100644 --- a/reference_guide/custom_language_support/references_and_resolve.md +++ b/topics/reference_guide/custom_language_support/references_and_resolve.md @@ -1,13 +1,14 @@ ---- -title: References and Resolve ---- +[//]: # (title: References and Resolve) + One of the most important and tricky parts in implementing a custom language PSI is resolving references. Resolving references gives users the ability to navigate from a PSI element usage (accessing a variable, calling a method, etc.) to the declaration of that element (the variable's definition, a method declaration, and so on). This feature is needed in order to support the _Go to Declaration_ action invoked by **Ctrl-B** and **Ctrl-Click**, and it is a prerequisite for implementing the [Find Usages](find_usages.md) action, the [Rename Refactoring](rename_refactoring.md) and [Code Completion](code_completion.md). -> **NOTE** The _Quick Definition_ action is based on the same mechanism, so it becomes automatically available for all references that can be resolved by the language plugin. + > The _Quick Definition_ action is based on the same mechanism, so it becomes automatically available for all references that can be resolved by the language plugin. + > + {type="note"} All PSI elements which work as references (for which the _Go to Declaration_ action applies) need to implement the [`PsiElement.getReference()`](upsource:///platform/core-api/src/com/intellij/psi/PsiElement.java) method and to return a [`PsiReference`](upsource:///platform/core-api/src/com/intellij/psi/PsiReference.java) implementation from that method. @@ -17,22 +18,27 @@ An element can also contain multiple references (for example, a string literal c The primary method of the [`PsiReference`](upsource:///platform/core-api/src/com/intellij/psi/PsiReference.java) interface is `resolve()`, which returns the element to which the reference points, or `null` if it was not possible to resolve the reference to a valid element (for example, should it point to an undefined class). The resolved element should implement the [`PsiNamedElement`](upsource:///platform/core-api/src/com/intellij/psi/PsiNamedElement.java) interface. -> **NOTE** While the referencing element and the referenced element both may have a name, only the element which **introduces** the name (e.g., the definition `int x = 42`) needs to implement the [`PsiNamedElement`](upsource:///platform/core-api/src/com/intellij/psi/PsiNamedElement.java) interface. + > While the referencing element and the referenced element both may have a name, only the element which **introduces** the name (e.g., the definition `int x = 42`) needs to implement the [`PsiNamedElement`](upsource:///platform/core-api/src/com/intellij/psi/PsiNamedElement.java) interface. > The referencing element at the point of usage (e.g., the `x` in the expression `x + 1`) should not implement `PsiNamedElement` since it does not _have_ a name. + > + {type="note"} -> **TIP** In order to enable more advanced IntelliJ functionality, prefer implementing [`PsiNameIdentifierOwner`](upsource:///platform/core-api/src/com/intellij/psi/PsiNameIdentifierOwner.java) over [`PsiNamedElement`](upsource:///platform/core-api/src/com/intellij/psi/PsiNamedElement.java) where possible. + > In order to enable more advanced IntelliJ functionality, prefer implementing [`PsiNameIdentifierOwner`](upsource:///platform/core-api/src/com/intellij/psi/PsiNameIdentifierOwner.java) over [`PsiNamedElement`](upsource:///platform/core-api/src/com/intellij/psi/PsiNamedElement.java) where possible. + > + {type="tip"} A counterpart to the `resolve()` method is `isReferenceTo()`, which checks if the reference resolves to the specified element. The latter method can be implemented by calling `resolve()` and comparing the result with the passed PSI element. Still, additional optimizations are possible (for example, performing the tree walk only if the element text is equal to the text of the reference). - **Examples**: - [Reference](upsource:///plugins/properties/src/com/intellij/lang/properties/ResourceBundleReference.java) to a ResourceBundle in the [Properties language plugin](upsource:///plugins/properties) -- [Custom Language Support Tutorial: Reference Contributor](/tutorials/custom_language_support/reference_contributor.md) +- [Custom Language Support Tutorial: Reference Contributor](reference_contributor.md) -> **TIP** To optimize `getReferences()` performance, consider implementing [`HintedReferenceHost`](upsource:///platform/core-api/src/com/intellij/psi/HintedReferenceHost.java) to provide additional hints. -> Please see also _Cache Results of Heavy Computations_ in [Working with PSI efficiently](/reference_guide/performance/performance.md#working-with-psi-efficiently). + > To optimize `getReferences()` performance, consider implementing [`HintedReferenceHost`](upsource:///platform/core-api/src/com/intellij/psi/HintedReferenceHost.java) to provide additional hints. +> Please see also _Cache Results of Heavy Computations_ in [Working with PSI efficiently](performance.md#working-with-psi-efficiently). + > + {type="tip"} There are a set of interfaces that can be used as a base for implementing resolve support, namely the [`PsiScopeProcessor`](upsource:///platform/core-api/src/com/intellij/psi/scope/PsiScopeProcessor.java) interface and the [`PsiElement.processDeclarations()`](upsource:///platform/core-api/src/com/intellij/psi/PsiElement.java) method. These interfaces have several extra complexities that are unnecessary for most custom languages (like support for substituting Java generics types). @@ -54,4 +60,4 @@ The implementation of resolve based on the standard helper classes contains the An extension of the [`PsiReference`](upsource:///platform/core-api/src/com/intellij/psi/PsiReference.java) interface, which allows a reference to resolve to multiple targets, is the [`PsiPolyVariantReference`](upsource:///platform/core-api/src/com/intellij/psi/PsiPolyVariantReference.java) interface. The targets to which the reference resolves are returned from the `multiResolve()` method. The _Go to Declaration_ action for such references allows the user to choose a navigation target. -The implementation of `multiResolve()` can be also based on [`PsiScopeProcessor`](upsource:///platform/core-api/src/com/intellij/psi/scope/PsiScopeProcessor.java), and can collect all valid targets for the reference instead of stopping when the first valid target is found. +The implementation of `multiResolve()` can be also based on [`PsiScopeProcessor`](upsource:///platform/core-api/src/com/intellij/psi/scope/PsiScopeProcessor.java), and can collect all valid targets for the reference instead of stopping when the first valid target is found. \ No newline at end of file diff --git a/reference_guide/custom_language_support/registering_file_type.md b/topics/reference_guide/custom_language_support/registering_file_type.md similarity index 82% rename from reference_guide/custom_language_support/registering_file_type.md rename to topics/reference_guide/custom_language_support/registering_file_type.md index 3cc4d0b88..9f0c1df5e 100644 --- a/reference_guide/custom_language_support/registering_file_type.md +++ b/topics/reference_guide/custom_language_support/registering_file_type.md @@ -1,6 +1,5 @@ ---- -title: Registering a File Type ---- +[//]: # (title: Registering a File Type) + The first step in developing a custom language plugin is registering a file type associated with the language. @@ -11,13 +10,15 @@ In 2020.2, support for mapping via _hashbang_ is available via `hashBangs` attri A custom language file type is a class derived from [`LanguageFileType`](upsource:///platform/core-api/src/com/intellij/openapi/fileTypes/LanguageFileType.java), which passes a [`Language`](upsource:///platform/core-api/src/com/intellij/lang/Language.java) subclass to its base class constructor. To register a file type, the plugin developer provides a subclass of [`FileTypeFactory`](upsource:///platform/platform-api/src/com/intellij/openapi/fileTypes/FileTypeFactory.java), which is registered via the `com.intellij.fileTypeFactory` extension point. -> **NOTE** When targeting 2019.2 or later only, using `com.intellij.fileType` extension point is preferred to using dedicated `FileTypeFactory`. + > When targeting 2019.2 or later only, using `com.intellij.fileType` extension point is preferred to using dedicated `FileTypeFactory`. + > + {type="note"} **Examples**: - [`LanguageFileType`](upsource:///platform/core-api/src/com/intellij/openapi/fileTypes/LanguageFileType.java) subclass in [Properties language plugin](upsource:///plugins/properties/properties-psi-api/src/com/intellij/lang/properties/PropertiesFileType.java) -- [Custom Language Support Tutorial: Language and File Type](/tutorials/custom_language_support/language_and_filetype.md) +- [Custom Language Support Tutorial: Language and File Type](language_and_filetype.md) -To verify that the file type is registered correctly, you can implement the [`LanguageFileType.getIcon()`](upsource:///platform/core-api/src/com/intellij/openapi/fileTypes/LanguageFileType.java) method and verify that the correct icon (see [Working with Icons and Images](/reference_guide/work_with_icons_and_images.md)) is displayed for files associated with your file type. +To verify that the file type is registered correctly, you can implement the [`LanguageFileType.getIcon()`](upsource:///platform/core-api/src/com/intellij/openapi/fileTypes/LanguageFileType.java) method and verify that the correct icon (see [Working with Icons and Images](work_with_icons_and_images.md)) is displayed for files associated with your file type. If you want IDEs to show a hint prompting users that your plugin supports a specific file type, see [Plugin Recommendations](https://plugins.jetbrains.com/docs/marketplace/intellij-plugin-recommendations.html). diff --git a/reference_guide/custom_language_support/rename_refactoring.md b/topics/reference_guide/custom_language_support/rename_refactoring.md similarity index 95% rename from reference_guide/custom_language_support/rename_refactoring.md rename to topics/reference_guide/custom_language_support/rename_refactoring.md index 4705ebebc..49db7e3a9 100644 --- a/reference_guide/custom_language_support/rename_refactoring.md +++ b/topics/reference_guide/custom_language_support/rename_refactoring.md @@ -1,6 +1,5 @@ ---- -title: Rename Refactoring ---- +[//]: # (title: Rename Refactoring) + The Rename refactoring operation is quite similar to that of [Find Usages](find_usages.md). @@ -13,7 +12,7 @@ Thus, surprisingly, the easiest way to get the replacement node is to create a d **Examples:** - [`setName()`](upsource:///plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/psi/impl/PropertyImpl.java) implementation for a [Properties language plugin](upsource:///plugins/properties) -- [Custom Language Support Tutorial: Reference Contributor](/tutorials/custom_language_support/reference_contributor.md) +- [Custom Language Support Tutorial: Reference Contributor](reference_contributor.md) To disable renaming for specific elements, implement `com.intellij.openapi.util.Condition` for PsiElement of type `T` and register it in `com.intellij.vetoRenameCondition` extension point. @@ -25,7 +24,6 @@ Implementations of `NamesValidator` are registered in the `com.intellij.lang.nam **Example**: [`PropertiesNamesValidator`](upsource:///plugins/properties/src/com/intellij/lang/properties/PropertiesNamesValidator.java) for [Properties language plugin](upsource:///plugins/properties) - ### Custom Rename UI and Workflow Further customization of the Rename refactoring processing is possible on multiple levels. Providing a custom implementation of the [`RenameHandler`](upsource:///platform/lang-api/src/com/intellij/refactoring/rename/RenameHandler.java) interface allows you to entirely replace the UI and workflow of the rename refactoring, and also to support renaming something which is not a [`PsiElement`](upsource:///platform/core-api/src/com/intellij/psi/PsiElement.java) at all. @@ -43,4 +41,4 @@ This allows you to: * etc. **Example**: -[`RenamePsiElementProcessor`](upsource:///plugins/properties/src/com/intellij/lang/properties/refactoring/rename/RenamePropertyProcessor.java) for renaming a property in [Properties plugin language](upsource:///plugins/properties) +[`RenamePsiElementProcessor`](upsource:///plugins/properties/src/com/intellij/lang/properties/refactoring/rename/RenamePropertyProcessor.java) for renaming a property in [Properties plugin language](upsource:///plugins/properties) \ No newline at end of file diff --git a/reference_guide/custom_language_support/safe_delete_refactoring.md b/topics/reference_guide/custom_language_support/safe_delete_refactoring.md similarity index 96% rename from reference_guide/custom_language_support/safe_delete_refactoring.md rename to topics/reference_guide/custom_language_support/safe_delete_refactoring.md index fd7986bdd..bd7c8cc3d 100644 --- a/reference_guide/custom_language_support/safe_delete_refactoring.md +++ b/topics/reference_guide/custom_language_support/safe_delete_refactoring.md @@ -1,6 +1,5 @@ ---- -title: Safe Delete Refactoring ---- +[//]: # (title: Safe Delete Refactoring) + The _Safe Delete_ refactoring also builds on the same [Find Usages](find_usages.md) framework as [Rename Refactoring](rename_refactoring.md). @@ -18,11 +17,10 @@ In addition to that, to support _Safe Delete_, a plugin needs to implement two t subclasses for which _Safe Delete_ is available. Deleting PSI elements is implemented by deleting the underlying AST nodes from the AST tree (which, in turn, causes the text ranges corresponding to the AST nodes to be deleted from the document). - **Example:** [`delete()`](upsource:///plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/psi/impl/PropertyImpl.java) implementation for a Property in [Properties language plugin](upsource:///plugins/properties/) If needed, it's possible to further customize how _Safe Delete_ is performed for a particular type of element (e.g., how references are searched) via [`SafeDeleteProcessorDelegate`](upsource:///platform/lang-impl/src/com/intellij/refactoring/safeDelete/SafeDeleteProcessorDelegate.java). **Example**: -[`SafeDeleteProcessorDelegate`](upsource:///plugins/properties/src/com/intellij/lang/properties/refactoring/PropertiesFilesSafeDeleteProcessor.java) implementation for [Properties language plugin](upsource:///plugins/properties) +[`SafeDeleteProcessorDelegate`](upsource:///plugins/properties/src/com/intellij/lang/properties/refactoring/PropertiesFilesSafeDeleteProcessor.java) implementation for [Properties language plugin](upsource:///plugins/properties) \ No newline at end of file diff --git a/reference_guide/custom_language_support/structure_view.md b/topics/reference_guide/custom_language_support/structure_view.md similarity index 95% rename from reference_guide/custom_language_support/structure_view.md rename to topics/reference_guide/custom_language_support/structure_view.md index 723177dec..d304434f4 100644 --- a/reference_guide/custom_language_support/structure_view.md +++ b/topics/reference_guide/custom_language_support/structure_view.md @@ -1,6 +1,5 @@ ---- -title: Structure View ---- +[//]: # (title: Structure View) + The Structure View implementation used for a specific file type can be customized on many levels. @@ -11,7 +10,7 @@ The starting point for the structure view is the [`PsiStructureViewFactory`](ups **Examples:** - [`PsiStructureViewFactory`](upsource:///plugins/properties/src/com/intellij/lang/properties/structureView/PropertiesStructureViewBuilderFactory.java) for [Properties language plugin](upsource:///plugins/properties) -- [Custom Language Support Tutorial: Structure View](/tutorials/custom_language_support/structure_view_factory.md) +- [Custom Language Support Tutorial: Structure View](structure_view_factory.md) To reuse the *IntelliJ Platform* implementation of the [`StructureView`](upsource:///platform/editor-ui-api/src/com/intellij/ide/structureView/StructureView.java), the plugin returns a [`TreeBasedStructureViewBuilder`](upsource:///platform/editor-ui-api/src/com/intellij/ide/structureView/TreeBasedStructureViewBuilder.java) from its [`PsiStructureViewFactory.getStructureViewBuilder()`](upsource:///platform/editor-ui-api/src/com/intellij/lang/PsiStructureViewFactory.java) method. As the builder model, the plugin can specify a subclass of [`TextEditorBasedStructureViewModel`](upsource:///platform/editor-ui-api/src/com/intellij/ide/structureView/TextEditorBasedStructureViewModel.java), and by overriding methods of this subclass, it customizes the structure view for a specific language. @@ -19,7 +18,6 @@ As the builder model, the plugin can specify a subclass of [`TextEditorBasedStru **Example**: [`StructureViewModel`](upsource:///plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/structureView/PropertiesFileStructureViewModel.java) for [Properties language plugin](upsource:///plugins/properties) - The main method to override is `getRoot()`, which returns the instance of a class implementing the [`StructureViewTreeElement`](upsource:///platform/editor-ui-api/src/com/intellij/ide/structureView/StructureViewTreeElement.java) interface. There exists no standard implementation of this interface, so a plugin will need to implement it completely. @@ -32,4 +30,4 @@ The latter method returns an array of `PsiElement`\-derived classes, which can b It is used to select the Structure View item matching the cursor position when the structure view is first opened or when the _Autoscroll from source_ option is enabled. **Example:** -[`StructureViewTreeElement`](upsource:///plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/editor/PropertyStructureViewElement.java) for [Properties language plugin](upsource:///plugins/properties/) +[`StructureViewTreeElement`](upsource:///plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/editor/PropertyStructureViewElement.java) for [Properties language plugin](upsource:///plugins/properties/) \ No newline at end of file diff --git a/reference_guide/custom_language_support/surround_with.md b/topics/reference_guide/custom_language_support/surround_with.md similarity index 97% rename from reference_guide/custom_language_support/surround_with.md rename to topics/reference_guide/custom_language_support/surround_with.md index 3fc8861fd..fe6c47978 100644 --- a/reference_guide/custom_language_support/surround_with.md +++ b/topics/reference_guide/custom_language_support/surround_with.md @@ -1,6 +1,5 @@ ---- -title: Surround With ---- +[//]: # (title: Surround With) + To support the _Surround With_ action, the plugin needs to register one or more implementations of the [`SurroundDescriptor`](upsource:///platform/lang-api/src/com/intellij/lang/surroundWith/SurroundDescriptor.java) interface in the `com.intellij.lang.surroundDescriptor` extension point. @@ -12,4 +11,4 @@ Then it calls the [`Surrounder.isApplicable()`](upsource:///platform/lang-api/sr Once the user selects a specific surrounder from the popup menu, the [`Surrounder.surroundElements()`](upsource:///platform/lang-api/src/com/intellij/lang/surroundWith/Surrounder.java) method is used to execute the surround action. **Example:** -[`SurroundDescriptor`](upsource:///plugins/groovy/src/org/jetbrains/plugins/groovy/lang/surroundWith/GroovySurroundDescriptor.java) for Groovy plugin +[`SurroundDescriptor`](upsource:///plugins/groovy/src/org/jetbrains/plugins/groovy/lang/surroundWith/GroovySurroundDescriptor.java) for Groovy plugin \ No newline at end of file diff --git a/reference_guide/custom_language_support/symbols.md b/topics/reference_guide/custom_language_support/symbols.md similarity index 90% rename from reference_guide/custom_language_support/symbols.md rename to topics/reference_guide/custom_language_support/symbols.md index a132956de..df5ec4bfa 100644 --- a/reference_guide/custom_language_support/symbols.md +++ b/topics/reference_guide/custom_language_support/symbols.md @@ -1,9 +1,10 @@ ---- -title: Symbols ---- +[//]: # (title: Symbols) + -> **WARNING** This API is available starting from 2020.3 and currently in development and thus in experimental state. + > This API is available starting from 2020.3 and currently in development and thus in experimental state. + > + {type="warning"} A symbol is a semantic element in some model, e.g., language model or framework model. The IntelliJ Platform uses [`Symbol`](upsource:///platform/core-api/src/com/intellij/model/Symbol.java) to represent symbols, @@ -23,9 +24,8 @@ A `Symbol` is not required to be backed by a `PsiElement`, and it is incorrect t - Database column is a symbol defined by data source (not backed by a `PsiElement`) and not bound to a `Project` since DB elements might be shared between projects. - ## Lifecycle The `Symbol` instance is expected to stay valid within a single read action, which means it's safe to pass the instance to different APIs. A `Symbol` instance should not be referenced between read actions. -One should create a pointer via `Symbol.createPointer()` in the current read action, and then call `Pointer.dereference()` to obtain a `Symbol` instance in the subsequent read action. +One should create a pointer via `Symbol.createPointer()` in the current read action, and then call `Pointer.dereference()` to obtain a `Symbol` instance in the subsequent read action. \ No newline at end of file diff --git a/reference_guide/custom_language_support/syntax_highlighting_and_error_highlighting.md b/topics/reference_guide/custom_language_support/syntax_highlighting_and_error_highlighting.md similarity index 89% rename from reference_guide/custom_language_support/syntax_highlighting_and_error_highlighting.md rename to topics/reference_guide/custom_language_support/syntax_highlighting_and_error_highlighting.md index f0b16cd05..8e13e93cb 100644 --- a/reference_guide/custom_language_support/syntax_highlighting_and_error_highlighting.md +++ b/topics/reference_guide/custom_language_support/syntax_highlighting_and_error_highlighting.md @@ -1,6 +1,5 @@ ---- -title: Syntax Highlighting and Error Highlighting ---- +[//]: # (title: Syntax Highlighting and Error Highlighting) + The class used to specify how a particular range of text should be highlighted is called [`TextAttributesKey`](upsource:///platform/core-api/src/com/intellij/openapi/editor/colors/TextAttributesKey.java). @@ -16,12 +15,16 @@ The _Export to HTML_ feature uses the same syntax highlighting mechanism as the **Examples**: - [`ColorSettingsPage`](upsource:///plugins/properties/src/com/intellij/openapi/options/colors/pages/PropertiesColorsPage.java) for [Properties language plugin](upsource:///plugins/properties/) -- [Custom Language Support Tutorial: Color Settings Page](/tutorials/custom_language_support/syntax_highlighter_and_color_settings_page.md) +- [Custom Language Support Tutorial: Color Settings Page](syntax_highlighter_and_color_settings_page.md) -> **NOTE** New functionality about Language Defaults and support for additional color schemes are detailed in [Color Scheme Management](/reference_guide/color_scheme_management.md). + > New functionality about Language Defaults and support for additional color schemes are detailed in [Color Scheme Management](color_scheme_management.md). + > + {type="note"} -> **TIP** To force re-highlighting, use + > To force re-highlighting, use > [`DaemonCodeAnalyzer.restart()`](upsource:///platform/analysis-api/src/com/intellij/codeInsight/daemon/DaemonCodeAnalyzer.java). + > + {type="tip"} The syntax and error highlighting are performed on multiple levels: Lexer, Parser, and (External) Annotator. @@ -33,7 +36,7 @@ For highlighting lexer errors, the standard `TextAttributesKey` for bad characte **Examples:** - [`SyntaxHighlighter`](upsource:///plugins/properties/properties-psi-api/src/com/intellij/lang/properties/PropertiesHighlighter.java) implementation for [Properties language plugin](upsource:///plugins/properties/) -- [Custom Language Support Tutorial: Syntax Highlighter](/tutorials/custom_language_support/syntax_highlighter_and_color_settings_page.md) +- [Custom Language Support Tutorial: Syntax Highlighter](syntax_highlighter_and_color_settings_page.md) ## Parser @@ -49,7 +52,9 @@ Annotators can analyze not only the syntax, but also the semantics using PSI, an The annotator can also provide quick fixes to problems it detects. When the file is changed, the annotator is called incrementally to process only changed elements in the PSI tree. -> **NOTE** See also [Code Inspections](code_inspections_and_intentions.md) which offer a more fine-grained control and some additional features. + > See also [Code Inspections](code_inspections_and_intentions.md) which offer a more fine-grained control and some additional features. + > + {type="note"} ### Errors/Warning See [Inspections](https://jetbrains.design/intellij/text/inspections/) topic in _IntelliJ Platform UI Guidelines_ on how to write message texts for highlighting/quick fixes. @@ -75,7 +80,7 @@ In previous versions, call `AnnotationHolder.createInfoAnnotation()` with an emp **Examples:** - [`Annotator`](upsource:///plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/PropertiesAnnotator.java) for [Properties language plugin](upsource:///plugins/properties/) -- [Custom Language Support Tutorial: Annotator](/tutorials/custom_language_support/annotator.md) +- [Custom Language Support Tutorial: Annotator](annotator.md) ## External Tool diff --git a/reference_guide/editors.md b/topics/reference_guide/editors.md similarity index 84% rename from reference_guide/editors.md rename to topics/reference_guide/editors.md index 718f76b43..e9aa08d1d 100644 --- a/reference_guide/editors.md +++ b/topics/reference_guide/editors.md @@ -1,14 +1,13 @@ ---- -title: Editors ---- +[//]: # (title: Editors) + This section covers working with text in the IntelliJ Platform editor. It is presented in two major sections: -* [Editor basics tutorial](/tutorials/editor_basics.md) +* [Editor basics tutorial](editor_basics.md) * Using the action system to access a caret placed in a document open in an editor. * Accessing position information about a caret in an editor: coordinate systems and offsets. * Handling actions activated by keystroke events in the editor. * [Multiple carets](multiple_carets.md) * Working with multiple, independent, carets in one editor. - * How multiple carets affect core functionality, editor actions, typing actions, and code insight actions. + * How multiple carets affect core functionality, editor actions, typing actions, and code insight actions. \ No newline at end of file diff --git a/reference_guide/frameworks_and_external_apis/external_builder_api.md b/topics/reference_guide/frameworks_and_external_apis/external_builder_api.md similarity index 96% rename from reference_guide/frameworks_and_external_apis/external_builder_api.md rename to topics/reference_guide/frameworks_and_external_apis/external_builder_api.md index 84fb1185b..8f825a486 100644 --- a/reference_guide/frameworks_and_external_apis/external_builder_api.md +++ b/topics/reference_guide/frameworks_and_external_apis/external_builder_api.md @@ -1,10 +1,11 @@ ---- -title: External Builder API and Plugins ---- +[//]: # (title: External Builder API and Plugins) + -> **NOTE** Adding JPS support to your plugin requires Java plugin to be present for it to work. -> Please see [Plugin Dependencies](/basics/plugin_structure/plugin_dependencies.md) on how to set up your plugin with required dependency. + > Adding JPS support to your plugin requires Java plugin to be present for it to work. +> Please see [Plugin Dependencies](plugin_dependencies.md) on how to set up your plugin with required dependency. + > + {type="note"} ### External Build Process Workflow @@ -68,7 +69,6 @@ In that case, you may fix the port number by adding the following VM option to t -Dcompiler.process.debug.port= ``` - **If your test IDE is IntelliJ IDEA 15.0 or older** Start IDE with your plugin with the following VM option: @@ -77,7 +77,6 @@ Start IDE with your plugin with the following VM option: -Dcompiler.process.debug.port= ``` - After that, every time compilation is run in the test IDE, the build process will wait for debugger connection on this port and then proceed. In a working copy of IDE, a "Remote" run configuration should be created and pointed to this port. Specifying port "-1" will disable debugging mode. @@ -99,7 +98,6 @@ Please capture a couple of snapshots for the situations you believe the build sh Please create an issue in the issue tracker and attach generated \*.snapshot files to it or upload them as [described here](https://intellij-support.jetbrains.com/hc/en-us/articles/206869619) and specify links in the issue. Please also provide details about the memory and other VM settings for the build process you were using. - ### Accessing External Build Process' Logs The log file is located under the directory: @@ -125,4 +123,4 @@ In that case, you need to extend the JPS model (use `JpsOsmorcModuleExtension` a If your compiler isn't involved in the compilation of an existing [`BuildTarget`](upsource:///jps/jps-builders/src/org/jetbrains/jps/builders/BuildTarget.java), you need to create a new implementation of `BuildTarget` and `BuildTargetType`. Also, register an implementation of [`BuildTargetScopeProvider`](upsource:///java/compiler/impl/src/com/intellij/compiler/impl/BuildTargetScopeProvider.java) extension on the IDE side to add required targets to the build scope. -The builder implementation should extend either [`TargetBuilder`](upsource:///jps/jps-builders/src/org/jetbrains/jps/incremental/TargetBuilder.java) or [`ModuleLevelBuilder`](upsource:///jps/jps-builders/src/org/jetbrains/jps/incremental/ModuleLevelBuilder.java) class and should be created using [`BuilderService`](upsource:///jps/jps-builders/src/org/jetbrains/jps/incremental/BuilderService.java) extension. +The builder implementation should extend either [`TargetBuilder`](upsource:///jps/jps-builders/src/org/jetbrains/jps/incremental/TargetBuilder.java) or [`ModuleLevelBuilder`](upsource:///jps/jps-builders/src/org/jetbrains/jps/incremental/ModuleLevelBuilder.java) class and should be created using [`BuilderService`](upsource:///jps/jps-builders/src/org/jetbrains/jps/incremental/BuilderService.java) extension. \ No newline at end of file diff --git a/reference_guide/frameworks_and_external_apis/external_system_integration.md b/topics/reference_guide/frameworks_and_external_apis/external_system_integration.md similarity index 92% rename from reference_guide/frameworks_and_external_apis/external_system_integration.md rename to topics/reference_guide/frameworks_and_external_apis/external_system_integration.md index 4f17ff9d4..6b701ce70 100644 --- a/reference_guide/frameworks_and_external_apis/external_system_integration.md +++ b/topics/reference_guide/frameworks_and_external_apis/external_system_integration.md @@ -1,6 +1,5 @@ ---- -title: External System Integration ---- +[//]: # (title: External System Integration) + This page provides high-level overview of *External System* sub-system. @@ -21,15 +20,14 @@ That means that we can separate external system-specific logic and general IDE p External system wrapper is required to be able to build project info on the basis of the given external system config. That information is built using in terms of [`DataNode`](upsource:///platform/external-system-api/src/com/intellij/openapi/externalSystem/model/DataNode.java), [`Key`](upsource:///platform/external-system-api/src/com/intellij/openapi/externalSystem/model/Key.java) and [`ExternalEntityData`](upsource:///platform/external-system-api/src/com/intellij/openapi/externalSystem/model/project/ExternalEntityData.java). -![DataNode](/reference_guide/img/data-node.png) +![DataNode](data-node.png) Here *DataNode* class is just a holder for the target data (data type is defined by the *Key*). Multiple DataNode objects might be organized in directed graph where every edge identifies parent-child relation. For example, simple one-module project might look as below: -![DataNode Example](/reference_guide/img/data-node-example.png) - +![DataNode Example](data-node-example.png) **Consequence** The IDE provides a set of built-in *Key*s and *ExternalEntityData*s but any external system integration or third-party plugin developer might enhance project data by defining her own *Key* and *ExternalEntityData* and storing them at a child of appropriate *DataNode*. @@ -64,14 +62,18 @@ Note that [`AbstractExternalProjectImportBuilder`](upsource:///java/idea-ui/src/ It's possible to configure external system integration to automatically refresh project structure when external project's config files are modified. -> **TIP** Since 2020.1, auto-import cannot be disabled by user. + > Since 2020.1, auto-import cannot be disabled by user. + > + {type="tip"} ### Auto-Import for `ExternalSystemManager` implementation Describe project's settings files to track by having external system `ExternalSystemManager` implement [`ExternalSystemAutoImportAware`](upsource:///platform/external-system-api/src/com/intellij/openapi/externalSystem/ExternalSystemAutoImportAware.java). -> **NOTE** `ExternalSystemAutoImportAware.getAffectedExternalProjectPath()` is called quite often, that’s why it’s expected to return control as soon as possible. + > `ExternalSystemAutoImportAware.getAffectedExternalProjectPath()` is called quite often, that’s why it’s expected to return control as soon as possible. > Helper `CachingExternalSystemAutoImportAware` class might be used for caching, i.e. `ExternalSystemManager` which implements `ExternalSystemAutoImportAware` can have a field like `new CachingExternalSystemAutoImportAware(new MyExternalSystemAutoImportAware())` and delegate `ExternalSystemAutoImportAware.getAffectedExternalProjectPath()` calls to it. + > + {type="note"} ### Auto-Import for Standalone External Systems @@ -79,26 +81,26 @@ Some external systems don’t have `ExternalSystemManager` (e.g., Maven), but th For this, implement `ExternalSystemProjectAware` interface that describes settings files for tracking and an action to reload project model. Then register the instance with `ExternalSystemProjectTracker` to start tracking. -> **NOTE** Multiple `ExternalSystemProjectAware` instances can correspond to a single external system. + > Multiple `ExternalSystemProjectAware` instances can correspond to a single external system. > It allows performing project reload differently depending on the set of settings files (project aware per settings file, per module, per external project, etc.). - + > + {type="note"} ### Icon for Reload Notification Since 2020.1, the icon for reload notification can be specified per external system. Implement `ExternalSystemIconProvider` and register via `com.intellij.externalIconProvider` extension point in `plugin.xml`. Alternatively, set `reloadIcon` field external system implements `ExternalSystemIconProvider` directly. - ## Settings The general idea is that all external system settings controls are represented by implementations of [`ExternalSystemSettingsControl`](upsource:///platform/external-system-impl/src/com/intellij/openapi/externalSystem/util/ExternalSystemSettingsControl.java) interface. There are also external system project-local settings and global external system settings. So, basically particular external system settings UI looks as below: -![Configurable](/reference_guide/img/configurable.png) +![Configurable](configurable.png) It's recommended to extend from [`AbstractExternalProjectSettingsControl`](upsource:///platform/external-system-impl/src/com/intellij/openapi/externalSystem/service/settings/AbstractExternalProjectSettingsControl.java) for implementing project-level settings control as it already handles some of them. Similar approach is used for providing 'import from external system' UI - implementation is expected to extend [`AbstractImportFromExternalSystemControl`](upsource:///java/idea-ui/src/com/intellij/openapi/externalSystem/service/settings/AbstractImportFromExternalSystemControl.java) and it has not linked external projects list but target external project path control: -![Import from external system](/reference_guide/img/import.png) +![Import from external system](import.png) \ No newline at end of file diff --git a/reference_guide/frameworks_and_external_apis/spring_api.md b/topics/reference_guide/frameworks_and_external_apis/spring_api.md similarity index 91% rename from reference_guide/frameworks_and_external_apis/spring_api.md rename to topics/reference_guide/frameworks_and_external_apis/spring_api.md index 8bc71f0c1..70311a8be 100644 --- a/reference_guide/frameworks_and_external_apis/spring_api.md +++ b/topics/reference_guide/frameworks_and_external_apis/spring_api.md @@ -1,6 +1,5 @@ ---- -title: Spring API ---- +[//]: # (title: Spring API) + Spring API allows 3rd party plugins to re-use, integrate with or extend existing Spring Framework support in IntelliJ IDEA. @@ -11,8 +10,10 @@ To develop plugins, you will need to use _IntelliJ IDEA Ultimate Edition_ versio ## Setting up IntelliJ Platform SDK -> **NOTE** This applies to [Plugin DevKit](/basics/getting_started/using_dev_kit.md) projects only. -> For [Gradle](/tutorials/build_system.md) projects, simply add dependency to bundled Spring plugin `com.intellij.spring`. + > This applies to [Plugin DevKit](using_dev_kit.md) projects only. +> For [Gradle](gradle_build_system.md) projects, simply add dependency to bundled Spring plugin `com.intellij.spring`. + > + {type="note"} ### New SDK Please create an IntelliJ Platform SDK to include all minimum required files. @@ -50,11 +51,17 @@ Hierarchies can be modeled by depending on another fileset (possibly from anothe As an API-user, you will usually prefer working with `SpringModel`, which is built on top of fileset(s). ## API Updates -> **NOTE** 2017.3: `LocalXmlModel#setActiveProfiles` & `LocalAnnotationModel#setActiveProfiles` have been deprecated and will be removed in 2018.1. + > 2017.3: `LocalXmlModel#setActiveProfiles` & `LocalAnnotationModel#setActiveProfiles` have been deprecated and will be removed in 2018.1. + > + {type="note"} -> **NOTE** Starting with 2016.2, the internal representation of bean _type_ has been changed from `PsiClass` to `PsiType`, please note deprecations. + > Starting with 2016.2, the internal representation of bean _type_ has been changed from `PsiClass` to `PsiType`, please note deprecations. + > + {type="note"} -> **NOTE** Some core classes have been changed in 14(.1); please see "_Version 14(.1)_" notes for info on how to replace existing API-calls. + > Some core classes have been changed in 14(.1); please see "_Version 14(.1)_" notes for info on how to replace existing API-calls. + > + {type="note"} ## How Do I... @@ -130,7 +137,6 @@ Use the following template: GenericAttributeValue getMyAttributeName(); ``` - ### Code Configuration #### Add Reference to Spring Bean in JamElement @@ -166,13 +172,14 @@ Use `com.intellij.spring.facet.SpringConfigurator` to provide "automatic" config Please do not reference bean icons from `SpringApiIcons` directly, but use `SpringPresentationProvider` to re-use unified icon/bean name. See `SpringBeansPsiElementCellRenderer` for popup/list renderer. - ## Spring Boot _2018.1_ Spring Boot API allows extending/accessing Spring Boot specific support in the IDE. -> **WARNING** While we try to maintain compatibility, please be prepared for a less strict policy. + > While we try to maintain compatibility, please be prepared for a less strict policy. + > + {type="warning"} ### Setting up Please perform these steps _additionally_ to setting up Spring API support (see [here](#setting-up-intellij-platform-sdk)): @@ -184,7 +191,7 @@ Please perform these steps _additionally_ to setting up Spring API support (see * add to _sourcepath_ * `$IDEA_HOME$/lib/src/src_spring-boot-openapi.zip` -### plugin.xml +### Update plugin.xml Add `com.intellij.spring.boot` to your `plugin.xml` to require "Spring Boot" plugin to be activated. All available extension points are provided under `com.intellij.spring.boot` prefix. @@ -208,4 +215,4 @@ requires `spring-boot-initializr.jar` _2018.2_ - requires `spring-boot-run.jar` Use EP `com.intellij.spring.boot.run.endpoint` to add custom actuator endpoint tabs. -Any settings should be exposed in "Spring Boot" settings tab via `com.intellij.spring.boot.run.endpointTabConfigurable` EP. +Any settings should be exposed in "Spring Boot" settings tab via `com.intellij.spring.boot.run.endpointTabConfigurable` EP. \ No newline at end of file diff --git a/reference_guide/frameworks_and_external_apis/xml_dom_api.md b/topics/reference_guide/frameworks_and_external_apis/xml_dom_api.md similarity index 98% rename from reference_guide/frameworks_and_external_apis/xml_dom_api.md rename to topics/reference_guide/frameworks_and_external_apis/xml_dom_api.md index 948bea2cc..cd2cb64cc 100644 --- a/reference_guide/frameworks_and_external_apis/xml_dom_api.md +++ b/topics/reference_guide/frameworks_and_external_apis/xml_dom_api.md @@ -1,6 +1,5 @@ ---- -title: XML DOM API ---- +[//]: # (title: XML DOM API) + @@ -81,7 +80,9 @@ interface Bar extends com.intellij.util.xml.DomElement { Next, you should create a [`DomFileDescription`](upsource:///xml/dom-openapi/src/com/intellij/util/xml/DomFileDescription.java) object, pass to its constructor the root tag name and root element interface, and register it with extension point `com.intellij.dom.fileDescription`. -> **NOTE** If your plugin targets 2019.1 or later, please use extension point `com.intellij.dom.fileMetaData` instead and specify `rootTagName` and `domVersion`/`stubVersion` in `plugin.xml`. + > If your plugin targets 2019.1 or later, please use extension point `com.intellij.dom.fileMetaData` instead and specify `rootTagName` and `domVersion`/`stubVersion` in `plugin.xml`. + > + {type="note"} You can now get the file element from [`DomManager`](upsource:///xml/dom-openapi/src/com/intellij/util/xml/DomManager.java). To get the "239" value, you only have to write the following code: @@ -115,7 +116,6 @@ Finally, we'll see how to easily create an UI editor for DOM model elements. ## Building the Model - ### Tag Content In XML PSI, tag content is referred to as tag value, so well do the same for consistency. @@ -239,7 +239,6 @@ Please note that the attributes getter method will never return `null`, even if Its `getValue()`, `getStringValue()` and `getXmlAttribute()` methods will return `null`, but the DOM interface instance will exist and be valid. If the element has an underlying attribute, this can be easily fixed (surely, only if you need that): just call the `undefine()` method (defined in `DomElement`), and the XML attribute disappears, while [`GenericAttributeValue`](upsource:///xml/dom-openapi/src/com/intellij/util/xml/GenericAttributeValue.java) remains valid. - ### Children: Fixed Number You may often deal with tags that have at most one sub-tag with the given name (e.g. ``, `` or ``) in tags defining entity EJBs. @@ -363,7 +362,7 @@ Output correctness/completeness will largely depend on the input scheme and may Follow these steps: -* Run IntelliJ IDEA with _Plugin DevKit_ enabled in [internal mode](/reference_guide/internal_actions/enabling_internal.md) +* Run IntelliJ IDEA with _Plugin DevKit_ enabled in [internal mode](enabling_internal.md) * Select *Tools \| Internal Actions \| DevKit \| Generate DOM Model* * Select Scheme file and set options, then click "Generate" to generate sources * Modify generated sources according to your needs @@ -402,7 +401,6 @@ To make your `TypeChooser` work, register it in your overridden `DomFileDescript ### Useful Methods of DomElement and DomManager - #### PSI Connection Of course, DOM is tightly connected to XML PSI, so there's always a way of getting the `XmlTag` instance (which can be `null` for fixed-number children and attributes) using the `getXmlTag()` method. We remember that in `GenericAttributeValue` there's also the `getXmlAttribute()` method. @@ -478,8 +476,6 @@ DOM will do this for you automatically, if you annotate the getter for that chil For collection children getters, this annotation will mean, that the collection should be not empty (corresponding to '+' sign in DTD). Also, when you create a new element that has required fixed-number or attribute children, their tags or attributes will also be created in XML. - - ### Resolving Remember the interface `GenericDomValue` and its sub-interface `GenericAttributeValue`? Remember, that ANY class may be passed as `T` — for example, let's interpret `GenericDomValue` as a reference to a class. Then we can always consider it as a reference to an object of class `T`! With Strings or enums, it is not a very useful idea, but we'll use it in another way. @@ -590,9 +586,11 @@ Usually you will want to add searcher/utility methods to work with your `DomMode Example can be found in Struts 2 plugin (package `com.intellij.struts2.dom.struts.model`). ### DOM Stubs -> **NOTE** Please use it sparingly and only for heavily accessed parts in your DOM model, as it increases disk space usage/indexing run time. + > Please use it sparingly and only for heavily accessed parts in your DOM model, as it increases disk space usage/indexing run time. + > + {type="note"} -DOM elements can be stubbed, so (costly) access to XML/PSI is not necessary (see [Indexing and PSI Stubs](/basics/indexing_and_psi_stubs.md) for similar feature for custom languages). +DOM elements can be stubbed, so (costly) access to XML/PSI is not necessary (see [Indexing and PSI Stubs](indexing_and_psi_stubs.md) for similar feature for custom languages). Performance relevant elements, tag or attribute getters can simply be annotated with `@com.intellij.util.xml.Stubbed`. Return `true` from `DomFileDescription.hasStubs()` and increase `DomFileDescription.getStubVersion()` whenever you change `@Stubbed` annotations usage in your DOM hierarchy to trigger proper rebuilding of Stubs during indexing. @@ -639,7 +637,7 @@ So let's look at the simple controls more closely. It allows you to edit boolean values. The control is bound to `JCheckBox`. -![BooleanControl](img/xml_dom_api/booleancontrol.gif) +![BooleanControl](booleancontrol.gif) ##### ComboControl The control is bound to a non-editable `JComboBox`, so it can be used to choose something from a limited set. @@ -650,7 +648,7 @@ Since it's common practice to specify custom `CellRenderer` for combo boxes, the If it returns `false` on the value you're rendering, you can highlight it in some way, to achieve the same result as the default renderer. Or you can just delegate to that renderer in your own way. -![ComboControl](img/xml_dom_api/combocontrol.gif) +![ComboControl](combocontrol.gif) ##### BooleanEnumControl Sometimes, when there are only 2 alternatives, it's convenient to use a check box instead of combo box. @@ -677,13 +675,12 @@ This is a one-line editor with a browse button that opens the standard class sel The control accepts class names only. It is bound to `PsiClassPanel`. -![PsiClassControl](img/xml_dom_api/psiclasscontrol.gif) +![PsiClassControl](psiclasscontrol.gif) ##### PsiTypeControl This is almost the same as PsiClassControl, but allows entering not only class names, but also Java primitive types and even arrays. It is bound to `PsiTypePanel`. - ### Collection Control There is a special table component where each row represents one collection child. It's called `DomCollectionControl`, where `T` is your collection element type. @@ -731,7 +728,7 @@ Call the `DomTableView.installPopup()` method after construction, and pass a `De Tables can have single or multiple (default) row selection. If you want to change this behavior, override `DomTableView.allowMultipleRowsSelection()`. -![CollectionControl](img/xml_dom_api/collectioncontrol.gif) +![CollectionControl](collectioncontrol.gif) ### UI Organization The easiest way to create a DOM-based UI form is to extend the [`BasicDomElementComponent`](upsource:///xml/dom-openapi/src/com/intellij/util/xml/ui/BasicDomElementComponent.java) class. @@ -788,4 +785,4 @@ The following bundled open-source plugins make (heavy) use of DOM: - [Ant](upsource:///plugins/ant) - [Plugin DevKit](upsource:///plugins/devkit/devkit-core) - [Maven](upsource:///plugins/maven) -- [Struts 2](https://github.com/JetBrains/intellij-plugins/tree/master/struts2) (Ultimate Edition) +- [Struts 2](https://github.com/JetBrains/intellij-plugins/tree/master/struts2) (Ultimate Edition) \ No newline at end of file diff --git a/reference_guide/intellij_artifacts.md b/topics/reference_guide/intellij_artifacts.md similarity index 96% rename from reference_guide/intellij_artifacts.md rename to topics/reference_guide/intellij_artifacts.md index a3c96ac1c..edfdfa0b8 100644 --- a/reference_guide/intellij_artifacts.md +++ b/topics/reference_guide/intellij_artifacts.md @@ -1,15 +1,16 @@ ---- -title: IntelliJ Platform Artifacts Repositories ---- +[//]: # (title: IntelliJ Platform Artifacts Repositories) + -> **WARNING** When using additional repositories, make sure to use HTTPS always. + > When using additional repositories, make sure to use HTTPS always. + > + {type="warning"} JetBrains maintains public repositories that host artifacts related to the IntelliJ Platform, such as binaries and source code. These repositories make artifacts more accessible for plugin developers. The IntelliJ Platform artifacts repositories are: -* [Releases repository](https://www.jetbrains.com/intellij-repository/releases/) for release versions by [build number](/basics/getting_started/build_number_ranges.md). +* [Releases repository](https://www.jetbrains.com/intellij-repository/releases/) for release versions by [build number](build_number_ranges.md). * [Snapshots repository](https://www.jetbrains.com/intellij-repository/snapshots/) for _BRANCH#-EAP-SNAPSHOT_, _EAP-CANDIDATE-SNAPSHOT_, _LATEST-EAP-SNAPSHOT_, and the _EAP-SNAPSHOT_. See the [Maven coordinates](#specify-the-maven-coordinates-for-the-artifact) section for details about specifying these artifacts. @@ -109,4 +110,4 @@ dependencies { Note: * The artifact version (`182.2949.4`) must match in both statements. - * In this example `jps-model-serialization` declares the APIs and `jps-model-impl` provides the implementation, so both are required dependencies. + * In this example `jps-model-serialization` declares the APIs and `jps-model-impl` provides the implementation, so both are required dependencies. \ No newline at end of file diff --git a/reference_guide/internal_actions/enabling_internal.md b/topics/reference_guide/internal_actions/enabling_internal.md similarity index 94% rename from reference_guide/internal_actions/enabling_internal.md rename to topics/reference_guide/internal_actions/enabling_internal.md index 6d3d823d6..4202a9997 100644 --- a/reference_guide/internal_actions/enabling_internal.md +++ b/topics/reference_guide/internal_actions/enabling_internal.md @@ -1,6 +1,5 @@ ---- -title: Enabling Internal Mode ---- +[//]: # (title: Enabling Internal Mode) + There are useful tools, such as the Internal Actions menu, that are only visible if internal mode is enabled in IntelliJ IDEA. @@ -18,4 +17,4 @@ idea.is.internal=true ``` * Save the `idea.properties` file and restart IntelliJ IDEA. -The Internal Actions menu is available in **Tools \| Internal Actions**. +The Internal Actions menu is available in **Tools \| Internal Actions**. \ No newline at end of file diff --git a/topics/reference_guide/internal_actions/interal_actions_menu.md b/topics/reference_guide/internal_actions/interal_actions_menu.md new file mode 100644 index 000000000..deef205c1 --- /dev/null +++ b/topics/reference_guide/internal_actions/interal_actions_menu.md @@ -0,0 +1,11 @@ +[//]: # (title: Internal Actions Menu) + + + +The Internal Actions menu provides JetBrains IDE plugin developers with a suite of tools to help develop, debug, and test their IntelliJ Platform project. + +If the menu item **Tools \| Internal Actions** is not available in IntelliJ IDEA, then the first step is to [enable internal mode](enabling_internal.md) + +## The Tools Available on the Internal Actions Menu + +* [UI submenu](internal_ui_sub.md) \ No newline at end of file diff --git a/reference_guide/internal_actions/internal_actions_intro.md b/topics/reference_guide/internal_actions/internal_actions_intro.md similarity index 69% rename from reference_guide/internal_actions/internal_actions_intro.md rename to topics/reference_guide/internal_actions/internal_actions_intro.md index 4e92ab79e..08bea7d6d 100644 --- a/reference_guide/internal_actions/internal_actions_intro.md +++ b/topics/reference_guide/internal_actions/internal_actions_intro.md @@ -1,14 +1,13 @@ ---- -title: Internal Actions Menu -redirect_from: - - /reference_guide/internal_actions/interal_actions_menu.html ---- +[//]: # (title: Internal Actions Menu) + The Internal Actions menu provides plugin developers with a suite of tools to help develop, debug, and test their IntelliJ Platform plugins. -> **TIP** If the menu item **Tools \| Internal Actions** is not available in IntelliJ IDEA, then the first step is to [Enabling Internal Mode](enabling_internal.md) + > If the menu item **Tools \| Internal Actions** is not available in IntelliJ IDEA, then the first step is to [Enabling Internal Mode](enabling_internal.md) + > + {type="tip"} Click on the following topics to learn more about the _Internal Actions_ menu. * [Enabling Internal Mode](enabling_internal.md) provides instructions for enabling the Internal Actions menu in IntelliJ IDEA. -* [UI Tools](internal_ui_sub.md) has information about some of the Internal Actions menu tools for inspecting and testing plugin UI. +* [UI Tools](internal_ui_sub.md) has information about some of the Internal Actions menu tools for inspecting and testing plugin UI. \ No newline at end of file diff --git a/reference_guide/internal_actions/internal_ui_inspector.md b/topics/reference_guide/internal_actions/internal_ui_inspector.md similarity index 83% rename from reference_guide/internal_actions/internal_ui_inspector.md rename to topics/reference_guide/internal_actions/internal_ui_inspector.md index 8c262ac08..ab6e49a0e 100644 --- a/reference_guide/internal_actions/internal_ui_inspector.md +++ b/topics/reference_guide/internal_actions/internal_ui_inspector.md @@ -1,9 +1,6 @@ ---- -title: Internal Actions - UI Inspector +[//]: # (title: Internal Actions - UI Inspector) +[//]: # (: ) -redirect_from: - - /reference_guide/internal_actions/internal_uii.html ---- The _UI Inspector_ is a tool to interrogate elements of the IntelliJ IDEA UI to get an internal description of each element. @@ -22,7 +19,7 @@ For example, to get information about the _Build Project_ button's icon (hammer) The _UI Inspector_ displays that the icon has the internal path `AllIcons.Actions.Compile`: -![Internal Icon Info](img/internal_uii_icon_info.png) +![Internal Icon Info](internal_uii_icon_info.png) ## Additional Properties Various components used in the IntelliJ Platform expose additional properties. @@ -30,21 +27,21 @@ These can be useful to locate the underlying implementation, related Action, etc | Type | Place | Properties | | ----------------------------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -| [`AnAction`][ActionSystem] | Action Button
Menu Item | `Action` - [`AnAction`][us:AnAction] implementation
`Action ID` - Action `id`
`Action Plugin ID` - contributing plugin | -| [`ActionToolbar`][ActionSystem] | Action Toolbar | `Toolbar Group` - Action Group ID
`All Groups` - contained Action Group IDs | +| [`AnAction`][ActionSystem] | Action Button
Menu Item | `Action` - [`AnAction`][us:AnAction] implementation
`Action ID` - Action `id`
`Action Plugin ID` - contributing plugin | +| [`ActionToolbar`][ActionSystem] | Action Toolbar | `Toolbar Group` - Action Group ID
`All Groups` - contained Action Group IDs | | [`DialogWrapper`][DialogWrapper] | Modal Dialog | `dialogWrapperClass` - [`DialogWrapper`][us:DialogWrapper] implementation | | [`GutterMark`][us:GutterMark] | Editor Gutter Icon | `gutter renderer` - [`GutterMark`][us:GutterMark] implementation | | [`IntentionAction`/`QuickFix`][IntentionAction] | Popup Menu in Editor | `intention action`/`quick fix` - [`IntentionAction`][us:IntentionAction] / [`QuickFix`][us:QuickFix] implementation | | [`Tree`][Tree] | Tree | `treeModelClass` - `javax.swing.tree.TreeModel` implementation | -[ActionSystem]: /basics/action_system.md -[DialogWrapper]: /user_interface_components/dialog_wrapper.md -[Tree]: /user_interface_components/lists_and_trees.md -[IntentionAction]: /reference_guide/custom_language_support/code_inspections_and_intentions.md +[ActionSystem]: basic_action_system.md +[DialogWrapper]: dialog_wrapper.md +[Tree]: lists_and_trees.md +[IntentionAction]: code_inspections_and_intentions.md [us:AnAction]: upsource:///platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java [us:GutterMark]: upsource:///platform/editor-ui-api/src/com/intellij/codeInsight/daemon/GutterMark.java [us:DialogWrapper]: upsource:///platform/platform-api/src/com/intellij/openapi/ui/DialogWrapper.java [us:IntentionAction]: upsource:///platform/analysis-api/src/com/intellij/codeInsight/intention/IntentionAction.java [us:QuickFix]: upsource:///platform/analysis-api/src/com/intellij/codeInspection/QuickFix.java -Custom Swing components can also provide additional properties via [`UiInspectorContextProvider`](upsource:///platform/platform-impl/src/com/intellij/internal/inspector/UiInspectorContextProvider.java) (2020.1 and later). +Custom Swing components can also provide additional properties via [`UiInspectorContextProvider`](upsource:///platform/platform-impl/src/com/intellij/internal/inspector/UiInspectorContextProvider.java) (2020.1 and later). \ No newline at end of file diff --git a/reference_guide/internal_actions/internal_ui_laf_defaults.md b/topics/reference_guide/internal_actions/internal_ui_laf_defaults.md similarity index 90% rename from reference_guide/internal_actions/internal_ui_laf_defaults.md rename to topics/reference_guide/internal_actions/internal_ui_laf_defaults.md index a9928ec06..0657b51ad 100644 --- a/reference_guide/internal_actions/internal_ui_laf_defaults.md +++ b/topics/reference_guide/internal_actions/internal_ui_laf_defaults.md @@ -1,9 +1,6 @@ ---- -title: Internal Actions - LaF Defaults +[//]: # (title: Internal Actions - LaF Defaults) +[//]: # (: ) -redirect_from: - - /reference_guide/internal_actions/internal_ui_lafd.html ---- The _LaF Defaults_ window provides a key-value pair lookup for UI Controls. @@ -25,7 +22,7 @@ The _LaF Defaults_ window is used interactively by entering a UI element type - _LaF Defaults_ shows the list of UI Control names matching the filter. Clicking on one of the names narrows the information to show only the key-value pair for that UI element: -![LaF Lookup](img/internal_lafd_win.png) +![LaF Lookup](internal_lafd_win.png) ### Prototyping the Color of UI Controls The color of UI Controls can be changed (in real time) by clicking in the _Value_ column next to a _Name_ (`key`) of interest. @@ -33,4 +30,4 @@ The _Choose Color_ window is displayed. Color changes can be specified as RGB, hexadecimal, or using the color picker. Pressing the _Choose_ button changes the UI Control color immediately. -UI Control colors can be reset using the _Choose Color_ window, or by resetting the [UI Theme](https://www.jetbrains.com/help/idea/settings-appearance.html). +UI Control colors can be reset using the _Choose Color_ window, or by resetting the [UI Theme](https://www.jetbrains.com/help/idea/settings-appearance.html). \ No newline at end of file diff --git a/reference_guide/internal_actions/internal_ui_sub.md b/topics/reference_guide/internal_actions/internal_ui_sub.md similarity index 73% rename from reference_guide/internal_actions/internal_ui_sub.md rename to topics/reference_guide/internal_actions/internal_ui_sub.md index 5406576ef..341859d1a 100644 --- a/reference_guide/internal_actions/internal_ui_sub.md +++ b/topics/reference_guide/internal_actions/internal_ui_sub.md @@ -1,13 +1,14 @@ ---- -title: Internal Actions - UI Submenu ---- +[//]: # (title: Internal Actions - UI Submenu) + The Internal Actions UI submenu provides IntelliJ Platform plugin developers with a suite of tools to help develop, debug, and test their IntelliJ Platform project UI. -> **TIP** If the menu item **Tools \| Internal Actions** is not available in IntelliJ IDEA, then the first step is to [Enabling Internal Mode](enabling_internal.md) + > If the menu item **Tools \| Internal Actions** is not available in IntelliJ IDEA, then the first step is to [Enabling Internal Mode](enabling_internal.md) + > + {type="tip"} ## The Tools Available on the UI Submenu Here are some tools available on the UI submenu of the Internal Actions menu: * [UI Inspector](internal_ui_inspector.md) is a tool to get an internal description with each UI element's properties. -* [LaF Defaults](internal_ui_laf_defaults.md) provides a way to lookup the key-value pair for a UI element, and the ability to prototype the color of UI Controls. +* [LaF Defaults](internal_ui_laf_defaults.md) provides a way to lookup the key-value pair for a UI element, and the ability to prototype the color of UI Controls. \ No newline at end of file diff --git a/reference_guide/jcef.md b/topics/reference_guide/jcef.md similarity index 95% rename from reference_guide/jcef.md rename to topics/reference_guide/jcef.md index 5de37b2b8..97ff2f6ad 100644 --- a/reference_guide/jcef.md +++ b/topics/reference_guide/jcef.md @@ -1,12 +1,13 @@ ---- -title: JCEF - Java Chromium Embedded Framework ---- +[//]: # (title: JCEF - Java Chromium Embedded Framework) + -> **WARNING** JCEF is available since 2020.1 as an **experimental feature**. + > JCEF is available since 2020.1 as an **experimental feature**. > We plan to deprecate using JavaFX in 3rd party plugins and switch to JCEF in 2020.2. > To continue using JavaFX in 2020.2 or later, an explicit dependency on [JavaFX Runtime for Plugins](https://plugins.jetbrains.com/plugin/14250-javafx-runtime-for-plugins) must be added. > Please see also blog post [JavaFX and JCEF in the IntelliJ Platform](https://blog.jetbrains.com/platform/2020/07/javafx-and-jcef-in-the-intellij-platform/) for summary of plans. + > + {type="warning"} JCEF is a Java port of [CEF](https://bitbucket.org/chromiumembedded/cef/wiki/Home) framework for embedding [Chromium-based browsers](https://www.chromium.org/Home) in applications using Swing. @@ -16,7 +17,9 @@ Embedding of the browser component inside the IDE allows amongst others: - previewing generated HTML (e.g., from Markdown) ## Enabling JCEF -> **NOTE** JCEF is available and enabled by default in 2020.2. + > JCEF is available and enabled by default in 2020.2. + > + {type="note"} Using JCEF requires using a dedicated JetBrains Runtime, please follow these [installation instructions](https://youtrack.jetbrains.com/issue/IDEA-231833#focus=streamItem-27-3993099.0-0) on how to obtain and activate it in your IDE. Enable `ide.browser.jcef.enabled` in Registry dialog (invoke **Help \| Find Action** and type "Registry") and restart the IDE for changes to take effect. @@ -33,7 +36,7 @@ ide.browser.jcef.debug.port=9222 JavaScript debugger in IntelliJ IDEA Ultimate can thus be used to debug JavaScript code running in the IDE via the Chrome DevTools. Use the _Attach to Node.js/Chrome_ configurations with a proper port number. -Also, JCEF provides a default Chrome DevTools front-end (similar to the one in the Chrome browser) that can be opened from the JCEF’s browser component context menu via **Open DevTools** (the menu item is available in [internal mode](/reference_guide/internal_actions/enabling_internal.md) only). +Also, JCEF provides a default Chrome DevTools front-end (similar to the one in the Chrome browser) that can be opened from the JCEF’s browser component context menu via **Open DevTools** (the menu item is available in [internal mode](enabling_internal.md) only). To access the Chrome DevTools in plugin code, use the following API: @@ -72,7 +75,6 @@ JCEF can be unsupported when: To avoid the above problems, the IDE should be run with the bundled JBR. - ### [`com.intellij.ui.jcef.JBCefClient`](upsource:///platform/platform-api/src/com/intellij/ui/jcef/JBCefClient.java) Is tied to every browser component explicitly or implicitly. Used for adding handlers to the associated browser. @@ -148,4 +150,4 @@ Say we want to open a link in an external browser, and see it in [`MarkdownJCEFH // Dispose the query when necessary Disposer.dispose(myJSQueryOpenInBrowser); -``` +``` \ No newline at end of file diff --git a/reference_guide/localization_guide.md b/topics/reference_guide/localization_guide.md similarity index 92% rename from reference_guide/localization_guide.md rename to topics/reference_guide/localization_guide.md index 89d76071e..ab96cf4b0 100644 --- a/reference_guide/localization_guide.md +++ b/topics/reference_guide/localization_guide.md @@ -1,6 +1,5 @@ ---- -title: Localization Guide ---- +[//]: # (title: Localization Guide) + The purpose of the document is to describe steps necessary to create localized versions of IDEA. @@ -28,9 +27,11 @@ See [native2ascii](https://docs.oracle.com/javase/7/docs/technotes/tools/solaris Property values mostly follow MessageFormat rules. -> **NOTE** Due to historic reasons main menu, toolbar, popup menus and other actions have their mnemonic char prefixed with `\_` (underscore) char while all other mnemonics like those for checkboxes, buttons etc. use `&` (ampersand) sign for the same purpose. + > Due to historic reasons main menu, toolbar, popup menus and other actions have their mnemonic char prefixed with `\_` (underscore) char while all other mnemonics like those for checkboxes, buttons etc. use `&` (ampersand) sign for the same purpose. > Moreover one can encounter `&&` (double ampersand) in some places, which denote alternative mnemonic to be used under MacOS X (mnemonics mapped to `U`, `I`, `O`, `N` chars won't work there). > Generally, use the same mnemonic denotation used in the original property value and everything will be OK. + > + {type="note"} ## Components Location @@ -53,4 +54,4 @@ Property values mostly follow MessageFormat rules. * **File templates** again go the same way (if at all should be translated). ***/fileTemplates/Singleton.java.ft*** goes to ***/fileTemplates_ja/Singleton.java.ft***. -Following Sun rules for property bundles whenever certain resource cannot be found in localized version its default version from ***resources_en.jar*** will be used instead. +Following Sun rules for property bundles whenever certain resource cannot be found in localized version its default version from ***resources_en.jar*** will be used instead. \ No newline at end of file diff --git a/reference_guide/messaging_infrastructure.md b/topics/reference_guide/messaging_infrastructure.md similarity index 94% rename from reference_guide/messaging_infrastructure.md rename to topics/reference_guide/messaging_infrastructure.md index 75e2d4f36..48ffb9f40 100644 --- a/reference_guide/messaging_infrastructure.md +++ b/topics/reference_guide/messaging_infrastructure.md @@ -1,6 +1,5 @@ ---- -title: Messaging Infrastructure ---- +[//]: # (title: Messaging Infrastructure) + ## Purpose @@ -21,7 +20,7 @@ Here are the main components of the messaging API. This class serves as an endpoint at the messaging infrastructure. I.e., clients are allowed to subscribe to a specific topic within a bus and send messages to that topic within that particular bus. -![Topic](img/topic.svg) +![Topic](topic.svg) * *display name* just a human-readable name used for logging/monitoring purposes; * *broadcast direction* will be explained in details at Broadcasting. Default value is *TO\_CHILDREN*; @@ -35,13 +34,13 @@ I.e., clients are allowed to subscribe to a specific topic within a bus and send Is the core of the messaging system. Is used at the following scenarios: -![Bus](img/bus.png) +![Bus](bus.png) ### Connection Manages all subscriptions for particular client within particular bus. -![Connection](img/connection.svg) +![Connection](connection.svg) * keeps number of *topic handler* mappings (callbacks to invoke when message for the target topic is received) *Note*: not more than one handler per-topic within the same connection is allowed; @@ -66,10 +65,11 @@ public interface ChangeActionNotifier { *Subscribing* -![Subscribing](img/subscribe.svg) - -> **NOTE** If targeting 2019.3 or later, use [declarative registration](/basics/plugin_structure/plugin_listeners.md) if possible. +![Subscribing](subscribe.svg) + > If targeting 2019.3 or later, use [declarative registration](plugin_listeners.md) if possible. + > + {type="note"} ```java public void init(MessageBus bus) { @@ -88,7 +88,7 @@ public void init(MessageBus bus) { *Publishing* -![Publishing](img/publish.svg) +![Publishing](publish.svg) ```java public void doChange(Context context) { @@ -115,13 +115,13 @@ public void doChange(Context context) { Message buses can be organised into hierarchies. Moreover, the *IntelliJ Platform* has them already: -![Standard hierarchy](img/standard_hierarchy.svg) +![Standard hierarchy](standard_hierarchy.svg) That allows to notify subscribers registered in one message bus on messages sent to another message bus. *Example:* -![Parent-child broadcast](img/parent_child_broadcast.svg) +![Parent-child broadcast](parent_child_broadcast.svg) Here we have a simple hierarchy (*application bus* is a parent of *project bus*) with three subscribers for the same topic. @@ -156,7 +156,7 @@ The IntelliJ Platform's Messaging infrastructure guarantees that all messages se Suppose we have the following configuration: -![Nested messages](img/nested_config.svg) +![Nested messages](nested_config.svg) Let's see what happens if someone sends a message to the target topic: @@ -207,4 +207,4 @@ We had the following then: 9. _subscriber2_ receives _message1_ and also modifies a document; 10. the call stack is unwinded and _actual change_ phase of document modification operation requested by _subscriber1_ begins; -**The problem** is that document range used by _subscriber1_ for initial modification request is invalid if _subscriber2_ has changed document's range before it. +**The problem** is that document range used by _subscriber1_ for initial modification request is invalid if _subscriber2_ has changed document's range before it. \ No newline at end of file diff --git a/reference_guide/multiple_carets.md b/topics/reference_guide/multiple_carets.md similarity index 94% rename from reference_guide/multiple_carets.md rename to topics/reference_guide/multiple_carets.md index ec4741623..f08d99e18 100644 --- a/reference_guide/multiple_carets.md +++ b/topics/reference_guide/multiple_carets.md @@ -1,6 +1,5 @@ ---- -title: Supporting Multiple Carets ---- +[//]: # (title: Supporting Multiple Carets) + ## Introduction @@ -67,11 +66,13 @@ Examples of its usage: * [`TypedAction`](upsource:///platform/platform-api/src/com/intellij/openapi/editor/actionSystem/TypedAction.java). * [`XmlGtTypedHandler`](upsource:///xml/impl/src/com/intellij/codeInsight/editorActions/XmlGtTypedHandler.java). -> **NOTE** Starting from version 14, [`TypedHandlerDelegate`](upsource:///platform/lang-api/src/com/intellij/codeInsight/editorActions/TypedHandlerDelegate.java) implementations are invoked automatically for each caret. + > Starting from version 14, [`TypedHandlerDelegate`](upsource:///platform/lang-api/src/com/intellij/codeInsight/editorActions/TypedHandlerDelegate.java) implementations are invoked automatically for each caret. > If one wants to implement custom multicaret behaviour on typing, [`TypedActionHandler`](upsource:///platform/platform-api/src/com/intellij/openapi/editor/actionSystem/TypedActionHandler.java) needs to be provided instead. + > + {type="note"} ## Code Insight Actions Existing actions inheriting from [`CodeInsightAction`](upsource:///platform/lang-api/src/com/intellij/codeInsight/actions/CodeInsightAction.java) will work for primary caret only. To support multiple carets, one should subclass [`MultiCaretCodeInsightAction`](upsource:///platform/lang-impl/src/com/intellij/codeInsight/actions/MultiCaretCodeInsightAction.java) instead. -Each caret might have a different editor and PSI instance, so using the old API is not possible. +Each caret might have a different editor and PSI instance, so using the old API is not possible. \ No newline at end of file diff --git a/reference_guide/performance/performance.md b/topics/reference_guide/performance/performance.md similarity index 86% rename from reference_guide/performance/performance.md rename to topics/reference_guide/performance/performance.md index 1c6f65862..46d2e9bca 100644 --- a/reference_guide/performance/performance.md +++ b/topics/reference_guide/performance/performance.md @@ -1,9 +1,10 @@ ---- -title: Optimizing Performance ---- +[//]: # (title: Optimizing Performance) + -> **TIP** [IDE Perf](https://plugins.jetbrains.com/plugin/15104-ide-perf) plugin provides on-the-fly performance diagnostic tools, including a dedicated view for [`CachedValue`](#cache-results-of-heavy-computations) metrics. + > [IDE Perf](https://plugins.jetbrains.com/plugin/15104-ide-perf) plugin provides on-the-fly performance diagnostic tools, including a dedicated view for [`CachedValue`](#cache-results-of-heavy-computations) metrics. + > + {type="tip"} ## Working with PSI Efficiently @@ -25,15 +26,15 @@ See below. Avoid loading too many parsed trees or documents into memory at the same time. Ideally, only AST nodes from files open in the editor should be present in the memory. -Everything else, even if it's needed for resolve/highlighting purposes, can be accessed via PSI interfaces, but its implementations should [use stubs](/basics/indexing_and_psi_stubs/stub_indexes.md) underneath, which are less CPU- and memory-expensive. +Everything else, even if it's needed for resolve/highlighting purposes, can be accessed via PSI interfaces, but its implementations should [use stubs](stub_indexes.md) underneath, which are less CPU- and memory-expensive. -If stubs don't suit your case well (e.g., the information you need is large and/or very rarely needed, or you're developing a plugin for a language whose PSI you don't control), you can create a [custom index or gist](/basics/indexing_and_psi_stubs.md). +If stubs don't suit your case well (e.g., the information you need is large and/or very rarely needed, or you're developing a plugin for a language whose PSI you don't control), you can create a [custom index or gist](indexing_and_psi_stubs.md). You can use [`AstLoadingFilter`](upsource:///platform/core-api/src/com/intellij/util/AstLoadingFilter.java) in production and `PsiManagerEx.setAssertOnFileLoadingFilter()` in tests to ensure you're not loading AST accidentally. The same applies to documents: only the ones opened in editors should be loaded. Usually, you shouldn't need document contents (as most information can be retrieved from PSI). -If you nevertheless need documents, consider saving the information you need to provide in a [custom index or gist](/basics/indexing_and_psi_stubs.md) to get it more cheaply later. +If you nevertheless need documents, consider saving the information you need to provide in a [custom index or gist](indexing_and_psi_stubs.md) to get it more cheaply later. If you still need documents, then at least ensure you load them one by one and don't hold them on strong references to let GC free the memory as quickly as possible. #### Cache Results of Heavy Computations @@ -84,4 +85,4 @@ Massive batches of VFS events can be pre-processed in background, see [`AsyncFil #### Don't block EDT by long non-cancellable `ReadAction`s in background threads -See [General Threading Rules](/basics/architectural_overview/general_threading_rules.md), especially its section on [*Read Action Cancellability*](/basics/architectural_overview/general_threading_rules.md#read-action-cancellability). +See [General Threading Rules](general_threading_rules.md), especially its section on [*Read Action Cancellability*](general_threading_rules.md#read-action-cancellability). \ No newline at end of file diff --git a/topics/reference_guide/project_model/build_system.md b/topics/reference_guide/project_model/build_system.md new file mode 100644 index 000000000..1fe71e071 --- /dev/null +++ b/topics/reference_guide/project_model/build_system.md @@ -0,0 +1,5 @@ +[//]: # (title: Build System) + + + +* [External builder API and plugins](external_builder_api.md) \ No newline at end of file diff --git a/reference_guide/project_model/facet.md b/topics/reference_guide/project_model/facet.md similarity index 84% rename from reference_guide/project_model/facet.md rename to topics/reference_guide/project_model/facet.md index 0e8df929e..12785267f 100644 --- a/reference_guide/project_model/facet.md +++ b/topics/reference_guide/project_model/facet.md @@ -1,6 +1,5 @@ ---- -title: Facet ---- +[//]: # (title: Facet) + A facet represents configuration specific for a particular framework/technology, associated with a module. @@ -18,4 +17,4 @@ Please see [Facet Basics](https://github.com/JetBrains/intellij-sdk-code-samples To create, search and access the list of facets for a module use [`FacetManager`](upsource:///platform/lang-api/src/com/intellij/facet/FacetManager.java). ### Facet-Based Tool Window -A [tool window](/user_interface_components/tool_windows.md) dependent on the existence of given facet(s) can be registered via `com.intellij.facet.toolWindow` extension point. +A [tool window](tool_windows.md) dependent on the existence of given facet(s) can be registered via `com.intellij.facet.toolWindow` extension point. \ No newline at end of file diff --git a/reference_guide/project_model/library.md b/topics/reference_guide/project_model/library.md similarity index 95% rename from reference_guide/project_model/library.md rename to topics/reference_guide/project_model/library.md index a74ae99f4..0856cdf44 100644 --- a/reference_guide/project_model/library.md +++ b/topics/reference_guide/project_model/library.md @@ -1,6 +1,5 @@ ---- -title: Library ---- +[//]: # (title: Library) + A library is an archive of compiled code (such as JAR files) that modules depend on. @@ -14,9 +13,6 @@ For more information about libraries, refer to [Libraries](https://www.jetbrains A particular type of programmatically defined libraries is [Predefined Libraries](#predefined-libraries). -* bullet list -{:toc} - ## Accessing Libraries and Jars Package [`libraries`](upsource:///platform/projectModel-api/src/com/intellij/openapi/roots/libraries) provides functionality for working with project libraries and jars. @@ -64,7 +60,7 @@ Messages.showInfoMessage(roots.toString(), "Library Info"); ### Creating a Library To create a library, perform the following steps: - * Get a [write action](../../basics/architectural_overview/general_threading_rules.md#readwrite-lock) + * Get a [write action](general_threading_rules.md#read-write-lock) * Obtain the library table to which you want to add the library. Use one of the following, depending on the library level: * `LibraryTablesRegistrar.getInstance().getLibraryTable()` * `LibraryTablesRegistrar.getInstance().getLibraryTable(Project)` @@ -78,7 +74,7 @@ You can find an example of using these APIs in the [project_model](https://githu ### Adding Contents or Modifying a Library To add or change the roots of a library, you need to perform the following steps: - * Get a [write action](../../basics/architectural_overview/general_threading_rules.md#readwrite-lock) + * Get a [write action](general_threading_rules.md#read-write-lock) * Get a **modifiable model** for the library, using `Library.getModifiableModel()` * Use methods such as `Library.ModifiableModel.addRoot()` to perform the necessary changes * Commit the model using `Library.ModifiableModel.commit()`. @@ -112,4 +108,4 @@ EP: `com.intellij.additionalLibraryRootsProvider` [`AdditionalLibraryRootsProvider`](upsource:///platform/projectModel-impl/src/com/intellij/openapi/roots/AdditionalLibraryRootsProvider.java) Allows providing synthetic/predefined libraries ([`SyntheticLibrary`](upsource:///platform/projectModel-impl/src/com/intellij/openapi/roots/SyntheticLibrary.java)) in a project without exposing them in the model. -By default, they're also hidden from UI. +By default, they're also hidden from UI. \ No newline at end of file diff --git a/reference_guide/project_model/module.md b/topics/reference_guide/project_model/module.md similarity index 95% rename from reference_guide/project_model/module.md rename to topics/reference_guide/project_model/module.md index 95b41e02b..bed0a2eda 100644 --- a/reference_guide/project_model/module.md +++ b/topics/reference_guide/project_model/module.md @@ -1,6 +1,5 @@ ---- -title: Module ---- +[//]: # (title: Module) + A _module_ is a discrete unit of functionality that can be run, tested, and debugged independently. @@ -15,15 +14,16 @@ The key components of a module are: Java classes directly under a source root will be in the root package. Source roots can also be used to implement more fine-grained dependency checks. Code under a regular source root cannot depend on code under a test source root. - > **NOTE** Not all other IntelliJ Platform-based IDEs use source roots. + > Not all other IntelliJ Platform-based IDEs use source roots. * **Order entries** - the dependencies of a module, which are stored in an ordered list. A dependency can be a reference to an [SDK](sdk.md), a [library](library.md), or another module. * **[Facets](facet.md)** - the list of framework-specific configuration entries. + > + {type="note"} In addition to that, a module can store other settings, such as a module-specific [SDK](sdk.md), compile output path settings, etc. Plugins can store additional data associated with a module by creating facets or module-level components. - The *IntelliJ Platform* provides a number of classes and interfaces you can use to work with modules: * [`Module`](upsource:///platform/core-api/src/com/intellij/openapi/module/Module.java) @@ -101,8 +101,7 @@ Module module = ModuleUtil.findModuleForFile(virtualFile,myProject); String moduleName = module == null ? "Module not found" : module.getName(); ``` -* To get the project module to which the specified [PSI element](/basics/architectural_overview/psi_elements.md) belongs, use the `ModuleUtil.findModuleForPsiElement()` method. - +* To get the project module to which the specified [PSI element](psi_elements.md) belongs, use the `ModuleUtil.findModuleForPsiElement()` method. ### Accessing Module Roots @@ -124,7 +123,7 @@ VirtualFile moduleSourceRoot = ProjectRootManager.getInstance(project).getFileIn ## Receiving Notifications About Module Changes -To receive notifications about module changes (modules being added, removed or renamed), use the [message bus](/reference_guide/messaging_infrastructure.md) and the `ProjectTopics.MODULES` topic: +To receive notifications about module changes (modules being added, removed or renamed), use the [message bus](messaging_infrastructure.md) and the `ProjectTopics.MODULES` topic: ```java project.getMessageBus().connect().subscribe(ProjectTopics.MODULES, new ModuleListener() { @@ -133,4 +132,4 @@ project.getMessageBus().connect().subscribe(ProjectTopics.MODULES, new ModuleLis } }); -``` +``` \ No newline at end of file diff --git a/reference_guide/project_model/project.md b/topics/reference_guide/project_model/project.md similarity index 94% rename from reference_guide/project_model/project.md rename to topics/reference_guide/project_model/project.md index 43724dc30..9e9238cd1 100644 --- a/reference_guide/project_model/project.md +++ b/topics/reference_guide/project_model/project.md @@ -1,6 +1,5 @@ ---- -title: Project ---- +[//]: # (title: Project) + In the *IntelliJ Platform*, a project encapsulates all the source code, libraries, and build instructions into a single organizational unit. @@ -22,7 +21,7 @@ Each XML file is responsible for its own set of settings and can be recognized b As for the file-based format projects, `.iml` files describe modules. Note that direct access to project files isn't required to load or save settings. -See [Persisting State of Components](../../basics/persisting_state_of_components.md) for more information. +See [Persisting State of Components](persisting_state_of_components.md) for more information. To work with projects and project files, use the following classes and interfaces: * [`Project`](upsource:///platform/core-api/src/com/intellij/openapi/project/Project.java) @@ -76,12 +75,12 @@ See [SDK](sdk.md) for more details. ## Changing the Project Structure Utility classes used for modifying the project structure can be found in the package [`projectModel-impl.openapi`](upsource:///platform/projectModel-impl/src/com/intellij/openapi). Its [`roots`](upsource:///platform/projectModel-impl/src/com/intellij/openapi/roots/) subpackage contains instances and utilities intended for work with project and module source roots, including [`ModuleRootModificationUtil`](upsource:///platform/projectModel-api/src/com/intellij/openapi/roots/ModuleRootModificationUtil.java) and [`ProjectRootUtil`](upsource:///platform/projectModel-impl/src/com/intellij/openapi/projectRoots/impl/ProjectRootUtil.java). -Project structure changes need to be performed in a [write action](/basics/architectural_overview/general_threading_rules.md#readwrite-lock). +Project structure changes need to be performed in a [write action](general_threading_rules.md#read-write-lock). Refer to the [project_model](https://github.com/JetBrains/intellij-sdk-code-samples/blob/master/project_model/src/main/java/org/intellij/sdk/project/model/ModificationAction.java) code sample to learn how project structure modification can be implemented. ## Receiving Notifications About Project Structure Changes -To receive notifications about changes in project structure (modules or libraries being added or removed, module dependencies being changed, and so on), use the [message bus](/reference_guide/messaging_infrastructure.md) and the `ProjectTopics.PROJECT_ROOTS` topic: +To receive notifications about changes in project structure (modules or libraries being added or removed, module dependencies being changed, and so on), use the [message bus](messaging_infrastructure.md) and the `ProjectTopics.PROJECT_ROOTS` topic: ```java project.getMessageBus().connect().subscribe(ProjectTopics.PROJECT_ROOTS, new ModuleRootListener() { @@ -91,4 +90,4 @@ project.getMessageBus().connect().subscribe(ProjectTopics.PROJECT_ROOTS, new Mod }); ``` -The event only notifies that something has changed; if more details are needed about what changes have occurred, keep a copy of the state of the project structure model which is relevant, and to compare it with the state after the change. +The event only notifies that something has changed; if more details are needed about what changes have occurred, keep a copy of the state of the project structure model which is relevant, and to compare it with the state after the change. \ No newline at end of file diff --git a/reference_guide/project_model/sdk.md b/topics/reference_guide/project_model/sdk.md similarity index 96% rename from reference_guide/project_model/sdk.md rename to topics/reference_guide/project_model/sdk.md index feb727644..bc51d7a6c 100644 --- a/reference_guide/project_model/sdk.md +++ b/topics/reference_guide/project_model/sdk.md @@ -1,6 +1,5 @@ ---- -title: SDK ---- +[//]: # (title: SDK) + Every project uses a Software Development Kit (SDK). @@ -69,7 +68,7 @@ To let a user select an SDK, see [`ProjectJdksEditor`](upsource:///java/idea-ui/ However, it is not recommended to use "SDK" in non-IntelliJ IDEA IDEs. Although "SDK" is available in most JetBrains products, `ProjectJdksEditor` is specific to Java, making the operation around "SDK" difficult. -The recommended way of managing "SDK" settings is to create a [`CustomStepProjectGenerator`](upsource:///platform/lang-impl/src/com/intellij/ide/util/projectWizard/CustomStepProjectGenerator.java) implementation and save settings in a [`PersistentStateComponent`](/basics/persisting_state_of_components.md). +The recommended way of managing "SDK" settings is to create a [`CustomStepProjectGenerator`](upsource:///platform/lang-impl/src/com/intellij/ide/util/projectWizard/CustomStepProjectGenerator.java) implementation and save settings in a [`PersistentStateComponent`](persisting_state_of_components.md). ## Assisting in Setting Up an SDK -Register the implementation of [`ProjectSdkSetupValidator`](upsource:///platform/lang-impl/src/com/intellij/codeInsight/daemon/ProjectSdkSetupValidator.java) in extension point `com.intellij.projectSdkSetupValidator` to provide quick fix. +Register the implementation of [`ProjectSdkSetupValidator`](upsource:///platform/lang-impl/src/com/intellij/codeInsight/daemon/ProjectSdkSetupValidator.java) in extension point `com.intellij.projectSdkSetupValidator` to provide quick fix. \ No newline at end of file diff --git a/reference_guide/project_wizard.md b/topics/reference_guide/project_wizard.md similarity index 97% rename from reference_guide/project_wizard.md rename to topics/reference_guide/project_wizard.md index 2cdc41820..01bc61663 100644 --- a/reference_guide/project_wizard.md +++ b/topics/reference_guide/project_wizard.md @@ -1,6 +1,5 @@ ---- -title: Project Wizard. Adding Support for Creating New Project Types. ---- +[//]: # (title: Project Wizard - Adding Support for Creating New Project Types.) + ## Project Wizard @@ -12,8 +11,7 @@ Working with the project wizard can be illustrated with the [RedLine SmallTalk p Additional support for specific tools and technologies is usually done via implementing some certain module type which is attached to the project. New module type should be derived from the class [`ModuleType`](upsource:///platform/lang-api/src/com/intellij/openapi/module/ModuleType.java). - -## Project Wizard +## Custom Project Wizard Main utilities to configure a custom project wizard can be found in the package [`lang-api.ide.util.projectWizard`](upsource:///platform/lang-api/src/com/intellij/ide/util/projectWizard). These classes and interfaces serve the following purposes: @@ -101,8 +99,7 @@ The [`RsModuleWizardStep`](https://github.com/bulenkov/RedlineSmalltalk/blob/mas ## Facet Facets in IntelliJ are the way to store multiple kinds of module-specific settings, for instance to make a language support or framework available in some given module. -To understand facets better from the point of view of an end-user, please see the [Facet](/reference_guide/project_model/facet.md) documentation section. - +To understand facets better from the point of view of an end-user, please see the [Facet](facet.md) documentation section. ## Implementing Project Structure Detector @@ -139,4 +136,4 @@ Here is an example that creates a module if no other modules exist in the projec projectDescriptor.setModules(modules); } } -``` +``` \ No newline at end of file diff --git a/reference_guide/settings_groups.md b/topics/reference_guide/settings_groups.md similarity index 93% rename from reference_guide/settings_groups.md rename to topics/reference_guide/settings_groups.md index 93e7cb855..1e33f301d 100644 --- a/reference_guide/settings_groups.md +++ b/topics/reference_guide/settings_groups.md @@ -1,6 +1,4 @@ ---- -title: Custom Settings Groups ---- +[//]: # (title: Custom Settings Groups) @@ -10,16 +8,15 @@ These parent groups are the existing categories of Settings in the IntelliJ Plat However, suppose the custom Settings are rich enough to require multiple levels? For example, a custom Setting implementation has multiple sub-Settings implementations. Extension Point declarations can create this kind of multilayer Settings hierarchy. - -* bullet list -{:toc} - + ## Extension Points for Parent-Child Settings Relationships There are multiple ways of creating parent-child relationships in groups of Settings: in implementations, or Extension Point declarations. However, there are performance penalties for creating these relationships in implementations because the objects must be instantiated to determine the relationships. This section describes the syntax for declaring more complex parent-child relationships in `com.intellij.projectConfigurable` or `com.intellij.applicationConfigurable` EPs. -> **NOTE** An application configurable can be a parent of a project configurable. + > An application configurable can be a parent of a project configurable. + > + {type="note"} There are two ways of declaring parent-child relationships using the `com.intellij.projectConfigurable` or `com.intellij.applicationConfigurable` EPs. The first is to use separate EP declarations that are tied together by the value of one attribute. @@ -80,10 +77,12 @@ For the child of a parent, the `id` attribute becomes compound: | Attribute | Required | Value | |:--- | :---: |:--- | -| `id` | Y | Compound FQN of implementation based on `com.intellij.openapi.options.Configurable` in the form: `XX.YY` where:
`XX` is the parent Settings component FQN-based id.
`YY` is unique to the child among other siblings. | +| `id` | Y | Compound FQN of implementation based on `com.intellij.openapi.options.Configurable` in the form: `XX.YY` where:
`XX` is the parent Settings component FQN-based id.
`YY` is unique to the child among other siblings. | -> **TIP** All children share the parent's `id` as the basis of their own `id`. + > All children share the parent's `id` as the basis of their own `id`. > All children have an `id` suffix that is unique among their siblings. + > + {type="tip"} ## Implementations for Parent-Child Settings Implementations can be based on [`Configurable`](upsource:///platform/platform-api/src/com/intellij/openapi/options/Configurable.java), [`ConfigurableProvider`](upsource:///platform/platform-api/src/com/intellij/openapi/options/ConfigurableProvider.java) or one of their subtypes. @@ -92,4 +91,4 @@ For more information about creating Settings implementations, see [Implementatio ### Configurable Marker Interfaces The `Configurable.Composite` interface indicates a configurable component has child components. The preferred approach is to specify child components in the [EP declaration](#extension-points-for-parent-child-settings-relationships). -Using the `Composite` interface incurs the penalty of loading child classes while building the tree of Settings Swing components. +Using the `Composite` interface incurs the penalty of loading child classes while building the tree of Settings Swing components. \ No newline at end of file diff --git a/reference_guide/settings_guide.md b/topics/reference_guide/settings_guide.md similarity index 83% rename from reference_guide/settings_guide.md rename to topics/reference_guide/settings_guide.md index 4358e7ffc..e526546a0 100644 --- a/reference_guide/settings_guide.md +++ b/topics/reference_guide/settings_guide.md @@ -1,21 +1,16 @@ ---- -title: Settings Guide ---- +[//]: # (title: Settings Guide) _Settings_ persistently store states that control the behavior and appearance of IntelliJ Platform-based IDEs. On this page, the term "Settings" means the same as "Preferences" on some platforms. -Plugins can create and store Settings to capture their configuration in a way that uses the IntelliJ Platform [Persistence Model](/basics/persisting_state_of_components.md). +Plugins can create and store Settings to capture their configuration in a way that uses the IntelliJ Platform [Persistence Model](persisting_state_of_components.md). The User Interface (UI) for these custom Settings can be added to the [IDE Settings dialog](https://www.jetbrains.com/help/idea/settings-preferences-dialog.html). Settings can [affect different levels](https://www.jetbrains.com/help/idea/configuring-project-and-ide-settings.html) of scope. This document describes adding custom Settings at the Project and Application (or Global, IDE) levels. -* bullet list -{:toc} - ## Extension Points for Settings Custom Settings implementations are declared in a plugin's configuration (`plugin.xml`) file using one of two Extension Points (EPs), depending on the level of the Settings. Many [attributes](#settings-declaration-attributes) are shared between the EP declarations. @@ -23,8 +18,10 @@ Many [attributes](#settings-declaration-attributes) are shared between the EP de Application and Project Settings typically provide an implementation based on the [`Configurable`](upsource:///platform/platform-api/src/com/intellij/openapi/options/Configurable.java) interface because they do not have runtime dependencies. See [Implementations for Settings Extension Points](#implementations-for-settings-extension-points) for more information. -> **NOTE** For performance reasons, the recommended approach is to declare as much information as possible about a Settings' implementation using attributes in the Extension Point. + > For performance reasons, the recommended approach is to declare as much information as possible about a Settings' implementation using attributes in the Extension Point. > If it is not declared, the component must be loaded to retrieve it from the implementation, degrading UI responsiveness. + > + {type="note"} ### Declaring Application Settings Settings at the Application level use the `com.intellij.applicationConfigurable` EP. @@ -60,17 +57,17 @@ This section provides some additional clarification of those comments. #### Table of Attributes The attributes supported by `com.intellij.applicationConfigurable` and `com.intellij.projectConfigurable` EPs are in the table below: -| Attribute |Implementation
Basis | Required   | Attribute
Value | +| Attribute |Implementation
Basis | Required   | Attribute
Value | | :---------- | :----- | :--------: |:------ | | `instance` | `Configurable` | (1) | FQN of implementation. See [The Configurable Interface](#the-configurable-interface) for more information. | | `provider` | `ConfigurableProvider` | (1) | FQN of implementation. See [The ConfigurableProvider Class](#the-configurableprovider-class) for more information. | -| `nonDefaultProject` | `Configurable` | Y | Applicable _only_ to the `com.intellij.projectConfigurable` (project Settings) EP.
`true` = show Settings for all projects _except_ the [default project](https://www.jetbrains.com/help/idea/configure-project-settings.html#new-default-settings).
`false` = show Settings for all projects. | -| `displayName` | `Configurable`
`ConfigurableProvider` | (2) | The non-localized Settings name visible to users, which is needed for the Settings dialog left-side menu.
For a _localized_ visible name omit `displayName` and use the `key` and `bundle` attributes. | -| `key` and
`bundle` | `Configurable`
`ConfigurableProvider` | (2) | The [localization](/reference_guide/localization_guide.md) key and bundle for the Settings name visible to users.
For non-localized visible names omit `key` and `bundle` and use `displayName`. | -| `id` | `Configurable`
`ConfigurableProvider` | Y | The unique, FQN identifier for this implementation.
The FQN should be based on the plugin `id` to ensure uniqueness. | -| `parentId` | `Configurable`
`ConfigurableProvider` | Y | This attribute is used to create a hierarchy of Settings. This component is declared one of the specified `parentId` component's children. Typically used for placing a Settings panel within the Settings Dialog menu. Acceptable values for `parentId` are given in [Values for Parent ID Attribute](#values-for-parent-id-attribute).
`groupId` is deprecated.(3) | -| `groupWeight` | `Configurable`
`ConfigurableProvider` | N | Specifies the weight (stacking order) of this component within the group of a parent configurable component. The default weight is 0, meaning lowest in the order.
If one child in a group or a parent component has non-zero weight, all children will be sorted descending by their weight. If the weights are equal, the components will be sorted ascending by their display name. | -| `dynamic` | `Configurable.Composite` | N | This component's children are dynamically calculated by calling the `getConfigurables()` method.
Not recommended because it requires loading additional classes while building a Settings tree. If possible, use XML attributes instead. | +| `nonDefaultProject` | `Configurable` | Y | Applicable _only_ to the `com.intellij.projectConfigurable` (project Settings) EP.
`true` = show Settings for all projects _except_ the [default project](https://www.jetbrains.com/help/idea/configure-project-settings.html#new-default-settings).
`false` = show Settings for all projects. | +| `displayName` | `Configurable`
`ConfigurableProvider` | (2) | The non-localized Settings name visible to users, which is needed for the Settings dialog left-side menu.
For a _localized_ visible name omit `displayName` and use the `key` and `bundle` attributes. | +| `key` and
`bundle` | `Configurable`
`ConfigurableProvider` | (2) | The [localization](localization_guide.md) key and bundle for the Settings name visible to users.
For non-localized visible names omit `key` and `bundle` and use `displayName`. | +| `id` | `Configurable`
`ConfigurableProvider` | Y | The unique, FQN identifier for this implementation.
The FQN should be based on the plugin `id` to ensure uniqueness. | +| `parentId` | `Configurable`
`ConfigurableProvider` | Y | This attribute is used to create a hierarchy of Settings. This component is declared one of the specified `parentId` component's children. Typically used for placing a Settings panel within the Settings Dialog menu. Acceptable values for `parentId` are given in [Values for Parent ID Attribute](#values-for-parent-id-attribute).
`groupId` is deprecated.(3) | +| `groupWeight` | `Configurable`
`ConfigurableProvider` | N | Specifies the weight (stacking order) of this component within the group of a parent configurable component. The default weight is 0, meaning lowest in the order.
If one child in a group or a parent component has non-zero weight, all children will be sorted descending by their weight. If the weights are equal, the components will be sorted ascending by their display name. | +| `dynamic` | `Configurable.Composite` | N | This component's children are dynamically calculated by calling the `getConfigurables()` method.
Not recommended because it requires loading additional classes while building a Settings tree. If possible, use XML attributes instead. | | `childrenEPName` | `Configurable` | N | Specifies the FQN name of the Extension Point that will be used to calculate the children of this component. | **Attribute Notes:** @@ -95,7 +92,6 @@ See the [previous section](#table-of-attributes) for all supported attributes. |`other` | Catch-all | The IntelliJ Platform no longer uses this group. Do not use this group. Use the `tools` group instead. | |`project` | Project-related Settings | The IntelliJ Platform no longer uses this group. It was intended to store some project-related settings. Do not use this group. | - ## Implementations for Settings Extension Points Implementations for `com.intellij.projectConfigurable` and `com.intellij.applicationConfigurable` EPs can have one of two bases: * The [`Configurable`](upsource:///platform/platform-api/src/com/intellij/openapi/options/Configurable.java) interface, which provides a named configurable component with a Swing form. @@ -114,7 +110,9 @@ Implementations must meet several requirements for constructors. For a `Configurable` implementation correctly declared using an EP, the implementation's constructor is not invoked by the IntelliJ Platform until a user chooses the corresponding Settings `displayName` in the Settings Dialog menu. -> **WARNING** The IntelliJ Platform may instantiate a `Configurable` implementation on a background thread, so creating Swing components in a constructor can degrade UI responsiveness. + > The IntelliJ Platform may instantiate a `Configurable` implementation on a background thread, so creating Swing components in a constructor can degrade UI responsiveness. + > + {type="warning"} #### IntelliJ Platform Interactions with Configurable The instantiation of a generic `Configurable` implementation is documented in the interface file. @@ -151,4 +149,4 @@ If the Settings make sense to display, `canCreateConfigurable()` returns `true`. In that case the IntelliJ Platform calls `ConfigurableProvider.createConfigurable()`, which returns the `Configurable` object for its Settings implementation. By choosing not to provide a `Configuration` implementation in some circumstances, the `ConfigurableProvider` opts out of the Settings display and modification process. -The use of `ConfigurableProvider` as a basis for a Settings implementation is declared using [attributes](#table-of-attributes) in the EP declaration. +The use of `ConfigurableProvider` as a basis for a Settings implementation is declared using [attributes](#table-of-attributes) in the EP declaration. \ No newline at end of file diff --git a/reference_guide/tomcat_integration.md b/topics/reference_guide/tomcat_integration.md similarity index 84% rename from reference_guide/tomcat_integration.md rename to topics/reference_guide/tomcat_integration.md index bf84d048c..4cc796a5d 100644 --- a/reference_guide/tomcat_integration.md +++ b/topics/reference_guide/tomcat_integration.md @@ -1,7 +1,6 @@ ---- -title: Tomcat Integration ---- +[//]: # (title: Tomcat Integration) + The source code of the Tomcat plugin included in IntelliJ IDEA Ultimate is available as a sample for implementing application server integration plugins. -You can find the code under *lib\src\src_tomcat.zip* in the main IntelliJ IDEA Ultimate distribution. +You can find the code under *lib\src\src_tomcat.zip* in the main IntelliJ IDEA Ultimate distribution. \ No newline at end of file diff --git a/reference_guide/ui_themes/themes.md b/topics/reference_guide/ui_themes/themes.md similarity index 88% rename from reference_guide/ui_themes/themes.md rename to topics/reference_guide/ui_themes/themes.md index 0859c1152..7808c52bf 100644 --- a/reference_guide/ui_themes/themes.md +++ b/topics/reference_guide/ui_themes/themes.md @@ -1,6 +1,5 @@ ---- -title: Creating Custom UI Themes ---- +[//]: # (title: Creating Custom UI Themes) + Creating a custom UI Theme is a process of choosing a base IDE Theme (_Light_ or _Darcula_,) then changing aspects of the base Theme definition. @@ -24,18 +23,17 @@ UI Themes have several components: * An optional background image file, located in the plugin project's `resources` folder. * Optional icon image files, located in the plugin project's `resources` folder. -![UI Theme Components](img/theme_components.png) +![UI Theme Components](theme_components.png) ## Custom UI Theme Workflow Creating a UI Theme follows this general sequence: -* [Start with a Plugin Project](/basics/getting_started/creating_plugin_project.md) +* [Start with a Plugin Project](creating_plugin_project.md) * [Add UI Theme components to the plugin](#creating-a-ui-theme-with-the-devkit-theme-wizard) by using the DevKit UI Theme Wizard. * [Customize the UI Theme](themes_customize.md) by adding data objects to the Theme description (JSON) file. * [Add an Editor Scheme or Background Image](themes_extras.md) to the plugin. -* [Build and test](/basics/getting_started/running_and_debugging_a_plugin.md) the UI Theme plugin. -* [Deploy the UI Theme plugin](/basics/getting_started/deploying_plugin.md) -* [Publish the UI Theme plugin](/basics/getting_started/publishing_plugin.md) - +* [Build and test](running_and_debugging_a_plugin.md) the UI Theme plugin. +* [Deploy the UI Theme plugin](deploying_plugin.md) +* [Publish the UI Theme plugin](publishing_plugin.md) ## Creating Custom UI Themes @@ -48,13 +46,13 @@ This Wizard can be used for both DevKit-based and Gradle-based plugins. While a plugin project is open in IntelliJ IDEA, select the `resources` folder in the _Project_ tool window. From the main menu, select the _**New | Plugin DevKit | Theme**_ action. -![DevKit Wizard Action](img/devkit_wiz_action.png) +![DevKit Wizard Action](devkit_wiz_action.png) -
+
The Wizard then prompts for the name of the new Theme, and the basis for the Theme: -![DevKit Dialog](img/devkit_wiz_dialog.png) +![DevKit Dialog](devkit_wiz_dialog.png) The best practice is to name the new Theme the same as the name of the plugin. The checkbox indicates the basis for the Theme. @@ -92,7 +90,9 @@ This declaration binds the Theme description file to a theme provider extension ``` -> **WARNING** Do not modify or re-use an existing value of the generated `id` attribute. + > Do not modify or re-use an existing value of the generated `id` attribute. + > + {type="warning"} At this point, the UI Theme `theme_basics` is a valid UI Theme. Its plugin can be built and tested in IntelliJ Platform-based IDEs, giving the user the opportunity to select _theme_basics_ in the [Theme](https://www.jetbrains.com/help/idea/settings-appearance.html) _Preferences_ dropdown. @@ -103,4 +103,4 @@ The default UI Theme definition can be directly edited to add or change some of The following values can be changed directly in the Theme (`*.theme.json`) description file: * The value of the `dark` key can be changed to `true`, which would switch the basis of the Theme to _Darcula_ instead of _Light_. * The value of the `author` key, which defaults to an empty string, can be set to a `String` literal. -In the case of the `theme_basics` code sample, it is set to "IntelliJ Platform SDK". +In the case of the `theme_basics` code sample, it is set to "IntelliJ Platform SDK". \ No newline at end of file diff --git a/reference_guide/ui_themes/themes_customize.md b/topics/reference_guide/ui_themes/themes_customize.md similarity index 94% rename from reference_guide/ui_themes/themes_customize.md rename to topics/reference_guide/ui_themes/themes_customize.md index 29b623ad1..828354d70 100644 --- a/reference_guide/ui_themes/themes_customize.md +++ b/topics/reference_guide/ui_themes/themes_customize.md @@ -1,19 +1,6 @@ ---- -title: Customizing UI Themes - Icons and UI Controls ---- - +[//]: # (title: Customizing UI Themes - Icons and UI Controls) - + A UI Theme is customized by adding information to the UI Theme description file that overrides the base (_Light_ or _Darcula_) UI Theme. @@ -91,7 +78,7 @@ Note that this document refers to `Objects` keys as "Noun icons." An icon Palette color is customized by adding an `Actions` or `Objects` `key` and custom color `value` to the `"ColorPalette": {}` section in a Theme description file. The list of available icon `Actions` and `Objects` keys are provided by the editor's completion popup: -![Color Palette Popup](img/theme_colorpalette_popup.png){:width="600px"} +![Color Palette Popup](theme_colorpalette_popup.png){width="600"} For example, the following key-value pair changes the color for all blue-colored icons on toolbars to the color `#5BC0DE`: @@ -117,7 +104,7 @@ An icon replacement is described within the `icon {}` section of a Theme descrip Note that icon replacement key-value pairs appear outside of the `ColorPalette` section. For icon substitutions, the `key` is the path to the default icon image. -This path is derived from the `AllIcons.[Group].[IconName]` path in icon section reported by the [UI Inspector](/reference_guide/internal_actions/internal_ui_inspector.md). +This path is derived from the `AllIcons.[Group].[IconName]` path in icon section reported by the [UI Inspector](internal_ui_inspector.md). For example, the _Build_ (hammer) icon in the toolbar has the path `Allcons.Actions.Compile` as reported by the UI Inspector. Therefore the `key` for the _Build_ icon is `/actions/compile.svg`. @@ -133,7 +120,9 @@ The `value` is the replacement icon's file name, located in the `resources` fold The color of a replaced icon takes precedence over any `ColorPalette` overrides. -> **TIP** For generating the SVG icons suited for the IntelliJ-based IDEs, you may also use the third-party web tool – [IntelliJ Icon Generator](https://bjansen.github.io/intellij-icon-generator/). + > For generating the SVG icons suited for the IntelliJ-based IDEs, you may also use the third-party web tool – [IntelliJ Icon Generator](https://bjansen.github.io/intellij-icon-generator/). + > + {type="tip"} ## Customizing UI Controls UI Themes can change the appearance of more general controls in the IntelliJ Platform UI. @@ -270,7 +259,7 @@ In this example, the customized border supersedes the default definition and any ## Finding Attribute Keys for UI Controls There are hundreds of UI control `element.property` keys defined in the IntelliJ Platform UI. -Some keys and strategies for applying them can be gleaned from the [UI Theme reference implementations](#UI-Theme-Reference-Implementations). +Some keys and strategies for applying them can be gleaned from the [UI Theme reference implementations](#ui-theme-reference-implementations). For a general search, here some suggested methods for locating UI control keys. ### Finding a UI Control Key Using Code Completion in the Editor @@ -278,7 +267,7 @@ The preferred method of finding UI control keys is to use the [Code Completion]( Note that some keys presented by the code completion feature may be deprecated. New entries in the `"ui": {}` section will invoke the code completion popup, as shown below: -![UI Control Key Code Completion](img/uit_control_complete.png) +![UI Control Key Code Completion](uit_control_complete.png) Beginning with version 2019.2 of the IntelliJ Platform, the editor has added features for Code Completion and [Quick Documentation](https://www.jetbrains.com/help/idea/viewing-reference-information.html#inline-quick-documentation) to show the release in which a UI control key began to be supported. It appears as the _Since_ attribute in editor popups. @@ -286,5 +275,5 @@ In the Quick Documentation popup, the format is e.g., _Since: 2019.2_. The Code Completion popup is similar, but the format is e.g., _[Since 2019.2]_. ### Finding a UI Control Key Using Laf Defaults UI -Using the [Laf Defaults](/reference_guide/internal_actions/internal_ui_laf_defaults.md) inspector, enter the `element` portion of the key. -The Laf Defaults inspector will prompt with a list of UI Control keys and their default color. +Using the [Laf Defaults](internal_ui_laf_defaults.md) inspector, enter the `element` portion of the key. +The Laf Defaults inspector will prompt with a list of UI Control keys and their default color. \ No newline at end of file diff --git a/reference_guide/ui_themes/themes_extras.md b/topics/reference_guide/ui_themes/themes_extras.md similarity index 97% rename from reference_guide/ui_themes/themes_extras.md rename to topics/reference_guide/ui_themes/themes_extras.md index cd19d2585..2e0744732 100644 --- a/reference_guide/ui_themes/themes_extras.md +++ b/topics/reference_guide/ui_themes/themes_extras.md @@ -1,6 +1,5 @@ ---- -title: UI Themes - Editor Schemes and Background Images ---- +[//]: # (title: UI Themes - Editor Schemes and Background Images) + UI Themes can also provide custom color and font settings, as well as custom images for display in the IDE application window. @@ -76,7 +75,9 @@ For additional examples of `FILESTATUS` color `name` attributes, see the editor Editor scroll bar colors should be coordinated with, and switch together with an editor color scheme. Please note that Custom UI Theme (`*.theme.json`) files also contain `ScrollBar.*` name attributes, but these are for scroll bars outside the context of the editor. -> **NOTE** The Editor Scroll Bar colors are the only editor scheme settings that cannot be customized and exported through IDE preferences. + > The Editor Scroll Bar colors are the only editor scheme settings that cannot be customized and exported through IDE preferences. + > + {type="note"} Customizing the editor scroll bar colors requires manually changing an editor color scheme XML file. At this time there isn't code completion functionality for changing custom color editor scheme XML files, so the `name` attributes are described below. @@ -132,7 +133,6 @@ The `name` attribute pattern for the horizontal scroll bar depends on the macOS The wildcard portion of these patterns corresponds to the `usage` definitions above. - ## Adding a Custom Background Image The IDE supports setting an image as a background in the application window. Users can do this manually in [Preferences](https://www.jetbrains.com/help/idea/setting-background-image.html). @@ -145,7 +145,6 @@ A `value` of 100 is opaque. * The `fill` key uses a value of `scale`, meaning to expand the image to fill the space as the window gets resized. * The `anchor` key uses a value of `center`, meaning to locate the center of the image in the center of the window. - The following example adds an image of the Austrian countryside to the _Theme Basics_ Theme description file: @@ -163,4 +162,4 @@ Theme description file: "anchor": "center" } } -``` +``` \ No newline at end of file diff --git a/reference_guide/ui_themes/themes_intro.md b/topics/reference_guide/ui_themes/themes_intro.md similarity index 73% rename from reference_guide/ui_themes/themes_intro.md rename to topics/reference_guide/ui_themes/themes_intro.md index f8d24745e..23210a69b 100644 --- a/reference_guide/ui_themes/themes_intro.md +++ b/topics/reference_guide/ui_themes/themes_intro.md @@ -1,19 +1,20 @@ ---- -title: Custom UI Themes ---- +[//]: # (title: Custom UI Themes) + Beginning with the 2019.1 release, custom UI Themes are supported. Custom UI Themes give designers control of the appearance of built-in UI elements. The [UI Themes available for download](https://plugins.jetbrains.com/search?headline=164-theme&tags=Theme) illustrate the creative possibilities. -[Creating a new UI element](/user_interface_components/user_interface_components.md) for a plugin is distinctly different than Custom UI Themes. +[Creating a new UI element](user_interface_components.md) for a plugin is distinctly different than Custom UI Themes. -> **NOTE** Custom UI Themes are available beginning in version **2019.1**. + > Custom UI Themes are available beginning in version **2019.1**. + > + {type="note"} This section discusses creating and customizing UI Themes: * [Creating UI Themes](themes.md) * [Customizing UI Themes](themes_customize.md) * [Adding Editor Schemes and Background Images](themes_extras.md) -For plugin developers, [Exposing Theme Metadata](themes_metadata.md) discusses the format of customization keys and information how to provide it to Theme authors. +For plugin developers, [Exposing Theme Metadata](themes_metadata.md) discusses the format of customization keys and information how to provide it to Theme authors. \ No newline at end of file diff --git a/reference_guide/ui_themes/themes_metadata.md b/topics/reference_guide/ui_themes/themes_metadata.md similarity index 94% rename from reference_guide/ui_themes/themes_metadata.md rename to topics/reference_guide/ui_themes/themes_metadata.md index 714198175..c7c948126 100644 --- a/reference_guide/ui_themes/themes_metadata.md +++ b/topics/reference_guide/ui_themes/themes_metadata.md @@ -1,18 +1,4 @@ ---- -title: Exposing Theme Metadata ---- - - +[//]: # (title: Exposing Theme Metadata) All available UI Customization Keys that can be used in [Custom Themes](themes_customize.md) must be defined in a dedicated `*.themeMetadata.json` file which is registered via `com.intellij.themeMetadataProvider` extension point. @@ -21,12 +7,10 @@ The following minimal sample demonstrates all details required when exposing UI `/resources/META-INF/plugin.xml`: ```xml - - [...] + - - [...] + ``` @@ -62,11 +46,17 @@ The following minimal sample demonstrates all details required when exposing UI - `since` - The release number (e.g. `[2019.2]`) when this UI customization key was exposed. A release number prior to 2019.2 is valid. -> **NOTE** Support for the `since` attribute began with version 2019.2, so this attribute is only displayed in versions 2019.2 and later. + > Support for the `since` attribute began with version 2019.2, so this attribute is only displayed in versions 2019.2 and later. + > + {type="note"} -> **TIP** It is highly recommended to always provide a `description` entry, so Theme authors can understand usages. + > It is highly recommended to always provide a `description` entry, so Theme authors can understand usages. + > + {type="tip"} -> **TIP** Do not remove existing keys, but deprecate them instead to help Theme authors upgrade their existing themes. + > Do not remove existing keys, but deprecate them instead to help Theme authors upgrade their existing themes. + > + {type="tip"} Color keys can be used via `JBColor.namedColor()` providing defaults for Light and Dark theme: @@ -83,7 +73,7 @@ All keys must follow this Naming Pattern: **`Object[.SubObject].[state][Part]Property`** -![Key Naming Pattern](img/keys-naming.png){:width="735"} +![Key Naming Pattern](keys-naming.png){width="735"} #### Property @@ -162,7 +152,9 @@ Examples of Swing keys: - `TableHeader.background` Correct: `Table.Header.background` ## IntelliJ Platform Metadata -> **NOTE** This section is relevant for IntelliJ Platform developers only. + > This section is relevant for IntelliJ Platform developers only. + > + {type="note"} Metadata is split up as follows: - [`IntelliJPlatform.themeMetadata.json`](upsource:///platform/platform-resources/src/themes/metadata/IntelliJPlatform.themeMetadata.json) - all keys from IntelliJ Platform and custom UI components @@ -171,4 +163,4 @@ Metadata is split up as follows: New keys should be added to `IntelliJPlatform.themeMetadata.json` only (or corresponding "local" `*.themeMetadata.json` file of the plugin if applicable). Please make sure to add a `description` and use `since` and `deprecated` attributes explained in [Attributes](#attributes). -Respect [Key Naming Scheme](#key-naming-scheme) and keep alphabetical ordering of keys. +Respect [Key Naming Scheme](#key-naming-scheme) and keep alphabetical ordering of keys. \ No newline at end of file diff --git a/reference_guide/vcs_integration_for_plugins.md b/topics/reference_guide/vcs_integration_for_plugins.md similarity index 97% rename from reference_guide/vcs_integration_for_plugins.md rename to topics/reference_guide/vcs_integration_for_plugins.md index a7106f450..5801b5425 100644 --- a/reference_guide/vcs_integration_for_plugins.md +++ b/topics/reference_guide/vcs_integration_for_plugins.md @@ -1,6 +1,5 @@ ---- -title: Version Control Systems ---- +[//]: # (title: Version Control Systems) + This page gives an overview of the Version Control Integration API. @@ -74,7 +73,9 @@ There are two main kinds of changelists: For VCSes which use per-file commit (like CVS), the plugin can use heuristics to group a sequence of individual file commits into a [`CommittedChangeList`](upsource:///platform/vcs-api/src/com/intellij/openapi/vcs/versionBrowser/CommittedChangeList.java) -> **NOTE** The *Unversioned Files*, *Locally Deleted Files*, etc., nodes in the *Changes* view are not actually change lists, and files under those nodes are not represented by `ChangeList` objects. + > The *Unversioned Files*, *Locally Deleted Files*, etc., nodes in the *Changes* view are not actually change lists, and files under those nodes are not represented by `ChangeList` objects. + > + {type="note"} ## Plugin Components @@ -117,4 +118,4 @@ The [`ChangeProvider`](upsource:///platform/vcs-api/src/com/intellij/openapi/vcs * `processLocallyDeletedFile()` is called for files which exist in the VCS repository, but do not exist on disk and are not scheduled for deletion. * `processIgnoredFile()` is called for files which are not managed by the VCS but are ignored through *.cvsignore* or a similar mechanism. * `processSwitchedFile()` is called for files or directories for which the working copy corresponds to a different branch compared to the working copy of their parent directory. - This can be called for the same files for which processSwitchedFile() has already been called. + This can be called for the same files for which processSwitchedFile() has already been called. \ No newline at end of file diff --git a/reference_guide/work_with_icons_and_images.md b/topics/reference_guide/work_with_icons_and_images.md similarity index 79% rename from reference_guide/work_with_icons_and_images.md rename to topics/reference_guide/work_with_icons_and_images.md index 874fcffef..ba65fed5b 100644 --- a/reference_guide/work_with_icons_and_images.md +++ b/topics/reference_guide/work_with_icons_and_images.md @@ -1,16 +1,19 @@ ---- -title: Working with Icons and Images ---- +[//]: # (title: Working with Icons and Images) + Icons and images are used widely by IntelliJ Platform plugins. Plugins need icons mostly for actions, custom components renderers, tool windows, and so on. -> **NOTE** Plugin Icons, which represent a plugin itself, have different requirements than icons and images used within a plugin. -For more information see the [Plugin Icon](/basics/plugin_structure/plugin_icon_file.md) page. + > Plugin Icons, which represent a plugin itself, have different requirements than icons and images used within a plugin. +For more information see the [Plugin Icon](plugin_icon_file.md) page. + > + {type="note"} -> **TIP** Plugins should reuse existing platform icons whenever possible, see [Icons list](https://jetbrains.design/intellij/resources/icons_list/) and [`AllIcons`](upsource:///platform/util/src/com/intellij/icons/AllIcons.java). + > Plugins should reuse existing platform icons whenever possible, see [Icons list](https://jetbrains.design/intellij/resources/icons_list/) and [`AllIcons`](upsource:///platform/util/src/com/intellij/icons/AllIcons.java). > A detailed [design guideline](https://jetbrains.design/intellij/principles/icons/) is available for creating custom icons. + > + {type="tip"} ## How to organize and how to use icons? @@ -18,7 +21,9 @@ The best way to deal with icons and other image resources is to put them to a de The `getIcon()` method of [`IconLoader`](upsource:///platform/util/ui/src/com/intellij/openapi/util/IconLoader.java) can be used to access the icons. -> **NOTE** The path to the icon passed in as argument to `IconLoader.getIcon()` must start with leading `/` + > The path to the icon passed in as argument to `IconLoader.getIcon()` must start with leading `/` + > + {type="note"} Then define a class/interface in a top-level package called `icons` holding icon constants as static fields: @@ -76,9 +81,10 @@ Required icon sizes depend on the usage as listed in the following table: | Tool window | 13x13 | | Editor gutter | 12x12 | - ### SVG Format -> **NOTE** SVG icons are supported since 2018.2. + > SVG icons are supported since 2018.2. + > + {type="note"} As SVG icons can be scaled arbitrarily, they provide better results on HiDPI environments or when used in combination with bigger screen fonts (e.g., in presentation mode). @@ -99,10 +105,14 @@ However, the `@2x` version of an SVG icon should still provide the same base siz The icon graphics of such an icon can be expressed in more details via double precision. If the icon graphics are simple enough so that it renders perfectly in every scale, then the `@2x` version can be omitted. -> **TIP** For generating the SVG icons suited for the IntelliJ-based IDEs, you may also use the third-party web tool – [IntelliJ Icon Generator](https://bjansen.github.io/intellij-icon-generator/). + > For generating the SVG icons suited for the IntelliJ-based IDEs, you may also use the third-party web tool – [IntelliJ Icon Generator](https://bjansen.github.io/intellij-icon-generator/). + > + {type="tip"} ### PNG Format -> **NOTE** Please consider using SVG icons if your plugin targets 2018.2+. + > Please consider using SVG icons if your plugin targets 2018.2+. + > + {type="note"} All icon files must be placed in the same directory following this naming pattern (replace `.png` with `.svg` for SVG icons): @@ -117,7 +127,7 @@ Here are examples of *toolWindowStructure.png* icon representations: | Theme/Resolution | File name | Image | | ---------------- | --------------------------------- | --------------------------------------------------------------------------- | -| Default | `toolWindowStructure.png` | ![Tool Window Structure](img/toolWindowStructure.png) | -| Darcula | `toolWindowStructure_dark.png` | ![Tool Window Structure, dark](img/toolWindowStructure_dark.png) | -| Default + Retina | `toolWindowStructure@2x.png` | ![Tool Window Structure, retina](img/toolWindowStructure@2x.png) | -| Darcula + Retina | `toolWindowStructure@2x_dark.png` | ![Tool Window Structure, retina, dark](img/toolWindowStructure@2x_dark.png) | +| Default | `toolWindowStructure.png` | ![Tool Window Structure](toolWindowStructure.png) | +| Darcula | `toolWindowStructure_dark.png` | ![Tool Window Structure, dark](toolWindowStructure_dark.png) | +| Default + Retina | `toolWindowStructure@2x.png` | ![Tool Window Structure, retina](toolWindowStructure@2x.png) | +| Darcula + Retina | `toolWindowStructure@2x_dark.png` | ![Tool Window Structure, retina, dark](toolWindowStructure@2x_dark.png) | \ No newline at end of file diff --git a/tutorials/action_system.md b/topics/tutorials/action_system.md similarity index 72% rename from tutorials/action_system.md rename to topics/tutorials/action_system.md index 1dce706dc..97c23165c 100644 --- a/tutorials/action_system.md +++ b/topics/tutorials/action_system.md @@ -1,12 +1,10 @@ ---- -title: IntelliJ Action System Tutorial ---- +[//]: # (title: IntelliJ Action System Tutorial) + This tutorial leads you through a series of steps which show how to create, register, and customize custom actions and action groups. By registering actions, you can add your own menu items, toolbar buttons and keyboard shortcuts to the IDE user interface. -* [Creating Actions](action_system/working_with_custom_actions.md) -* [Grouping Actions](action_system/grouping_action.md) +* [Creating Actions](working_with_custom_actions.md) +* [Grouping Actions](grouping_action.md) - -The source code for the [`action_basics`](https://github.com/JetBrains/intellij-sdk-code-samples/tree/master/action_basics) code sample is used throughout this tutorial. +The source code for the [`action_basics`](https://github.com/JetBrains/intellij-sdk-code-samples/tree/master/action_basics) code sample is used throughout this tutorial. \ No newline at end of file diff --git a/tutorials/action_system/grouping_action.md b/topics/tutorials/action_system/grouping_action.md similarity index 93% rename from tutorials/action_system/grouping_action.md rename to topics/tutorials/action_system/grouping_action.md index 989a0a298..ed48a37a5 100644 --- a/tutorials/action_system/grouping_action.md +++ b/topics/tutorials/action_system/grouping_action.md @@ -1,6 +1,5 @@ ---- -title: Grouping Actions ---- +[//]: # (title: Grouping Actions) + If an implementation requires several actions, or there are simply too many actions that overload the menu, the actions can be placed into groups. @@ -9,9 +8,6 @@ The sample code discussed in this tutorial is from the code sample [`action_basi Some content in this tutorial assumes the reader is familiar with the tutorial for [Creating Actions](working_with_custom_actions.md). -* bullet list -{:toc} - ## Simple Action Groups In this first example, the action group will be available as a top-level menu item, and actions are represented as drop-down menu items. The group is based on a default IntelliJ Platform implementation. @@ -23,9 +19,9 @@ This default implementation is used if a set of actions belonging to the group i The `id` attribute must be unique, so incorporating the plugin ID or package name is the best practice. The `popup` attribute determines whether actions in the group are placed in a submenu. -The `icon` attribute specifies the FQN of an [`Icon`](/reference_guide/work_with_icons_and_images.md) object to be displayed. +The `icon` attribute specifies the FQN of an [`Icon`](work_with_icons_and_images.md) object to be displayed. No `compact` attribute is specified, which means this group will support submenus. -See [Registering Actions in plugin.xml](/basics/action_system.md#registering-actions-in-pluginxml) for more information about these attributes. +See [Registering Actions in plugin.xml](basic_action_system.md#registering-actions-in-pluginxml) for more information about these attributes. ```xml @@ -62,11 +58,10 @@ The action in this group will display the menu text "A Group Action". After performing the steps described above, the action group and its content will be available in the **Tools** menu. The underlying `PopupDialogAction` implementation is reused for two entries in the **Tools** menu: -* Once for the top menu entry **Tools \| Pop Dialog Action** with the action `id` equal to `org.intellij.sdk.action.PopupDialogAction` as set in the [Creating Actions](/tutorials/action_system/working_with_custom_actions.md#registering-an-action-with-the-new-action-form) tutorial. +* Once for the top menu entry **Tools \| Pop Dialog Action** with the action `id` equal to `org.intellij.sdk.action.PopupDialogAction` as set in the [Creating Actions](working_with_custom_actions.md#registering-an-action-with-the-new-action-form) tutorial. * A second time for the menu entry **Tools \| Static Grouped Actions \| A Group Action** with the action `id` equal to `org.intellij.sdk.action.GroupPopDialogAction`. -![Simple Action Group](img/grouped_action.png){:width="550px"} - +![Simple Action Group](grouped_action.png){width="550"} ## Implementing Custom Action Group Classes In some cases, the specific behavior of a group of actions needs to depend on the context. @@ -134,7 +129,7 @@ In the `` element declaration below: ``` -Now the translations for the `text` and `description` attributes must be provided in the resource bundle [`BasicActionsBundle.properties`](https://github.com/JetBrains/intellij-sdk-code-samples/blob/master/action_basics/src/main/resources/messages/BasicActionsBundle.properties) file according to [Localizing Actions and Groups](/basics/action_system.md#localizing-actions-and-groups). +Now the translations for the `text` and `description` attributes must be provided in the resource bundle [`BasicActionsBundle.properties`](https://github.com/JetBrains/intellij-sdk-code-samples/blob/master/action_basics/src/main/resources/messages/BasicActionsBundle.properties) file according to [Localizing Actions and Groups](basic_action_system.md#localizing-actions-and-groups). Note there are two sets of `text` and `description` translations, one for the action and one for the group. Conceivably, there could be another set of translations for the action if it used the `` attribute. @@ -166,8 +161,7 @@ After compiling and running the code sample above and opening a file in the edit Note the group and actions come from the resource file as all contain the suffix "[en]". The new group will also have an icon: -![Custom Action Group](img/editor_popup_menu.png) - +![Custom Action Group](editor_popup_menu.png) ## Action Groups with Variable Actions Sets If a set of actions belonging to a custom group varies depending on the context, the group must extend [`ActionGroup`](upsource:///platform/editor-ui-api/src/com/intellij/openapi/actionSystem/ActionGroup.java). @@ -193,8 +187,10 @@ When enabled, this group appears at the entry just below the [Static Grouped Act ``` -> **WARNING** If a`` element's `class` attribute names a class derived from `ActionGroup`, then any static `` declarations in that group throw an exception. + > If a`` element's `class` attribute names a class derived from `ActionGroup`, then any static `` declarations in that group throw an exception. For a statically defined group, use `DefaultActionGroup`. + > + {type="warning"} ### Adding Child Actions to the Dynamic Group To add actions to the `DynamicActionGroup`, a non-empty array of `AnAction` instances should be returned from the `DynamicActionGroup.getChildren()` method. @@ -215,4 +211,4 @@ public class DynamicActionGroup extends ActionGroup { After providing the implementation of `DynamicActionGroup` and making it return a non-empty array of actions, the third position in the **Tools** menu will contain a new group of actions: -![Dynamic Action Group](img/dynamic_action_group.png){:width="600px"} +![Dynamic Action Group](dynamic_action_group.png){width="600"} \ No newline at end of file diff --git a/tutorials/action_system/working_with_custom_actions.md b/topics/tutorials/action_system/working_with_custom_actions.md similarity index 86% rename from tutorials/action_system/working_with_custom_actions.md rename to topics/tutorials/action_system/working_with_custom_actions.md index 5175d9be1..9ebdd9695 100644 --- a/tutorials/action_system/working_with_custom_actions.md +++ b/topics/tutorials/action_system/working_with_custom_actions.md @@ -1,6 +1,5 @@ ---- -title: Creating Actions ---- +[//]: # (title: Creating Actions) + ## Introduction @@ -10,9 +9,6 @@ However, the actions of a plugin must first be defined and registered with the I Using the SDK code sample `action_basics`, this tutorial illustrates the steps to create an action for a plugin. -* bullet list -{:toc} - ## Creating a Custom Action Custom actions extend the abstract class [`AnAction`](upsource:///platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java). Classes that extend it should override `AnAction.update()`, and must override `AnAction.actionPerformed()`. @@ -37,9 +33,11 @@ public class PopupDialogAction extends AnAction { } ``` -> **WARNING** `AnAction` classes do not have class fields of any kind. + > `AnAction` classes do not have class fields of any kind. > This restriction prevents memory leaks. -> For more information about why, see [Action Implementation](/basics/action_system.md#action-implementation). +> For more information about why, see [Action Implementation](basic_action_system.md#action-implementation). + > + {type="warning"} At this stage, `update()` implicitly defaults always to enable this action. The implementation of `actionPerformed()` does nothing. @@ -50,19 +48,19 @@ Before fleshing out those methods, to complete this minimal implementation, `Pop ## Registering a Custom Action Actions are registered by declaring them in code or by declaring them in the `` section of a plugin configuration (`plugin.xml`) file. This section describes using IDE tooling - the New Action Form - to add a declaration to the `plugin.xml` file, and then tuning registration attributes manually. -A more comprehensive explanation of action registration is available in the [Action Registration](/basics/action_system.md#registering-actions) section of this guide. +A more comprehensive explanation of action registration is available in the [Action Registration](basic_action_system.md#registering-actions) section of this guide. ### Registering an Action with the New Action Form IntelliJ IDEA has an embedded inspection that spots unregistered actions. Verify the inspection is enabled at **Settings/Preferences \| Editor \| Inspections \| Plugin DevKit \| Code \| Component/Action not registered**. Here is an example for this stage of the `PopupDialogAction` class: -!["Action never used" inspection](img/action_never_used.png){:width="600px"} +!["Action never used" inspection](action_never_used.png){width="600"} To register `PopupDialogAction` and set up its basic attributes press ***Alt + Shift + Enter***. Fill out the **New Action** form to set up the parameters for `PopupDialogAction`: -![New Action](img/new_action.png){:width="800px"} +![New Action](new_action.png){width="800"} The fields of the form are: * _Action ID_ - Every action must have a unique ID. @@ -96,11 +94,11 @@ This declaration is adequate, but adding more attributes is discussed in the nex ### Setting Registration Attributes Manually An action declaration can be added manually to the `plugin.xml` file. -An exhaustive list of declaration elements and attributes is presented in [Registering Actions in plugin.xml](/basics/action_system.md#registering-actions-in-pluginxml). +An exhaustive list of declaration elements and attributes is presented in [Registering Actions in plugin.xml](basic_action_system.md#registering-actions-in-pluginxml). Attributes are added by selecting them from the **New Action** form, or by editing the registration declaration directly in the plugin.xml file. The `` declaration for `PopupDialogAction` in the `action_basics` [plugin.xml](https://github.com/JetBrains/intellij-sdk-code-samples/blob/master/action_basics/src/main/resources/META-INF/plugin.xml) file. -It also contains an attribute for an [`Icon`](/reference_guide/work_with_icons_and_images.md) and encloses elements declaring text overrides, keyboard and mouse shortcuts, and to which menu group the action should be added. +It also contains an attribute for an [`Icon`](work_with_icons_and_images.md) and encloses elements declaring text overrides, keyboard and mouse shortcuts, and to which menu group the action should be added. The full declaration is: @@ -118,17 +116,17 @@ The full declaration is: By using the `override-text` element introduced in 2020.1 of the IntelliJ Platform, the action text can be different depending on the context of where the action appears: menu, toolbar, etc. The example above uses this element to ensure the shorter text "Pop Dialog Action" is shown anywhere the action appears in the Main Menu structure. Otherwise, the default, more explanatory text "Action Basics Plugin: Pop Dialog Action" is shown. -For more information, see [Setting the Override-Text Element](/basics/action_system.md#setting-the-override-text-element) +For more information, see [Setting the Override-Text Element](basic_action_system.md#setting-the-override-text-element). ## Testing the Minimal Custom Action Implementation After performing the steps described above, compile and run the plugin to see the newly created action available as a Tools Menu item, which is within the context of the Main Menu: -!["Register action"](img/tools_menu_item_action.png){:width="350px"} +!["Register action"](tools_menu_item_action.png){width="350"} To see the alternate, more verbose text declared by the `override-text` element, use **Help \| Find Action...** and search for "Pop Dialog Action". The search shows the verbose menu text in a context outside of the Main Menu: -!["Override Text Display"](img/find_action.png){:width="500px"} +!["Override Text Display"](find_action.png){width="500"} Selecting the action from the menu, keyboard/mouse shortcuts, or Find Action won't do anything at this point because the implementations are empty. However, it confirms the new entry appears at **Tools \| Pop Dialog Action** and **Help \| Find Action...**. @@ -150,7 +148,7 @@ However, code in this method could manipulate a project, invoke an inspection, c For demonstration purposes the `AnActionEvent.getData()` method tests if a [`Navigatable`](upsource:///platform/core-api/src/com/intellij/pom/Navigatable.java) object is available. If so, information about the selected element is added to the dialog. -See [Determining the Action Context](/basics/action_system.md#determining-the-action-context) for more information about accessing information from the `AnActionEvent` input parameter. +See [Determining the Action Context](basic_action_system.md#determining-the-action-context) for more information about accessing information from the `AnActionEvent` input parameter. ```java @Override @@ -172,15 +170,17 @@ See [Determining the Action Context](/basics/action_system.md#determining-the-ac Adding code to `PopupDialogAction.update()` gives finer control of the action's visibility and availability. The action's state and(or) presentation can be dynamically changed depending on the context. -> **WARNING** This method needs to _execute very quickly_. -> For more information about this constraint, see the warning in [Overriding the AnAction.update Method](/basics/action_system.md#overriding-the-anactionupdate-method). + > This method needs to _execute very quickly_. +> For more information about this constraint, see the warning in [Overriding the AnAction.update Method](basic_action_system.md#overriding-the-anactionupdate-method). + > + {type="warning"} In this example, the `update()` method relies on a `Project` object being available. This requirement means the user must have at least one project open in the IDE for the `PopupDialogAction` to be available. So the `update()` method disables the action for contexts where a `Project` object isn't defined. The availability (enabled and visible) is set on the `Presentation` object. -Setting both the enabled state and visibility produces consistent behavior despite possible host menu settings, as discussed in [Grouping Actions](/basics/action_system.md#grouping-actions). +Setting both the enabled state and visibility produces consistent behavior despite possible host menu settings, as discussed in [Grouping Actions](basic_action_system.md#grouping-actions). ```java @Override @@ -193,7 +193,7 @@ Setting both the enabled state and visibility produces consistent behavior despi The `update()` method does not check to see if a `Navigatable` object is available before enabling `PopupDialogAction`. This check is unnecessary because using the `Navigatable` object is opportunistic in `actionPerformed()`. -See [Determining the Action Context](/basics/action_system.md#determining-the-action-context) for more information about accessing information from the `AnActionEvent` input parameter. +See [Determining the Action Context](basic_action_system.md#determining-the-action-context) for more information about accessing information from the `AnActionEvent` input parameter. ### Other Method Overrides A constructor is overridden in `PopupDialogAction`, but this is an artifact of reusing this class for a dynamically created menu action. @@ -202,4 +202,4 @@ Otherwise, overriding constructors for `AnAction` is not required. ## Testing the Custom Action After compiling and running the plugin project and invoking the action, the dialog will pop up: -![Action performed](img/action_performed.png){:width="800px"} +![Action performed](action_performed.png){width="800"} \ No newline at end of file diff --git a/tutorials/build_system/deployment.md b/topics/tutorials/build_system/deployment.md similarity index 87% rename from tutorials/build_system/deployment.md rename to topics/tutorials/build_system/deployment.md index 10ec56d1b..39d5c35f2 100644 --- a/tutorials/build_system/deployment.md +++ b/topics/tutorials/build_system/deployment.md @@ -1,22 +1,22 @@ ---- -title: Publishing Plugins with Gradle ---- +[//]: # (title: Publishing Plugins with Gradle) + Once you have configured Gradle support, you can automatically build and deploy your plugin to the [JetBrains Plugins Repository](https://plugins.jetbrains.com). To automatically deploy a plugin, you need to have _already published the plugin to the plugin repository at least once._ -Please see the guide page for manually [publishing a plugin](../../basics/getting_started/publishing_plugin.md) for the first time. +Please see the guide page for manually [publishing a plugin](publishing_plugin.md) for the first time. -> **TIP** Please see [Marketing](/appendix/resources/marketing.md) for remarks on how to prepare your plugin for optimal presentation. + > Please see [Marketing](marketing.md) for remarks on how to prepare your plugin for optimal presentation. + > + {type="tip"} -> **WARNING** When adding additional repositories to your Gradle build script, always use HTTPS protocol. - -* bullet list -{:toc} + > When adding additional repositories to your Gradle build script, always use HTTPS protocol. + > + {type="warning"} ## Building Distribution For manual distribution or local installation, invoke the `buildPlugin` Gradle task to create the plugin distribution. -The resulting JAR/ZIP is located in `build/distributions` and can then be [installed](https://www.jetbrains.com/help/idea/managing-plugins.html#installing-plugins-from-disk) either manually or uploaded to a [custom plugin repository](/basics/getting_started/update_plugins_format.md). +The resulting JAR/ZIP is located in `build/distributions` and can then be [installed](https://www.jetbrains.com/help/idea/managing-plugins.html#installing-plugins-from-disk) either manually or uploaded to a [custom plugin repository](update_plugins_format.md). ## Providing Your Hub Permanent Token to Gradle To deploy a plugin to the JetBrains Plugins Repository, you need to supply your [JetBrains Hub Permanent Token](https://plugins.jetbrains.com/docs/marketplace/plugin-upload.html). @@ -32,8 +32,10 @@ Start by defining an environment variable such as: export ORG_GRADLE_PROJECT_intellijPublishToken='YOUR_HUB_TOKEN_HERE' ``` -> **NOTE** On macOS systems, environment variables set in `.bash_profile` are only visible to processes you run from bash. + > On macOS systems, environment variables set in `.bash_profile` are only visible to processes you run from bash. Environment variables visible to all processes need to be defined in [Environment.plist](https://developer.apple.com/library/archive/qa/qa1067/_index.html). + > + {type="note"} Now provide the environment variable in the run configuration with which you run the `publishPlugin` task locally. To do so, create a Gradle run configuration (if not already done), choose your Gradle project, specify the `publishPlugin` task, and then add the environment variable. @@ -52,7 +54,6 @@ For example, you can provide the parameter `-Dorg.gradle.project.intellijPublish Note that also, in this case, you still need to put some default values in your Gradle properties. - ## Deploying a Plugin with Gradle The first step when deploying a plugin is to confirm that it works correctly. You may wish to verify this by [installing your plugin from disk](https://www.jetbrains.com/help/idea/managing-plugins.html) on a fresh instance of your target IDE(s). @@ -87,4 +88,4 @@ Popular channel names include: * `beta`: https://plugins.jetbrains.com/plugins/beta/list * `eap`: https://plugins.jetbrains.com/plugins/eap/list -More information about the available configuration options is in the [documentation of the IntelliJ Gradle plugin](https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md#publishing-dsl). +More information about the available configuration options is in the [documentation of the IntelliJ Gradle plugin](https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md#publishing-dsl). \ No newline at end of file diff --git a/tutorials/build_system/gradle_guide.md b/topics/tutorials/build_system/gradle_guide.md similarity index 81% rename from tutorials/build_system/gradle_guide.md rename to topics/tutorials/build_system/gradle_guide.md index b43e7fa87..3e8758a31 100644 --- a/tutorials/build_system/gradle_guide.md +++ b/topics/tutorials/build_system/gradle_guide.md @@ -1,18 +1,16 @@ ---- -title: Configuring Gradle Projects ---- +[//]: # (title: Configuring Gradle Projects) + -This page serves as a guide to the Gradle-based plugin configuration for _IntelliJ Platform_ projects. +This page serves as a guide to Gradle-based plugin configuration for _IntelliJ Platform_ projects. The IntelliJ IDEA Ultimate and Community editions bundle the _Gradle_ and _Plugin DevKit_ plugins to support Gradle-based development. -The [Getting Started with Gradle](prerequisites.md) page provides a tutorial for creating Gradle-based IntelliJ Platform plugins. -It may be useful to review the IntelliJ Platform page, particularly the description of versioning in the [Open Source](/intro/intellij_platform.md#open-source) section. +The [Getting Started with Gradle](gradle_prerequisites.md) page provides a tutorial for creating Gradle-based IntelliJ Platform plugins. +It may be useful to review the IntelliJ Platform page, particularly the description of versioning in the [Open Source](intellij_platform.md#open-source) section. -> **WARNING** When adding additional repositories to your Gradle build script, always use HTTPS protocol. - -* bullet list -{:toc} + > When adding additional repositories to your Gradle build script, always use HTTPS protocol. + > + {type="warning"} ## Overview of the Gradle Plugin The Gradle plugin is built from the open-source project [gradle-intellij-plugin](https://github.com/JetBrains/gradle-intellij-plugin). @@ -32,14 +30,15 @@ When getting started, there are several items to note on the README page: * Examples are always a helpful resource, and at the bottom of the page are links to [example](https://github.com/JetBrains/gradle-intellij-plugin#examples) open-source IntelliJ Platform plugin projects based on Gradle. * Almost every Gradle plugin attribute has a default value that will work to get started on a Gradle-based IntelliJ Platform plugin project. - ## Guide to Configuring Gradle Plugin Functionality This section presents a guided tour of Gradle plugin attributes to achieve the commonly desired functionality. ### Configuring the Gradle Plugin for Building IntelliJ Platform Plugin Projects By default, the Gradle plugin will build a plugin project against the IntelliJ Platform defined by the latest EAP snapshot of the IntelliJ IDEA Community Edition. -> **NOTE** Using EAP versions of the IntelliJ Platform requires adding the _Snapshots repository_ to the `build.gradle` file (see [IntelliJ Platform Artifacts Repositories](/reference_guide/intellij_artifacts.md)). + > Using EAP versions of the IntelliJ Platform requires adding the _Snapshots repository_ to the `build.gradle` file (see [IntelliJ Platform Artifacts Repositories](intellij_artifacts.md)). + > + {type="note"} If a matching version of the specified IntelliJ Platform is not available on the local machine, the Gradle plugin downloads the correct version and type. IntelliJ IDEA then indexes the build and any associated source code and JetBrains Java Runtime. @@ -47,7 +46,7 @@ IntelliJ IDEA then indexes the build and any associated source code and JetBrain #### IntelliJ Platform Configuration Explicitly setting the [Setup DSL](https://github.com/JetBrains/gradle-intellij-plugin#setup-dsl) attributes `intellij.version` and `intellij.type` tells the Gradle plugin to use that configuration of the IntelliJ Platform to create the plugin project. -All available platform versions can be browsed in the [IntelliJ Platform Artifacts Repositories](/reference_guide/intellij_artifacts.md). +All available platform versions can be browsed in the [IntelliJ Platform Artifacts Repositories](intellij_artifacts.md). If the chosen platform version is not available in the repositories, or a local installation of the target IDE is the desired type and version of the IntelliJ Platform, use `intellij.localPath` to point to that installation. If the `intellij.localPath` attribute is set, do not set the `intellij.version` and `intellij.type` attributes as this could result in undefined behavior. @@ -59,28 +58,28 @@ The Gradle plugin will fetch any plugins in the list defined by `intellij.plugin See the Gradle plugin [README](https://github.com/JetBrains/gradle-intellij-plugin#setup-dsl) for information about specifying the plugin and version. Note that this attribute describes a dependency so that the Gradle plugin can fetch the required artifacts. -The runtime dependency must be added in the [Plugin Configuration](/basics/plugin_structure/plugin_configuration_file.md) (`plugin.xml`) file as described in [Plugin Dependencies](/basics/plugin_structure/plugin_dependencies.md#3-dependency-declaration-in-pluginxml). +The runtime dependency must be added in the [Plugin Configuration](plugin_configuration_file.md) (`plugin.xml`) file as described in [Plugin Dependencies](plugin_dependencies.md#dependency-declaration-in-pluginxml). ### Configuring the Gradle Plugin for Running IntelliJ Platform Plugin Projects -By default, the Gradle plugin will use the same version of the IntelliJ Platform for the IDE Development Instance, as was used for building the plugin. -Using the corresponding JetBrains Runtime is also the default, so for this use case, no further configuration is required. +By default, the Gradle plugin will use the same version of the IntelliJ Platform for the IDE Development Instance as was used for building the plugin. +Using the corresponding JetBrains Runtime is also the default, so for this use case no further configuration is required. #### Running Against Alternate Versions and Types of IntelliJ Platform-Based IDEs The IntelliJ Platform IDE used for the Development Instance can be different from that used to build the plugin project. Setting the [Running DSL](https://github.com/JetBrains/gradle-intellij-plugin#running-dsl) attribute `runIde.ideDirectory` will define an IDE to be used for the Development Instance. -This attribute is commonly used when running or debugging a plugin in an [alternate IntelliJ Platform-based IDE](/intro/intellij_platform.md#ides-based-on-the-intellij-platform). +This attribute is commonly used when running or debugging a plugin in an [alternate IntelliJ Platform-based IDE](intellij_platform.md#ides-based-on-the-intellij-platform). #### Running Against Alternate Versions of the JetBrains Runtime -Every version of the IntelliJ Platform has a corresponding version of the [JetBrains Runtime](/basics/ide_development_instance.md#using-a-jetbrains-runtime-for-the-development-instance). +Every version of the IntelliJ Platform has a corresponding version of the [JetBrains Runtime](ide_development_instance.md#using-a-jetbrains-runtime-for-the-development-instance). A different version of the runtime can be used by specifying the `runIde.jbrVersion` attribute, describing a version of the JetBrains Runtime that should be used by the IDE Development Instance. The Gradle plugin will fetch the specified JetBrains Runtime as needed. ### Managing Directories Used by the Gradle Plugin There are several attributes to control where the Gradle plugin places directories for downloads and use by the IDE Development Instance. -The location of the [sandbox home](/basics/ide_development_instance.md#sandbox-home-location-for-gradle-based-plugin-projects) directory and its subdirectories can be controlled with Gradle plugin attributes. +The location of the [sandbox home](ide_development_instance.md#sandbox-home-location-for-gradle-based-plugin-projects) directory and its subdirectories can be controlled with Gradle plugin attributes. The `intellij.sandboxDirectory` attribute is used to set the path for the sandbox directory to be used while running the plugin in an IDE Development Instance. -Locations of the sandbox [subdirectories](/basics/ide_development_instance.md#development-instance-settings-caches-logs-and-plugins) can be controlled using the `runIde.configDirectory`, `runIde.pluginsDirectory`, and `runIde.systemDirectory` attributes. +Locations of the sandbox [subdirectories](ide_development_instance.md#development-instance-settings-caches-logs-and-plugins) can be controlled using the `runIde.configDirectory`, `runIde.pluginsDirectory`, and `runIde.systemDirectory` attributes. If the `intellij.sandboxDirectory` path is explicitly set, the subdirectory attributes default to the new sandbox directory. The storage location of downloaded IDE versions and components defaults to the Gradle cache directory. @@ -88,11 +87,11 @@ However, it can be controlled by setting the `intellij.ideaDependencyCachePath` ### Controlling Downloads by the Gradle Plugin As mentioned in the section about [configuring the IntelliJ Platform](#configuring-the-gradle-plugin-for-building-intellij-platform-plugin-projects) used for building plugin projects, the Gradle plugin will fetch the version of the IntelliJ Platform specified by the default or by the `intellij` attributes. -Standardizing the versions of the Gradle plugin and the Gradle system across projects will minimize the time spent downloading versions. +Standardizing the versions of the Gradle plugin and Gradle system across projects will minimize the time spent downloading versions. -There are controls for managing the `gradle-intellij-plugin` version, and the version of the Gradle itself. +There are controls for managing the `gradle-intellij-plugin` version, and the version of Gradle itself. The plugin version is defined in the `plugins {}` section of a project's `build.gradle` file. -The version of the Gradle is defined in `/gradle/wrapper/gradle-wrapper.properties`. +The version of Gradle is defined in `/gradle/wrapper/gradle-wrapper.properties`. ### Patching the Plugin Configuration File A plugin project's `plugin.xml` file has element values that are "patched" at build time from the attributes of the `patchPluginXml` task ([Patching DSL](https://github.com/JetBrains/gradle-intellij-plugin#patching-dsl)). @@ -107,14 +106,16 @@ As many as possible of the attributes in the Patching DSL will be substituted in * Either set `intellij.updateSinceUntilBuild = false`, which will disable substituting both `since-build` and `until-build` attributes, * Or, for independent control, set `patchPluginXml.sinceBuild(null)` and `patchPluginXml.untilBuild(null)` depending on whether the intention is to disable one or both substitutions. -A best practice to avoid confusion is to replace the elements in `plugin.xml` the Gradle plugin will patch that with a comment. -That way, the values for these parameters do not appear in two places in the source code. +A best practice to avoid confusion is to replace the elements in `plugin.xml` that will be patched by the Gradle plugin with a comment. +That way the values for these parameters do not appear in two places in the source code. The Gradle plugin will add the necessary elements as part of the patching process. For those `patchPluginXml` attributes that contain descriptions such as `changeNotes` and `pluginDescription`, a `CDATA` block is not necessary when using HTML elements. -> **TIP** To maintain and generate an up-to-date changelog, try using [Gradle Changelog Plugin](https://github.com/JetBrains/gradle-changelog-plugin). + > To maintain and generate an up-to-date changelog, try using [Gradle Changelog Plugin](https://github.com/JetBrains/gradle-changelog-plugin). + > + {type="tip"} -As discussed in [Components of a Wizard-Generated Gradle IntelliJ Platform Plugin](prerequisites.md#components-of-a-wizard-generated-gradle-intellij-platform-plugin), the Gradle properties `project.version`, `project.group`, and `rootProject.name` are all generated based on the input to the Wizard. +As discussed in [Components of a Wizard-Generated Gradle IntelliJ Platform Plugin](gradle_prerequisites.md#components-of-a-wizard-generated-gradle-intellij-platform-plugin), the Gradle properties `project.version`, `project.group`, and `rootProject.name` are all generated based on the input to the Wizard. However, the `gradle-intellij-plugin` does not combine and substitute those Gradle properties for the default `` and `` elements in the `plugin.xml` file. The best practice is to keep `project.version` current. @@ -133,7 +134,6 @@ Please check the [Plugin Verifier DSL](https://github.com/JetBrains/gradle-intel Please review the [Publishing Plugins with Gradle](deployment.md) page before using the [Publishing DSL](https://github.com/JetBrains/gradle-intellij-plugin#publishing-dsl) attributes. That documentation explains different ways to use Gradle for plugin uploads without exposing account credentials. - ## Common Gradle Plugin Configurations for Development Different combinations of Gradle plugin attributes are needed to create the desired build or IDE Development Instance environment. This section reviews some of the more common configurations. @@ -141,7 +141,7 @@ This section reviews some of the more common configurations. ### Plugins Targeting IntelliJ IDEA IntelliJ Platform plugins targeting IntelliJ IDEA have the most straightforward Gradle plugin configuration. * Determine the version of [IntelliJ IDEA to use for building the plugin project](#configuring-the-gradle-plugin-for-building-intellij-platform-plugin-projects); this is the desired version of the IntelliJ Platform. - This can be EAP (default) or determined from the [build number ranges](/basics/getting_started/build_number_ranges.md). + This can be EAP (default) or determined from the [build number ranges](build_number_ranges.md). * If a production version of IntelliJ IDEA is the desired target, set the `intellij` [version attributes](#intellij-platform-configuration) accordingly. * Set the necessary [plugin dependencies](#plugin-dependencies), if any. * If the plugin project should be run or debugged in an IDE Development Instance based on the same IntelliJ IDEA version, no further attributes need to be set for the IDE Development Instance. @@ -152,4 +152,4 @@ IntelliJ Platform plugins targeting IntelliJ IDEA have the most straightforward ### Plugins Targeting Alternate IntelliJ Platform-Based IDEs Gradle also supports developing plugins to run in IDEs that are based on the IntelliJ Platform. -For more information, see the [Developing for Multiple Products](/products/dev_alternate_products.md) page of this guide. +For more information, see the [Developing for Multiple Products](dev_alternate_products.md) page of this guide. \ No newline at end of file diff --git a/tutorials/build_system/prerequisites.md b/topics/tutorials/build_system/gradle_prerequisites.md similarity index 83% rename from tutorials/build_system/prerequisites.md rename to topics/tutorials/build_system/gradle_prerequisites.md index 515c2eb8e..b8711dca0 100644 --- a/tutorials/build_system/prerequisites.md +++ b/topics/tutorials/build_system/gradle_prerequisites.md @@ -1,6 +1,5 @@ ---- -title: Getting Started with Gradle ---- +[//]: # (title: Getting Started with Gradle) + Gradle is the preferred solution for creating IntelliJ Platform plugins. @@ -8,12 +7,13 @@ The IntelliJ IDEA Ultimate and Community editions bundle the necessary plugins t These IntelliJ IDEA plugins are _Gradle_ and _Plugin DevKit_, which are enabled by default. To verify these plugins are installed and enabled, see the help section about [Managing Plugins](https://www.jetbrains.com/help/idea/managing-plugins.html). -> **TIP** [IntelliJ Platform Plugin Template](https://github.com/JetBrains/intellij-platform-plugin-template) makes it easier to create and maintain your IDE plugins, having the Gradle plugin already integrated and CI covered with GitHub Actions. + > [IntelliJ Platform Plugin Template](https://github.com/JetBrains/intellij-platform-plugin-template) makes it easier to create and maintain your IDE plugins, having the Gradle plugin already integrated and CI covered with GitHub Actions. + > + {type="tip"} -> **WARNING** When adding additional repositories to your Gradle build script, always use HTTPS protocol. - -* bullet list -{:toc} + > When adding additional repositories to your Gradle build script, always use HTTPS protocol. + > + {type="warning"} ## Creating a Gradle-Based IntelliJ Platform Plugin with New Project Wizard Creating new Gradle-based IntelliJ Platform plugin projects is performed using the [New Project Wizard](https://www.jetbrains.com/help/idea/gradle.html#project_create_gradle). @@ -22,7 +22,9 @@ The Wizard creates all the necessary project files based on a few template input Before creating a new Gradle project, familiarize yourself with the help topic [Creating a new Gradle project](https://www.jetbrains.com/help/idea/getting-started-with-gradle.html#create_gradle_project), which is a tutorial for creating general Gradle projects in IntelliJ IDEA. This page emphasizes the steps in the process of creating IntelliJ Platform plugin projects that are Gradle-based. -> **WARNING** Please note that Gradle 6.1 has a [known bug](https://github.com/gradle/gradle/issues/11966) that prevents using it for developing plugins, please upgrade to 6.1.1 or later. + > Please note that Gradle 6.1 has a [known bug](https://github.com/gradle/gradle/issues/11966) that prevents using it for developing plugins, please upgrade to 6.1.1 or later. + > + {type="warning"} Launch the [New Project Wizard](https://www.jetbrains.com/help/idea/gradle.html#project_create_gradle). It guides you through the Gradle project creation process with two screens. @@ -33,7 +35,9 @@ On the first screen, the type of project is configured: * Specify the _Project SDK_ based on the **Java 8** JDK. This SDK will be the default JRE used to run Gradle, and the JDK version used to compile the plugin Java sources. -> **NOTE** When targeting 2020.3 and later only, using Java 11 is now required, please see [blog post](https://blog.jetbrains.com/platform/2020/09/intellij-project-migrates-to-java-11/) + > When targeting 2020.3 and later only, using Java 11 is now required, please see [blog post](https://blog.jetbrains.com/platform/2020/09/intellij-project-migrates-to-java-11/) + > + {type="note"} * In the _Additional Libraries and Frameworks_ panel, select _Java_ and _IntelliJ Platform Plugin_. These settings will be used for the remainder of this tutorial. @@ -41,12 +45,12 @@ On the first screen, the type of project is configured: Optionally: * To include support for the Kotlin language in the plugin, check the _Kotlin/JVM_ box (circled in green below). This option can be selected with or without the _Java_ language. - See [Kotlin for Plugin Developers](/tutorials/kotlin.md) for more information. + See [Kotlin for Plugin Developers](kotlin.md) for more information. * To create the `build.gradle` file as a Kotlin build script (`build.gradle.kts`) rather than Groovy, check the _Kotlin DSL build script_ box (circled in magenta below). Then click _Next_: -![Select Gradle in the Project Creation Wizard](img/step1_new_gradle_project.png){:width="800px"} +![Select Gradle in the Project Creation Wizard](step1_new_gradle_project.png){width="800"} ### Project Naming/Artifact Coordinates Screen Expand the _Artifact Coordinates_ section and specify a [GroupId, ArtifactId, and Version](https://www.jetbrains.com/help/idea/gradle.html#project_create_gradle) using [Maven naming](https://maven.apache.org/guides/mini/guide-naming-conventions.html) conventions. @@ -62,7 +66,6 @@ The _Name_ field is synced automatically with the specified _ArtifactId_. Specify the path for the new project in _Location_ and click _Finish_ to continue and generate the project. - ### Components of a Wizard-Generated Gradle IntelliJ Platform Plugin For the [example](#creating-a-gradle-based-intellij-platform-plugin-with-new-project-wizard) `my_gradle_plugin`, the New Project Wizard creates the following directory content: @@ -88,11 +91,10 @@ my_gradle_plugin ``` * The default IntelliJ Platform `build.gradle` file (see next paragraph). -* The Gradle Wrapper files, and in particular the `gradle-wrapper.properties` file, which specifies the version of the Gradle to be used to build the plugin. - If needed, the IntelliJ IDEA Gradle plugin downloads the version of the Gradle specified in this file. +* The Gradle Wrapper files, and in particular the `gradle-wrapper.properties` file, which specifies the version of Gradle to be used to build the plugin. + If needed, the IntelliJ IDEA Gradle plugin downloads the version of Gradle specified in this file. * The `settings.gradle` file, containing a definition of the `rootProject.name`. -* The `META-INF` directory under the default `main` [SourceSet](https://docs.gradle.org/current/userguide/java_plugin.html#sec:java_project_layout) contains the plugin [configuration file](/basics/plugin_structure/plugin_configuration_file.md). - +* The `META-INF` directory under the default `main` [SourceSet](https://docs.gradle.org/current/userguide/java_plugin.html#sec:java_project_layout) contains the plugin [configuration file](plugin_configuration_file.md). The generated `my_gradle_plugin` project `build.gradle` file: @@ -119,7 +121,7 @@ The generated `my_gradle_plugin` project `build.gradle` file: } patchPluginXml { changeNotes """ - Add change notes here.
+ Add change notes here.
most HTML tags may be used""" } ``` @@ -135,10 +137,8 @@ The generated `my_gradle_plugin` project `build.gradle` file: It defaults to the version of IntelliJ IDEA that was used to run the New Project Wizard. * The value of the Patching DSL attribute `patchPluginXml.changeNotes` is set to a place holder text. - - #### Plugin Gradle Properties and Plugin Configuration File Elements -The Gradle properties `rootProject.name` and `project.group` will not, in general, match the respective [plugin configuration file](/basics/plugin_structure/plugin_configuration_file.md) `plugin.xml` elements `` and ``. +The Gradle properties `rootProject.name` and `project.group` will not, in general, match the respective [plugin configuration file](plugin_configuration_file.md) `plugin.xml` elements `` and ``. There is no IntelliJ Platform-related reason they should as they serve different functions. The `` element (used as the plugin's display name) is often the same as `rootProject.name`, but it can be more explanatory. @@ -147,7 +147,7 @@ The `` value must be a unique identifier over all plugins, typically a conca Please note that it is impossible to change the `` of a published plugin without losing automatic updates for existing installations. ## Adding Gradle Support to an Existing DevKit-Based IntelliJ Platform Plugin -Converting a [DevKit-based](/basics/getting_started/using_dev_kit.md) plugin project to a Gradle-based plugin project can be done using the New Project Wizard to create a Gradle-based project around the existing DevKit-based project: +Converting a [DevKit-based](using_dev_kit.md) plugin project to a Gradle-based plugin project can be done using the New Project Wizard to create a Gradle-based project around the existing DevKit-based project: * Ensure the directory containing the DevKit-based IntelliJ Platform plugin project can be fully recovered if necessary. * Delete all the artifacts of the DevKit-based project: * `.idea` directory @@ -165,22 +165,21 @@ Converting a [DevKit-based](/basics/getting_started/using_dev_kit.md) plugin pro * Click _Finish_ to create the new Gradle-based plugin. * [Add more modules](https://www.jetbrains.com/help/idea/gradle.html#gradle_add_module) using Gradle [_Source Sets_](https://www.jetbrains.com/help/idea/gradle.html#gradle_source_sets) as needed. - ## Running a Simple Gradle-Based IntelliJ Platform Plugin Gradle projects are run from the IDE's Gradle Tool window. ### Adding Code to the Project Before running [`my_gradle_project`](#components-of-a-wizard-generated-gradle-intellij-platform-plugin), some code can be added to provide simple functionality. -See the [Creating Actions](/tutorials/action_system/working_with_custom_actions.md) tutorial for step-by-step instructions for adding a menu action. +See the [Creating Actions](working_with_custom_actions.md) tutorial for step-by-step instructions for adding a menu action. ### Executing the Plugin Open the Gradle tool window and search for the `runIde` task: * If it’s not in the list, hit the [Refresh](https://www.jetbrains.com/help/idea/jetgradle-tool-window.html#1eeec055) button at the top of the Gradle window. * Or [Create a new Gradle Run Configuration](https://www.jetbrains.com/help/idea/create-run-debug-configuration-gradle-tasks.html). -![Gradle Tool Window](img/gradle_tasks_in_tool_window.png){:width="398px"} +![Gradle Tool Window](gradle_tasks_in_tool_window.png){width="398"} Double-click on the _runIde_ task to execute it. See the IntelliJ IDEA help for more information about [Working with Gradle tasks](https://www.jetbrains.com/help/idea/gradle.html#96bba6c3). -Finally, when `my_gradle_plugin` launches in the IDE development instance, there should be a new menu under the **Tools** menu. +Finally, when `my_gradle_plugin` launches in the IDE development instance, there should be a new menu under the **Tools** menu. \ No newline at end of file diff --git a/tutorials/code_inspections.md b/topics/tutorials/code_inspections.md similarity index 97% rename from tutorials/code_inspections.md rename to topics/tutorials/code_inspections.md index dffc89de6..f2ba80ca4 100644 --- a/tutorials/code_inspections.md +++ b/topics/tutorials/code_inspections.md @@ -1,6 +1,5 @@ ---- -title: Code Inspections ---- +[//]: # (title: Code Inspections) + The IntelliJ Platform provides tools designed for static code analysis called _code inspections_, which help the user maintain and clean up code without actually executing it. @@ -125,10 +124,12 @@ Implicit in using [`LocalInspectionTool`](upsource:///platform/analysis-api/src/ If a short name is not provided by the plugin, the IntelliJ Platform computes one by removing `Inspection` suffix from the implementation class name. ### Inspection Unit Test -> **NOTE** Please note that running the test requires setting system property `idea.home.path` in `test {}` block of `build.gradle` + > Please note that running the test requires setting system property `idea.home.path` in `test {}` block of `build.gradle` + > + {type="note"} The `comparing_references_inspection` code sample provides a unit test for the inspection. -See the [Testing Plugins](/basics/testing_plugins/testing_plugins.md) section for general information about plugin testing. +See the [Testing Plugins](testing_plugins.md) section for general information about plugin testing. The `comparing_references_inspection` test is based on the [`UsefulTestCase`](upsource:///platform/testFramework/src/com/intellij/testFramework/UsefulTestCase.java) class, part of the JUnit framework APIs. This class handles much of the underlying boilerplate for tests. @@ -140,7 +141,6 @@ In the case of `comparing_references_inspection` the test files are `Eq.java` / The `comparing_references_inspection` tests run the inspection on the `*.java` files, implement the quick fix, and compare the results with the respective `*.after.java` files. - ## Running the Comparing References Inspection Code Sample The [comparing_references_inspection](https://github.com/JetBrains/intellij-sdk-code-samples/tree/master/comparing_references_inspection) code sample adds a new inspection to the **Java | Probable Bugs** group in the [Inspections list](https://www.jetbrains.com/help/idea/inspections-settings.html). The inspection reports when the `==` or `!=` operator is used between Java expressions of reference types. @@ -159,7 +159,7 @@ You can specify the Java classes to participate in the code inspection and the s On the main menu, open the **Preferences | Editor | Inspections** dialog. In the list of the IntelliJ IDEA _Java_ inspections, expand the _Probable bugs_ node, and then click _SDK: '==' or '!=' instead of 'equals()'_. -![](img/comparingReferences_options.png) +![](comparingReferences_options.png) Under **Options**, you can specify the following plugin settings: * From the **Severity** list, select the severity level of probable bugs the plugin finds such as Warning, Info, etc. @@ -171,7 +171,7 @@ Under **Options**, you can specify the following plugin settings: The plugin inspects your code opened in the IntelliJ IDEA editor or the code you are typing. The plugin highlights the code fragments where two variables of the reference type are separated by `==` or `!=` and proposes to replace this code fragment with `.equals()`: -![](img/comparingReferences.png) +![](comparingReferences.png) In this example, the `str1` and `str2` are variables of the String type. Clicking _SDK: Use equals()_ replaces: @@ -184,4 +184,4 @@ with the code: ```java return (str1.equals(str2)); -``` +``` \ No newline at end of file diff --git a/tutorials/code_intentions.md b/topics/tutorials/code_intentions.md similarity index 91% rename from tutorials/code_intentions.md rename to topics/tutorials/code_intentions.md index 173b1cc95..03fb2f21c 100644 --- a/tutorials/code_intentions.md +++ b/topics/tutorials/code_intentions.md @@ -1,6 +1,5 @@ ---- -title: Code Intentions ---- +[//]: # (title: Code Intentions) + This topic describes the [conditional_operator_intention](https://github.com/JetBrains/intellij-sdk-code-samples/tree/master/conditional_operator_intention), a sample plugin that adds a new [intention action](https://www.jetbrains.com/help/idea/intention-actions.html) to the IntelliJ Platform Intentions list. @@ -25,7 +24,7 @@ You can view a list of all available intention actions using the [Intention List The [conditional_operator_intention](https://github.com/JetBrains/intellij-sdk-code-samples/tree/master/conditional_operator_intention) sample plugin illustrates the use of the following techniques: -- How to analyze a [PSI tree](/basics/architectural_overview/psi_files.md). +- How to analyze a [PSI tree](psi_files.md). - How to find a Java token of interest in the PSI tree. - How to invoke a quick fix action for a token element under cursor using the [`PsiElementBaseIntentionAction`](upsource:///platform/lang-api/src/com/intellij/codeInsight/intention/PsiElementBaseIntentionAction.java) class. - How to create a JUnit test for this plugin using the [`IdeaTestFixtureFactory`](upsource:///platform/testFramework/src/com/intellij/testFramework/fixtures/IdeaTestFixtureFactory.java) class. @@ -35,7 +34,7 @@ The [conditional_operator_intention](https://github.com/JetBrains/intellij-sdk-c The **ConditionalOperatorConverter** sample plugin is available in the `<%IntelliJ SDK Docs project%>/code_samples/conditional_operator_intention` directory. When launched, this plugin adds the **Convert ternary operator if statement** item to the **Conditional Operator** node in the IDEA Intentions list: -![](img/IntentionsList.png) +![](IntentionsList.png) #### Running the Plugin @@ -50,7 +49,7 @@ When launched, this plugin adds the **Convert ternary operator if statement** it The plugin analyzes symbols under the cursor in your code opened in the IDEA editor. If the cursor is positioned on the "?" conditional operator, **IntelliJ IDEA** proposes to replace this conditional (ternary) operator with the "if-then-else" statement: -![](img/TernaryOperator.png) +![](TernaryOperator.png) In this example, the code: @@ -69,9 +68,11 @@ if ((n>=0)) { ``` ##### Testing the Plugin -> **NOTE** Please note that running the test requires setting system property `idea.home.path` in `test {}` block of `build.gradle` + > Please note that running the test requires setting system property `idea.home.path` in `test {}` block of `build.gradle` + > + {type="note"} The sample plugin contains the `ConditionalOperatorConverterTest` Java class and the test data in the `test/testData/` directory. To perform the plugin test, run the `ConditionalOperatorConverterTest.testIntention()` method. -For detailed information about testing and all related procedures, refer to [Testing](https://www.jetbrains.com/help/idea/performing-tests.html) in the **IntelliJ IDEA** Web Help. +For detailed information about testing and all related procedures, refer to [Testing](https://www.jetbrains.com/help/idea/performing-tests.html) in the **IntelliJ IDEA** Web Help. \ No newline at end of file diff --git a/tutorials/custom_language_support/annotator.md b/topics/tutorials/custom_language_support/annotator.md similarity index 63% rename from tutorials/custom_language_support/annotator.md rename to topics/tutorials/custom_language_support/annotator.md index 3f01f84a7..7f7f49bb8 100644 --- a/tutorials/custom_language_support/annotator.md +++ b/topics/tutorials/custom_language_support/annotator.md @@ -1,19 +1,15 @@ ---- -title: 7. Annotator ---- +[//]: # (title: 7. Annotator) + An `Annotator` helps highlight and annotate any code based on specific rules. This section adds annotation functionality to support the Simple Language in the context of Java code. -**Reference**: [Annotator](/reference_guide/custom_language_support/syntax_highlighting_and_error_highlighting.md#annotator) - -* bullet list -{:toc} +**Reference**: [Annotator](syntax_highlighting_and_error_highlighting.md#annotator) ## Required Project Configuration Changes Classes defined in this step of the tutorial depend on `com.intellij.psi.PsiLiteralExpression` at runtime. -Using `PsiLiteralExpression` [introduces a dependency](/basics/getting_started/plugin_compatibility.md#modules-specific-to-functionality) on `com.intellij.modules.java`. +Using `PsiLiteralExpression` [introduces a dependency](plugin_compatibility.md#modules-specific-to-functionality) on `com.intellij.modules.java`. Beginning in version 2019.2 of the IntelliJ Platform these dependencies are declared in `plugin.xml`: ```xml @@ -28,21 +24,25 @@ intellij { } ``` -## 7.1. Define an Annotator +## Define an Annotator The `SimpleAnnotator` subclasses [`Annotator`](upsource:///platform/analysis-api/src/com/intellij/lang/annotation/Annotator.java). Consider a literal string that starts with "simple:" as a prefix of a Simple Language key. It isn't part of the Simple Language, but it is a useful convention for detecting Simple Language keys embedded as string literals in other languages, like Java. Annotate the `simple:key` literal expression, and differentiate between a well-formed vs. an unresolved property. -> **NOTE** The use of new `AnnotationHolder` syntax starting 2020.2, which uses the builder format. + > The use of new `AnnotationHolder` syntax starting 2020.2, which uses the builder format. + > + {type="note"} ```java -{% include /code_samples/simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleAnnotator.java %} ``` +{src="simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleAnnotator.java"} -> **TIP** If the above code is copied at this stage of the tutorial, then remove the line below the comment "** Tutorial step 18.3 …" The quick fix class in that line is not defined until later in the tutorial. + > If the above code is copied at this stage of the tutorial, then remove the line below the comment "** Tutorial step 18.3 …" The quick fix class in that line is not defined until later in the tutorial. + > + {type="tip"} -## 7.2. Register the Annotator +## Register the Annotator Using the `com.intellij.annotator` extension point in the plugin configuration file, register the Simple Language annotator class with the IntelliJ Platform: ```xml @@ -51,7 +51,7 @@ Using the `com.intellij.annotator` extension point in the plugin configuration f ``` -## 7.3. Run the Project +## Run the Project As a test, define the following Java file containing a Simple Language `prefix:value` pair: ```java @@ -64,10 +64,10 @@ public class Test { Open this Java file in an IDE Development Instance running the `simple_language_plugin` to check if the IDE resolves a property: -![Annotator](img/annotator.png){:width="800px"} +![Annotator](annotator.png){width="800"} If the property is an undefined name, the annotator flags the code with an error. -![Unresolved property](img/unresolved_property.png){:width="800px"} +![Unresolved property](unresolved_property.png){width="800"} -Try changing the Simple Language [color settings](/tutorials/custom_language_support/syntax_highlighter_and_color_settings_page.md#run-the-project-1) to differentiate the annotation from the default language color settings. +Try changing the Simple Language [color settings](syntax_highlighter_and_color_settings_page.md#run-the-project) to differentiate the annotation from the default language color settings. \ No newline at end of file diff --git a/tutorials/custom_language_support/code_style_settings.md b/topics/tutorials/custom_language_support/code_style_settings.md similarity index 72% rename from tutorials/custom_language_support/code_style_settings.md rename to topics/tutorials/custom_language_support/code_style_settings.md index 658ce994b..38edad1a6 100644 --- a/tutorials/custom_language_support/code_style_settings.md +++ b/topics/tutorials/custom_language_support/code_style_settings.md @@ -1,33 +1,29 @@ ---- -title: 16. Code Style Settings ---- +[//]: # (title: 16. Code Style Settings) + Code style settings enable defining formatting options. A code style settings provider creates an instance of the settings and also creates an options page in settings/preferences. This example creates a settings/preferences page that uses the default language code style settings, customized by a language code style settings provider. -**Reference**: [Code Style Settings](/reference_guide/custom_language_support/code_formatting.md#code-style-settings) +**Reference**: [Code Style Settings](code_formatting.md#code-style-settings) -* bullet list -{:toc} - -## 16.1. Define Code Style Settings +## Define Code Style Settings Define a code style settings for Simple Language by subclassing [`CustomCodeStyleSettings`](upsource:///platform/code-style-api/src/com/intellij/psi/codeStyle/CustomCodeStyleSettings.java). ```java -{% include /code_samples/simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleCodeStyleSettings.java %} ``` +{src="simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleCodeStyleSettings.java"} -## 16.2. Define Code Style Settings Provider +## Define Code Style Settings Provider The code style settings provider gives the IntelliJ Platform a standard way to instantiate `CustomCodeStyleSettings` for the Simple Language. Define a code style settings provider for Simple Language by subclassing [`CodeStyleSettingsProvider`](upsource:///platform/lang-api/src/com/intellij/psi/codeStyle/CodeStyleSettingsProvider.java). ```java -{% include /code_samples/simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleCodeStyleSettingsProvider.java %} ``` +{src="simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleCodeStyleSettingsProvider.java"} -## 16.3. Register the Code Style Settings Provider +## Register the Code Style Settings Provider The `SimpleCodeStyleSettingsProvider` implementation is registered with the IntelliJ Platform in the plugin configuration file using the `com.intellij.codeStyleSettingsProvider` extension point. ```xml @@ -36,14 +32,14 @@ The `SimpleCodeStyleSettingsProvider` implementation is registered with the Inte ``` -## 16.4. Define the Language Code Style Settings Provider +## Define the Language Code Style Settings Provider Define a code style settings provider for Simple Language by subclassing [`LanguageCodeStyleSettingsProvider`](upsource:///platform/lang-api/src/com/intellij/psi/codeStyle/LanguageCodeStyleSettingsProvider.java), which provides common code style settings for a specific language. ```java -{% include /code_samples/simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleLanguageCodeStyleSettingsProvider.java %} ``` +{src="simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleLanguageCodeStyleSettingsProvider.java"} -## 16.5. Register the Language Code Style Settings Provider +## Register the Language Code Style Settings Provider The `SimpleLanguageCodeStyleSettingsProvider` implementation is registered with the IntelliJ Platform in the plugin configuration file using the `com.intellij.langCodeStyleSettingsProvider` extension point. ```xml @@ -53,7 +49,7 @@ The `SimpleLanguageCodeStyleSettingsProvider` implementation is registered with ``` -## 16.6. Run the Project +## Run the Project In the IDE Development Instance, open the Simple Language code formatting page: **Preferences/Settings \| Editor \| Code Style \| Simple**. -![Code Style Settings](img/code_style_settings.png) +![Code Style Settings](code_style_settings.png) \ No newline at end of file diff --git a/tutorials/custom_language_support/commenter.md b/topics/tutorials/custom_language_support/commenter.md similarity index 71% rename from tutorials/custom_language_support/commenter.md rename to topics/tutorials/custom_language_support/commenter.md index a88a12e50..ae61c51a6 100644 --- a/tutorials/custom_language_support/commenter.md +++ b/topics/tutorials/custom_language_support/commenter.md @@ -1,22 +1,18 @@ ---- -title: 17. Commenter ---- +[//]: # (title: 17. Commenter) + A commenter enables the user to comment-out a line of code at the cursor or selected code automatically. The [`Commenter`](upsource:///platform/core-api/src/com/intellij/lang/Commenter.java) defines support for **Code \| Comment with Line Comment** and **Code \| Comment with Block Comment** actions. -* bullet list -{:toc} - -## 17.1. Define a Commenter +## Define a Commenter The commenter for Simple Language defines the line comment prefix as `#`. ```java -{% include /code_samples/simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleCommenter.java %} ``` +{src="simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleCommenter.java"} -## 17.2. Register the Commenter +## Register the Commenter The `SimpleCommenter` implementation is registered in the plugin configuration file using the `com.intellij.lang.commenter` extension point. ```xml @@ -25,11 +21,11 @@ The `SimpleCommenter` implementation is registered in the plugin configuration f ``` -## 17.3. Run the Project -Open the example Simple Language [properties file ](/tutorials/custom_language_support/lexer_and_parser_definition.md#47-run-the-project) in the IDE Development Instance. +## Run the Project +Open the example Simple Language [properties file ](lexer_and_parser_definition.md#run-the-project) in the IDE Development Instance. Place the cursor at the `website` line. Select **Code \| Comment with Line Comment**. The line is converted to a comment. Select **Code \| Comment with Line Comment** again, and the comment is converted back to active code. -![Commenter](img/commenter.png) +![Commenter](commenter.png) \ No newline at end of file diff --git a/tutorials/custom_language_support/completion_contributor.md b/topics/tutorials/custom_language_support/completion_contributor.md similarity index 72% rename from tutorials/custom_language_support/completion_contributor.md rename to topics/tutorials/custom_language_support/completion_contributor.md index 49831cd77..38805360a 100644 --- a/tutorials/custom_language_support/completion_contributor.md +++ b/topics/tutorials/custom_language_support/completion_contributor.md @@ -1,25 +1,21 @@ ---- -title: 9. Completion Contributor ---- +[//]: # (title: 9. Completion Contributor) + Custom languages provide code completion using one of two approaches: Contributor and Reference-based (see [10. Reference Contributor](reference_contributor.md)) completion. -**Reference**: [Code Completion](/reference_guide/custom_language_support/code_completion.md) +**Reference**: [Code Completion](code_completion.md) -* bullet list -{:toc} - -## 9.1. Define a Completion Contributor +## Define a Completion Contributor For this tutorial, the `simple_language_plugin` provides custom completion for values in Simple Language property files. Create a completion contributor by subclassing [`CompletionContributor`](upsource:///platform/analysis-api/src/com/intellij/codeInsight/completion/CompletionContributor.java). This rudimentary completion contributor always adds "Hello" to the results set, regardless of context: ```java -{% include /code_samples/simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleCompletionContributor.java %} ``` +{src="simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleCompletionContributor.java"} -## 9.2. Register the Completion Contributor +## Register the Completion Contributor The `SimpleCompletionContributor` implementation is registered in the plugin configuration file with the IntelliJ Platform using the `com.intellij.completion.contributor` extension point. ```xml @@ -29,9 +25,9 @@ The `SimpleCompletionContributor` implementation is registered in the plugin con ``` -## 9.3. Run the Project -Run the `simple_language_plugin` in a Development Instance and open the [`test.simple`](/tutorials/custom_language_support/lexer_and_parser_definition.md#run-the-project) file. +## Run the Project +Run the `simple_language_plugin` in a Development Instance and open the [`test.simple`](lexer_and_parser_definition.md#run-the-project) file. Erase the property "English" and invoke [Basic Code Completion](https://www.jetbrains.com/help/idea/auto-completing-code.html#invoke-basic-completion). The choice "Hello" is shown: -![Completion](img/completion.png) +![Completion](completion.png) \ No newline at end of file diff --git a/tutorials/custom_language_support/find_usages_provider.md b/topics/tutorials/custom_language_support/find_usages_provider.md similarity index 76% rename from tutorials/custom_language_support/find_usages_provider.md rename to topics/tutorials/custom_language_support/find_usages_provider.md index bb974caa4..96bd5d685 100644 --- a/tutorials/custom_language_support/find_usages_provider.md +++ b/topics/tutorials/custom_language_support/find_usages_provider.md @@ -1,26 +1,22 @@ ---- -title: 11. Find Usages Provider ---- +[//]: # (title: 11. Find Usages Provider) + A `FindUsagesProvider` uses a word scanner to build an index of words in every file. A scanner breaks the text into words and defines the context for each word. -**Reference**: [Find Usages](/reference_guide/custom_language_support/find_usages.md) +**Reference**: [Find Usages](find_usages.md) -* bullet list -{:toc} - -## 11.1. Define a Find Usages Provider +## Define a Find Usages Provider The `SimpleFindUsagesProvider` implements [`FindUsagesProvider`](upsource:///platform/indexing-api/src/com/intellij/lang/findUsages/FindUsagesProvider.java). Using the [`DefaultWordsScanner`](upsource:///platform/indexing-api/src/com/intellij/lang/cacheBuilder/DefaultWordsScanner.java) ensures the scanner implementation is thread-safe. See the comments in `FindUsagesProvider` for more information. ```java -{% include /code_samples/simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleFindUsagesProvider.java %} ``` +{src="simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleFindUsagesProvider.java"} -## 11.2. Register the Find Usages Provider +## Register the Find Usages Provider The `SimpleFindUsagesProvider` implementation is registered with the IntelliJ Platform in the plugin configuration file using the `com.intellij.lang.findUsagesProvider` extension point. ```xml @@ -30,8 +26,8 @@ The `SimpleFindUsagesProvider` implementation is registered with the IntelliJ Pl ``` -## 11.3. Run the Project +## Run the Project Rebuild the project, and run `simple_language_plugin` in a Development Instance. The IDE now supports [Find Usages](https://www.jetbrains.com/help/idea/find-highlight-usages.html) for any property with a reference: -![Find Usages](img/find_usages.png) +![Find Usages](find_usages.png) \ No newline at end of file diff --git a/tutorials/custom_language_support/folding_builder.md b/topics/tutorials/custom_language_support/folding_builder.md similarity index 80% rename from tutorials/custom_language_support/folding_builder.md rename to topics/tutorials/custom_language_support/folding_builder.md index dfdd007f9..f03519b86 100644 --- a/tutorials/custom_language_support/folding_builder.md +++ b/topics/tutorials/custom_language_support/folding_builder.md @@ -1,34 +1,32 @@ ---- -title: 12. Folding Builder ---- +[//]: # (title: 12. Folding Builder) + A folding builder identifies the folding regions in the code. In this step of the tutorial, the folding builder is used to identify folding regions and replace the regions with specific text. Rather than the usual practice of using a folding builder to collapse a class, method, or comments to fewer lines, the folding builder replaces Simple Language keys with their corresponding values. -* bullet list -{:toc} - -## 12.1. Define a Folding Builder +## Define a Folding Builder The `SimpleFoldingBuilder` replaces usages of properties with their values by default. Start by subclassing [`FoldingBuilderEx`](upsource:///platform/core-api/src/com/intellij/lang/folding/FoldingBuilderEx.java) Note that `SimpleFoldingBuilder` also implements [`DumbAware`](upsource:///platform/core-api/src/com/intellij/openapi/project/DumbAware.java), which means the class is allowed to run in dumb mode, when indices are in background update. -> **NOTE** A folding builder must implement [`DumbAware`](upsource:///platform/core-api/src/com/intellij/openapi/project/DumbAware.java) to function in this tutorial and pass tests. + > A folding builder must implement [`DumbAware`](upsource:///platform/core-api/src/com/intellij/openapi/project/DumbAware.java) to function in this tutorial and pass tests. + > + {type="note"} -The `buildFoldRegions()` method searches down a PSI tree from `root` to find all literal expressions containing the [simple prefix](/tutorials/custom_language_support/annotator.md#define-an-annotator) `simple:`. +The `buildFoldRegions()` method searches down a PSI tree from `root` to find all literal expressions containing the [simple prefix](annotator.md#define-an-annotator) `simple:`. The remainder of such a string is expected to contain a Simple Language key, and so the text range is stored as a [`FoldingDescriptor`](upsource:///platform/core-api/src/com/intellij/lang/folding/FoldingDescriptor.java). The `getPlaceholderText()` method retrieves the Simple Language value corresponding to the key associated with the (ASTNode) provided. The IntelliJ Platform uses the value to substitute for the key when the code gets folded. ```java -{% include /code_samples/simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleFoldingBuilder.java %} ``` +{src="simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleFoldingBuilder.java"} -## 12.2. Register the Folding Builder +## Register the Folding Builder The `SimpleFoldingBuilder` implementation is registered with the IntelliJ Platform in the plugin configuration file using the `com.intellij.lang.foldingBuilder` extension point. ```xml @@ -38,10 +36,10 @@ The `SimpleFoldingBuilder` implementation is registered with the IntelliJ Platfo ``` -## 12.3. Run the Project +## Run the Project Rebuild the project, and run `simple_language_plugin` in a Development Instance. Now when a Java file is opened in the Editor, it shows the property's value instead of the key. This is because `SimpleFoldingBuilder.isCollapsedByDefault()` always returns `true`. Try using **Code \| Folding \| Expand All** to show the key rather than the value. -![Folding](img/folding.png) +![Folding](folding.png) \ No newline at end of file diff --git a/tutorials/custom_language_support/formatter.md b/topics/tutorials/custom_language_support/formatter.md similarity index 78% rename from tutorials/custom_language_support/formatter.md rename to topics/tutorials/custom_language_support/formatter.md index 2a14c0380..c5a0e14f2 100644 --- a/tutorials/custom_language_support/formatter.md +++ b/topics/tutorials/custom_language_support/formatter.md @@ -1,38 +1,34 @@ ---- -title: 15. Formatter ---- +[//]: # (title: 15. Formatter) + The IntelliJ Platform includes a powerful framework for implementing formatting for custom languages. A formatter enables reformatting code automatically based on code style settings. The formatter controls spaces, indents, wrap, and alignment. -**Reference**: [Code Formatter](/reference_guide/custom_language_support/code_formatting.md) +**Reference**: [Code Formatter](code_formatting.md) -* bullet list -{:toc} - -## 15.1. Define a Block +## Define a Block The formatting model represents the formatting structure of a file as a tree of [`Block`](upsource:///platform/code-style-api/src/com/intellij/formatting/Block.java) objects, with associated indent, wrap, alignment and spacing settings. The goal is to cover each PSI element with such a block. Since each block builds its children's blocks, it can generate extra blocks or skip any PSI elements. Define `SimpleBlock` based on [`AbstractBlock`](upsource:///platform/code-style-impl/src/com/intellij/psi/formatter/common/AbstractBlock.java). ```java -{% include /code_samples/simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleBlock.java %} ``` +{src="simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleBlock.java"} -## 15.2. Define a Formatting Model Builder +## Define a Formatting Model Builder Define a formatter that removes extra spaces except for the single spaces around the property separator. For example, reformat "foo =     bar" to "foo = bar". Create `SimpleFormattingModelBuilder` by subclassing [`FormattingModelBuilder`](upsource:///platform/code-style-api/src/com/intellij/formatting/FormattingModelBuilder.java). ```java -{% include /code_samples/simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleFormattingModelBuilder.java %} ``` +{src="simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleFormattingModelBuilder.java"} -## 15.3. Register the Formatter +## Register the Formatter The `SimpleFormattingModelBuilder` implementation is registered with the IntelliJ Platform in the plugin configuration file using the `com.intellij.lang.formatter` extension point. ```xml @@ -42,8 +38,8 @@ The `SimpleFormattingModelBuilder` implementation is registered with the Intelli ``` -## 15.4. Run the Project +## Run the Project Add some extra spaces around the `=` separator between `language` and `English`. Reformat the code by selecting **Code \| Show Reformat File Dialog** and choose **Run**. -![Formatter](img/formatter.png) +![Formatter](formatter.png) \ No newline at end of file diff --git a/tutorials/custom_language_support/go_to_symbol_contributor.md b/topics/tutorials/custom_language_support/go_to_symbol_contributor.md similarity index 81% rename from tutorials/custom_language_support/go_to_symbol_contributor.md rename to topics/tutorials/custom_language_support/go_to_symbol_contributor.md index 880bacf02..c08a444cc 100644 --- a/tutorials/custom_language_support/go_to_symbol_contributor.md +++ b/topics/tutorials/custom_language_support/go_to_symbol_contributor.md @@ -1,16 +1,12 @@ ---- -title: 13. Go To Symbol Contributor ---- +[//]: # (title: 13. Go To Symbol Contributor) + A _Go to Symbol Contributor_ helps the user to navigate to any PSI element by its name. -**Reference**: [Go to Class and Go to Symbol](/reference_guide/custom_language_support/go_to_class_and_go_to_symbol.md) +**Reference**: [Go to Class and Go to Symbol](go_to_class_and_go_to_symbol.md) -* bullet list -{:toc} - -## 13.1. Define a Helper Method for Generated PSI Elements +## Define a Helper Method for Generated PSI Elements To specify how a PSI element looks like in the **Go To Symbol** popup window, **Structure** tool window, or other components, it should implement `getPresentation()`. This method gets defined in the utility class `SimplePsiImplUtil`, and the parser and PSI classes must be regenerated. Add the following method to `SimplePsiImplUtil`: @@ -39,7 +35,7 @@ public static ItemPresentation getPresentation(final SimpleProperty element) { } ``` -## 13.2. Update Grammar and Regenerate the Parser +## Update Grammar and Regenerate the Parser Now add the `SimplePsiImplUtil.getPresentation()` to the `property` methods definition in the `Simple.bnf` grammar file by replacing the `property` definition with the lines below. Don't forget to regenerate the parser after updating the file! Right-click on the `Simple.bnf` file and select **Generate Parser Code**. @@ -52,14 +48,14 @@ property ::= (KEY? SEPARATOR VALUE?) | KEY { } ``` -## 13.3. Define a Go to Symbol Contributor +## Define a Go to Symbol Contributor To enable the `simple_language_plugin` to contribute items to **Navigate \| Class..., File..., Symbol...** lists, subclass [`ChooseByNameContributor`](upsource:///platform/lang-api/src/com/intellij/navigation/ChooseByNameContributor.java) to create `SimpleChooseByNameContributor`: ```java -{% include /code_samples/simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleChooseByNameContributor.java %} ``` +{src="simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleChooseByNameContributor.java"} -## 13.4. Register the Go To Symbol Contributor +## Register the Go To Symbol Contributor The `SimpleChooseByNameContributor` implementation is registered with the IntelliJ Platform in the plugin configuration file using the `com.intellij.gotoSymbolContributor` extension point. ```xml @@ -69,8 +65,8 @@ The `SimpleChooseByNameContributor` implementation is registered with the Intell ``` -## 13.5. Run the Project +## Run the Project Rebuild the project, and run `simple_language_plugin` in a Development Instance. The IDE now supports navigating to a property definition by name pattern via **Navigate \| Symbol** action. -![Go To Symbol](img/go_to_symbol.png){:width="800px"} +![Go To Symbol](go_to_symbol.png){width="800"} \ No newline at end of file diff --git a/tutorials/custom_language_support/grammar_and_parser.md b/topics/tutorials/custom_language_support/grammar_and_parser.md similarity index 77% rename from tutorials/custom_language_support/grammar_and_parser.md rename to topics/tutorials/custom_language_support/grammar_and_parser.md index d79fd03a3..b1c94e0b3 100644 --- a/tutorials/custom_language_support/grammar_and_parser.md +++ b/topics/tutorials/custom_language_support/grammar_and_parser.md @@ -1,31 +1,27 @@ ---- -title: 3. Grammar and Parser ---- +[//]: # (title: 3. Grammar and Parser) + In order for the IntelliJ Platform to parse a Simple Language file, tokens and elements must be defined based on [`IElementType`](upsource:///platform/core-api/src/com/intellij/psi/tree/IElementType.java). The Simple Language grammar must also be defined to generate a parser. -**Reference**: [Implementing a Parser and PSI](/reference_guide/custom_language_support/implementing_parser_and_psi.md) +**Reference**: [Implementing a Parser and PSI](implementing_parser_and_psi.md) -* bullet item -{:toc} - -## 3.1. Define a Token Type +## Define a Token Type Create `SimpleTokenType` in the `org.intellij.sdk.language.psi` package (see the `simple_language_plugin` code sample) by subclassing `IElementType`. ```java -{% include /code_samples/simple_language_plugin/src/main/java/org/intellij/sdk/language/psi/SimpleTokenType.java %} ``` +{src="simple_language_plugin/src/main/java/org/intellij/sdk/language/psi/SimpleTokenType.java"} -## 3.2. Define an Element Type +## Define an Element Type Create the `SimpleElementType` in the `org.intellij.sdk.language.psi` package by subclassing `IElementType`. ```java -{% include /code_samples/simple_language_plugin/src/main/java/org/intellij/sdk/language/psi/SimpleElementType.java %} ``` +{src="simple_language_plugin/src/main/java/org/intellij/sdk/language/psi/SimpleElementType.java"} -## 3.3. Define the Grammar +## Define the Grammar Define a grammar for the Simple Language in the `com/intellij/sdk/language/Simple.bnf` file. ```properties @@ -61,11 +57,13 @@ This flexibility allows the IntelliJ Platform to recognize incorrectly defined p Note that the `SimpleTypes` class in the `elementTypeHolderClass` field above specifies the name of a class that gets generated from the grammar; it doesn't exist at this point. -## 3.4. Generate a Parser +## Generate a Parser Now that the grammar is defined generate a parser with PSI classes via **Generate Parser Code** from the context menu on the *Simple.bnf* file. This step generates a parser and PSI elements in the `/src/main/gen` folder of the project. Mark this folder as *Generated Sources Root* and make sure everything compiles without errors. -> **TIP** Gradle plugin [gradle-grammarkit-plugin](https://github.com/JetBrains/gradle-grammar-kit-plugin) can be used alternatively. + > Gradle plugin [gradle-grammarkit-plugin](https://github.com/JetBrains/gradle-grammar-kit-plugin) can be used alternatively. + > + {type="tip"} -![Parser](img/generated_parser.png){:width="800px"} +![Parser](generated_parser.png){width="800"} \ No newline at end of file diff --git a/tutorials/custom_language_support/language_and_filetype.md b/topics/tutorials/custom_language_support/language_and_filetype.md similarity index 71% rename from tutorials/custom_language_support/language_and_filetype.md rename to topics/tutorials/custom_language_support/language_and_filetype.md index a21347ee7..d78ddab0e 100644 --- a/tutorials/custom_language_support/language_and_filetype.md +++ b/topics/tutorials/custom_language_support/language_and_filetype.md @@ -1,42 +1,38 @@ ---- -title: 2. Language and File Type ---- +[//]: # (title: 2. Language and File Type) + The IntelliJ Platform determines file type by examining the name of a file. Each language has [Language](upsource:///platform/core-api/src/com/intellij/lang/Language.java) and [LanguageFileType](upsource:///platform/core-api/src/com/intellij/openapi/fileTypes/LanguageFileType.java) objects defining the language. Register the `LanguageFileType` with the IntelliJ Platform in the plugin configuration file. -**Reference**: [Registering a File Type](/reference_guide/custom_language_support/registering_file_type.md) +**Reference**: [Registering a File Type](registering_file_type.md) -* bullet item -{:toc} - -## 2.1. Define the Language +## Define the Language The language implemented in this tutorial is named "Simple" - note the case of the name. The `SimpleLanguage` class is defined in the `org.intellij.sdk.language` package of the `simple_language_plugin` code sample: ```java -{% include /code_samples/simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleLanguage.java %} ``` +{src="simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleLanguage.java"} -## 2.2. Define an Icon +## Define an Icon The [icon](https://github.com/JetBrains/intellij-sdk-code-samples/blob/master/simple_language_plugin/src/main/resources/icons/jar-gray.png) for the Simple Language is defined by the `SimpleIcons` class. -There is nothing uniquely Simple Language-specific about [defining the icon](/reference_guide/work_with_icons_and_images.md) itself. +There is nothing uniquely Simple Language-specific about [defining the icon](work_with_icons_and_images.md) itself. The definition follows a pattern similar to defining, e.g., `SdkIcons`. ```java -{% include /code_samples/simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleIcons.java %} ``` +{src="simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleIcons.java"} -## 2.3. Define a FileType +## Define a FileType The Simple Language file type is defined by subclassing [`LanguageFileType`](upsource:///platform/core-api/src/com/intellij/openapi/fileTypes/LanguageFileType.java): ```java -{% include /code_samples/simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleFileType.java %} ``` +{src="simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleFileType.java"} -## 2.4. Register the FileType Directly +## Register the FileType Directly Direct registration is possible when targeting version 2019.2 (and later) of the IntelliJ Platform - no `FileTypeFactory` is required. Instead, the file type is registered via the `com.intellij.fileType` extension point in `plugin.xml`: @@ -48,19 +44,19 @@ Instead, the file type is registered via the `com.intellij.fileType` extension p ``` -Skip to [section 2.6](#26-run-the-project). +Skip to [section 2.6](#run-the-project). -## 2.5. Register the FileType Using a Factory +## Register the FileType Using a Factory This pattern is necessary when targeting versions of the IntelliJ Platform prior to 2019.2 -### 2.5.1 Define a FileType Factory +### Define a FileType Factory First, define `SimpleFileTypeFactory` as a subclass of [`FileTypeFactory`](upsource:///platform/platform-api/src/com/intellij/openapi/fileTypes/FileTypeFactory.java). ```java -{% include /code_samples/simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleFileTypeFactory.java %} ``` +{src="simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleFileTypeFactory.java"} -### 2.5.2 Register the FileType Factory +### Register the FileType Factory The `SimpleFileTypeFactory` is registered using the `com.intellij.openapi.fileTypes.FileTypeFactory` extension point in `plugin.xml`. ```xml @@ -69,8 +65,8 @@ The `SimpleFileTypeFactory` is registered using the `com.intellij.openapi.fileTy ``` -## 2.6. Run the Project +## Run the Project Create an empty file with the extension `*.simple`, and IntelliJ IDEA automatically associates it with our language. Note the appearance of the Simple Language file icon next to the `test.simple` file in the **Project Tool Window**, and the editor tab for the file. -![File Type Factory](img/file_type_factory.png){:width="800px"} +![File Type Factory](file_type_factory.png){width="800"} \ No newline at end of file diff --git a/tutorials/custom_language_support/lexer_and_parser_definition.md b/topics/tutorials/custom_language_support/lexer_and_parser_definition.md similarity index 71% rename from tutorials/custom_language_support/lexer_and_parser_definition.md rename to topics/tutorials/custom_language_support/lexer_and_parser_definition.md index 62525bb6a..7557861de 100644 --- a/tutorials/custom_language_support/lexer_and_parser_definition.md +++ b/topics/tutorials/custom_language_support/lexer_and_parser_definition.md @@ -1,15 +1,11 @@ ---- -title: 4. Lexer and Parser Definition ---- +[//]: # (title: 4. Lexer and Parser Definition) + The lexical analyzer defines how the contents of a file are broken into tokens, which is the basis for supporting custom language features. The easiest way to create a lexer is to use [JFlex](https://jflex.de/). -**Reference**: [Implementing Lexer](/reference_guide/custom_language_support/implementing_lexer.md) - -* bullet item -{:toc} +**Reference**: [Implementing Lexer](implementing_lexer.md) ## Required Project Configuration Change The previous tutorial step [Grammar and Parser](grammar_and_parser.md), and this page, generate source files in the directory `src/main/gen`. @@ -24,14 +20,14 @@ Or the following line in the project's `build.gradle.kts` file: sourceSets["main"].java.srcDirs("src/main/gen") ``` -## 4.1. Define a Lexer +## Define a Lexer Define a `Simple.flex` file with rules for the Simple Language lexer, as demonstrated in `org.intellij.sdk.language.Simple.flex`. ```java -{% include /code_samples/simple_language_plugin/src/main/java/org/intellij/sdk/language/Simple.flex %} ``` +{src="simple_language_plugin/src/main/java/org/intellij/sdk/language/Simple.flex"} -## 4.2. Generate a Lexer Class +## Generate a Lexer Class Now generate a lexer class via **JFlex Generator** from the context menu on `Simple.flex` file. The Grammar-Kit plugin uses the JFlex lexer generation. @@ -40,33 +36,35 @@ Choose the project root directory, for example `code_samples/simple_language_plu After that, the IDE generates the lexer under the `gen` directory, for example in `simple_language_plugin/src/main/gen/org/intellij/sdk/language/SimpleLexer`. -> **TIP** Gradle plugin [gradle-grammarkit-plugin](https://github.com/JetBrains/gradle-grammar-kit-plugin) can be used alternatively. + > Gradle plugin [gradle-grammarkit-plugin](https://github.com/JetBrains/gradle-grammar-kit-plugin) can be used alternatively. + > + {type="tip"} -See [Implementing Lexer](/reference_guide/custom_language_support/implementing_lexer.md) for more information about using _JFlex_ with the IntelliJ Platform. +See [Implementing Lexer](implementing_lexer.md) for more information about using _JFlex_ with the IntelliJ Platform. -## 4.3. Define a Lexer Adapter +## Define a Lexer Adapter The JFlex lexer needs to be adapted to the IntelliJ Platform Lexer API. This is done by subclassing [`FlexAdapter`](upsource:///platform/core-api/src/com/intellij/lexer/FlexAdapter.java). ```java -{% include /code_samples/simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleLexerAdapter.java %} ``` +{src="simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleLexerAdapter.java"} -## 4.4. Define a Root File -The `SimpleFile` implementation is the top-level node of the [tree of `PsiElements`](/reference_guide/custom_language_support/implementing_parser_and_psi.md) for a Simple Language file. +## Define a Root File +The `SimpleFile` implementation is the top-level node of the [tree of `PsiElements`](implementing_parser_and_psi.md) for a Simple Language file. ```java -{% include /code_samples/simple_language_plugin/src/main/java/org/intellij/sdk/language/psi/SimpleFile.java %} ``` +{src="simple_language_plugin/src/main/java/org/intellij/sdk/language/psi/SimpleFile.java"} -## 4.5. Define a Parser +## Define a Parser The Simple Language parser is defined by subclassing [`ParserDefinition`](upsource:///platform/core-api/src/com/intellij/lang/ParserDefinition.java). ```java -{% include /code_samples/simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleParserDefinition.java %} ``` +{src="simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleParserDefinition.java"} -## 4.6. Register the Parser Definition +## Register the Parser Definition Registering the parser definition in the `plugin.xml` file makes it available to the IntelliJ Platform. Use the `com.intellij.lang.parserDefinition` extension point for registration. For example, see `simple_language_plugin/src/main/resources/META-INF/plugin.xml`. @@ -78,7 +76,7 @@ For example, see `simple_language_plugin/src/main/resources/META-INF/plugin.xml` ``` -## 4.7. Run the Project +## Run the Project With the `simple_language_plugin` loaded in a Development Instance, create a `test.simple` properties file with the following content: ```text @@ -98,4 +96,4 @@ tab : \u0009 Now open the *PsiViewer* tool window and check how the lexer breaks the content of the file into tokens, and the parser parsed the tokens into PSI elements. -![PSI Elements](img/psi_elements.png) +![PSI Elements](psi_elements.png) \ No newline at end of file diff --git a/tutorials/custom_language_support/line_marker_provider.md b/topics/tutorials/custom_language_support/line_marker_provider.md similarity index 86% rename from tutorials/custom_language_support/line_marker_provider.md rename to topics/tutorials/custom_language_support/line_marker_provider.md index 4548f0d50..8d8bd4d29 100644 --- a/tutorials/custom_language_support/line_marker_provider.md +++ b/topics/tutorials/custom_language_support/line_marker_provider.md @@ -1,26 +1,22 @@ ---- -title: 8. Line Marker Provider ---- +[//]: # (title: 8. Line Marker Provider) + Line markers help annotate code with icons on the gutter. These markers can provide navigation targets to related code. -* bullet list -{:toc} - -## 8.1. Define a Line Marker Provider +## Define a Line Marker Provider A line marker provider annotates usages of Simple Language properties within Java code and provides navigation to the definition of these properties. The visual marker is a Simple Language icon in the gutter of the Editor window. The Simple Language marker provider subclasses [`RelatedItemLineMarkerProvider`](upsource:///platform/lang-api/src/com/intellij/codeInsight/daemon/RelatedItemLineMarkerProvider.java). -For this example, override the `collectNavigationMarkers()` method to collect usage of a Simple Language [key and separators](/tutorials/custom_language_support/language_and_filetype.md#define-the-language): +For this example, override the `collectNavigationMarkers()` method to collect usage of a Simple Language [key and separators](language_and_filetype.md#define-the-language): ```java -{% include /code_samples/simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleLineMarkerProvider.java %} ``` +{src="simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleLineMarkerProvider.java"} -## 8.2. Best Practices for Implementing Line Marker Providers +## Best Practices for Implementing Line Marker Providers This section addresses important details about implementing a marker provider. The `collectNavigationMarkers()` method should: * Only return line marker information consistent with the element passed into the method. @@ -29,7 +25,7 @@ The `collectNavigationMarkers()` method should: For example, do not return method marker for [`PsiMethod`](upsource:///java/java-psi-api/src/com/intellij/psi/PsiMethod.java). Instead, return it for the [`PsiIdentifier`](upsource:///java/java-psi-api/src/com/intellij/psi/PsiIdentifier.java) which contains the name of the method. -![Line Marker Location](img/line_marker_location.png){:width="900px"} +![Line Marker Location](line_marker_location.png){width="900"} What happens when a `LineMarkerProvider` returns marker information for a `PsiElement` that is a higher node in the PSI tree? For example, if `MyWrongLineMarkerProvider()` erroneously returns a `PsiMethod` instead of a `PsiIdentifier` element: @@ -65,7 +61,7 @@ public class MyCorrectLineMarkerProvider implements LineMarkerProvider { } ``` -## 8.3. Register the Line Marker Provider +## Register the Line Marker Provider The `SimpleLineMarkerProvider` implementation is registered with the IntelliJ Platform in the plugin configuration file using the `com.intellij.codeInsight.lineMarkerProvider` extension point. ```xml @@ -75,9 +71,9 @@ The `SimpleLineMarkerProvider` implementation is registered with the IntelliJ Pl ``` -## 8.4. Run the Project -Run the `simple_language_plugin` in a Development Instance and open the [Test file](/tutorials/custom_language_support/annotator.md#run-the-project). +## Run the Project +Run the `simple_language_plugin` in a Development Instance and open the [Test file](annotator.md#run-the-project). Now the icon appears next to line 3 on the gutter. A user can click on the icon to navigate to the property definition. -![Line Marker](img/line_marker.png) +![Line Marker](line_marker.png) \ No newline at end of file diff --git a/tutorials/custom_language_support/prerequisites.md b/topics/tutorials/custom_language_support/prerequisites.md similarity index 61% rename from tutorials/custom_language_support/prerequisites.md rename to topics/tutorials/custom_language_support/prerequisites.md index 5569256db..2567845c9 100644 --- a/tutorials/custom_language_support/prerequisites.md +++ b/topics/tutorials/custom_language_support/prerequisites.md @@ -1,19 +1,20 @@ ---- -title: 1. Prerequisites ---- +[//]: # (title: 1. Prerequisites) + -### 1.1. Download and Install IntelliJ IDEA +## Download and Install IntelliJ IDEA Download and install either IntelliJ IDEA Ultimate or IntelliJ IDEA Community Edition from [here](https://www.jetbrains.com/idea/download/). -### 1.2. Check out Community Edition Source Files -> **NOTE** While not required, having the full sources of the platform and all bundled plugins available for browsing allows finding related implementations. +## Check out Community Edition Source Files + > While not required, having the full sources of the platform and all bundled plugins available for browsing allows finding related implementations. + > + {type="note"} Download the IntelliJ IDEA Community Edition source files as described in the IntelliJ IDEA Community Edition [README](upsource:///README.md) file. -### 1.3. Install Required Plugins +## Install Required Plugins Make sure that the bundled *Plugin DevKit* plugin is enabled. Install and enable [Grammar-Kit](https://plugins.jetbrains.com/plugin/6606-grammar-kit) and [PsiViewer](https://plugins.jetbrains.com/plugin/227-psiviewer) plugins. -### 1.4. Create a Project -Create an [IntelliJ Platform Plugin project](/tutorials/build_system/prerequisites.md). +## Create a Project +Create an [IntelliJ Platform Plugin project](gradle_prerequisites.md). \ No newline at end of file diff --git a/tutorials/custom_language_support/psi_helper_and_utilities.md b/topics/tutorials/custom_language_support/psi_helper_and_utilities.md similarity index 85% rename from tutorials/custom_language_support/psi_helper_and_utilities.md rename to topics/tutorials/custom_language_support/psi_helper_and_utilities.md index 590f0dfda..90c99b383 100644 --- a/tutorials/custom_language_support/psi_helper_and_utilities.md +++ b/topics/tutorials/custom_language_support/psi_helper_and_utilities.md @@ -1,14 +1,10 @@ ---- -title: 6. PSI Helpers and Utilities ---- +[//]: # (title: 6. PSI Helpers and Utilities) + Helper classes and utilities can be embedded in the code generated by Grammar-Kit. -* bullet item -{:toc} - -## 6.1. Define Helper Methods for Generated PSI Elements +## Define Helper Methods for Generated PSI Elements Custom methods in PSI classes are defined separately, and Grammar-Kit embeds them into generated code. Define a utility class with these helper methods: @@ -41,10 +37,10 @@ public class SimplePsiImplUtil { The parser generates the `SimpleProperty` interface referenced in the code above. -## 6.2. Update Grammar and Regenerate the Parser +## Update Grammar and Regenerate the Parser Now the utility class is added to the grammar file via the `psiImplUtilClass` attribute. Add methods for a particular rule to specify which one should be used for PSI classes. -Compare the last line of the grammar below to the [previous definition](/tutorials/custom_language_support/grammar_and_parser.md#define-the-grammar). +Compare the last line of the grammar below to the [previous definition](grammar_and_parser.md#define-the-grammar). ```java { @@ -73,10 +69,10 @@ property ::= (KEY? SEPARATOR VALUE?) | KEY {methods=[getKey getValue]} After making changes to the grammar, regenerate the parser and PSI classes. -## 6.3. Define a Utility to Search Properties +## Define a Utility to Search Properties Create a utility class to search PSI elements for defined properties over the project. This utility will be used later when implementing [code completion](https://www.jetbrains.com/help/idea/auto-completing-code.html). ```java -{% include /code_samples/simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleUtil.java %} ``` +{src="simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleUtil.java"} \ No newline at end of file diff --git a/tutorials/custom_language_support/quick_fix.md b/topics/tutorials/custom_language_support/quick_fix.md similarity index 64% rename from tutorials/custom_language_support/quick_fix.md rename to topics/tutorials/custom_language_support/quick_fix.md index a767fb304..77e439bc6 100644 --- a/tutorials/custom_language_support/quick_fix.md +++ b/topics/tutorials/custom_language_support/quick_fix.md @@ -1,54 +1,50 @@ ---- -title: 18. Quick Fix ---- +[//]: # (title: 18. Quick Fix) + A quick fix for a custom language supports the IntelliJ Platform-based IDE feature [Intention Actions](https://www.jetbrains.com/help/idea/intention-actions.html#apply-intention-actions). For the Simple Language, this tutorial adds a quick fix that helps to define an unresolved property from its usage. -**Reference**: [Code Inspections and Intentions](/reference_guide/custom_language_support/code_inspections_and_intentions.md) +**Reference**: [Code Inspections and Intentions](code_inspections_and_intentions.md) -* bullet list -{:toc} - -## 18.1. Update the Element Factory +## Update the Element Factory The `SimpleElementFactory` is updated to include two new methods to support the user choice of creating a new property for the Simple Language quick fix. -The new `createCRLF()` method supports adding a newline to the end of the [`test.simple`](/tutorials/custom_language_support/lexer_and_parser_definition.md#run-the-project) file before adding a new property. +The new `createCRLF()` method supports adding a newline to the end of the [`test.simple`](lexer_and_parser_definition.md#run-the-project) file before adding a new property. A new overload of `createProperty()` creates a new `key`-`value` pair for Simple Language. ```java -{% include /code_samples/simple_language_plugin/src/main/java/org/intellij/sdk/language/psi/SimpleElementFactory.java %} ``` +{src="simple_language_plugin/src/main/java/org/intellij/sdk/language/psi/SimpleElementFactory.java"} -## 18.2. Define an Intention Action +## Define an Intention Action The `SimpleCreatePropertyQuickFix` creates a property in the file chosen by the user - in this case, a Java file containing a `prefix:key` - and navigate to this property after creation. Under the hood, `SimpleCreatePropertyQuickFix` is an Intention Action. For a more in-depth example of an Intention Action, see [`conditional_operator_intention`](https://github.com/JetBrains/intellij-sdk-code-samples/tree/master/conditional_operator_intention). ```java -{% include /code_samples/simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleCreatePropertyQuickFix.java %} ``` +{src="simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleCreatePropertyQuickFix.java"} -## 18.3. Update the Annotator +## Update the Annotator When a `badProperty` annotation is created, the `badProperty.registerFix()` method is called. This method call registers the `SimpleCreatePropertyQuickFix` as the Intention Action for the Intellij Platform to use to correct the problem. ```java -{% include /code_samples/simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleAnnotator.java %} ``` +{src="simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleAnnotator.java"} -## 18.4. Run the Project -Open the test [Java file](/tutorials/custom_language_support/annotator.md#run-the-project) in an IDE Development Instance running the `simple_language_plugin`. +## Run the Project +Open the test [Java file](annotator.md#run-the-project) in an IDE Development Instance running the `simple_language_plugin`. To test `SimpleCreatePropertyQuickFix`, change `simple:website` to `simple:website.url`. The key `website.url` is highlighted by `SimpleAnnotator` as an invalid key, as shown below. Choose "Create Property". -![Quick Fix](img/quick_fix.png){:width="800px"} +![Quick Fix](quick_fix.png){width="800"} The IDE opens the `test.simple` file and adds `website.url` as a new key. Add the new value `jetbrains.com` for the new `website.url` key. -![New Property](img/new_property.png) +![New Property](new_property.png) -Now switch back to the Java file; the new key is highlighted as valid. +Now switch back to the Java file; the new key is highlighted as valid. \ No newline at end of file diff --git a/tutorials/custom_language_support/reference_contributor.md b/topics/tutorials/custom_language_support/reference_contributor.md similarity index 78% rename from tutorials/custom_language_support/reference_contributor.md rename to topics/tutorials/custom_language_support/reference_contributor.md index ce09a00c9..9497c09fa 100644 --- a/tutorials/custom_language_support/reference_contributor.md +++ b/topics/tutorials/custom_language_support/reference_contributor.md @@ -1,34 +1,32 @@ ---- -title: 10. Reference Contributor ---- +[//]: # (title: 10. Reference Contributor) + The references functionality is one of the most important parts in the implementation of custom language support. Resolving references means the ability to go from the usage of an element to its declaration, completion, rename refactoring, find usages, etc. -> **NOTE** Every PSI element that can be renamed or referenced needs to implement [`PsiNamedElement`](upsource:///platform/core-api/src/com/intellij/psi/PsiNamedElement.java) interface. + > Every PSI element that can be renamed or referenced needs to implement [`PsiNamedElement`](upsource:///platform/core-api/src/com/intellij/psi/PsiNamedElement.java) interface. + > + {type="note"} -**Reference**: [References and Resolve](/reference_guide/custom_language_support/references_and_resolve.md) +**Reference**: [References and Resolve](references_and_resolve.md) -* bullet list -{:toc} - -## 10.1. Define a Named Element Class +## Define a Named Element Class The classes below show how the Simple Language fulfills the need to implement `PsiNamedElement`. The `SimpleNamedElement` interface is subclassed from [`PsiNameIdentifierOwner`](upsource:///platform/core-api/src/com/intellij/psi/PsiNameIdentifierOwner.java). ```java -{% include /code_samples/simple_language_plugin/src/main/java/org/intellij/sdk/language/psi/SimpleNamedElement.java %} ``` +{src="simple_language_plugin/src/main/java/org/intellij/sdk/language/psi/SimpleNamedElement.java"} The `SimpleNamedElementImpl` class implements the `SimpleNamedElement` interface and extends [`ASTWrapperPsiElement`](upsource:///platform/core-impl/src/com/intellij/extapi/psi/ASTWrapperPsiElement.java). ```java -{% include /code_samples/simple_language_plugin/src/main/java/org/intellij/sdk/language/psi/impl/SimpleNamedElementImpl.java %} ``` +{src="simple_language_plugin/src/main/java/org/intellij/sdk/language/psi/impl/SimpleNamedElementImpl.java"} -## 10.2. Define Helper Methods for Generated PSI Elements +## Define Helper Methods for Generated PSI Elements Modify `SimplePsiImplUtil` to support new methods that get added to the PSI class for Simple Language. Note that `SimpleElementFactory` isn't defined until the [next step](#define-an-element-factory), so for now it shows as an error. @@ -65,7 +63,7 @@ public class SimplePsiImplUtil { } ``` -## 10.3. Define an Element Factory +## Define an Element Factory The `SimpleElementFactory` provides methods for creating `SimpleFile`. ```java @@ -89,7 +87,7 @@ public class SimpleElementFactory { } ``` -## 10.4. Update Grammar and Regenerate the Parser +## Update Grammar and Regenerate the Parser Now make corresponding changes to the `Simple.bnf` grammar file by replacing the `property` definition with the lines below. Don't forget to regenerate the parser after updating the file! Right-click on the `Simple.bnf` file and select **Generate Parser Code**. @@ -102,25 +100,25 @@ property ::= (KEY? SEPARATOR VALUE?) | KEY { } ``` -## 10.5. Define a Reference +## Define a Reference Now define a reference class to resolve a property from its usage. This requires extending [`PsiReferenceBase`](upsource:///platform/core-api/src/com/intellij/psi/PsiReferenceBase.java) and implementing [`PsiPolyVariantReference`](upsource:///platform/core-api/src/com/intellij/psi/PsiPolyVariantReference.java). The latter enables the reference to resolve to more than one element or to resolve result(s) for a superset of valid resolve cases. ```java -{% include /code_samples/simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleReference.java %} ``` +{src="simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleReference.java"} -## 10.6. Define a Reference Contributor +## Define a Reference Contributor A reference contributor allows the `simple_language_plugin` to provide references to Simple Language from elements in other languages such as Java. Create `SimpleReferenceContributor` by subclassing [`PsiReferenceContributor`](upsource:///platform/core-api/src/com/intellij/psi/PsiReferenceContributor.java). Contribute a reference to each usage of a property: ```java -{% include /code_samples/simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleReferenceContributor.java %} ``` +{src="simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleReferenceContributor.java"} -## 10.7. Register the Reference Contributor +## Register the Reference Contributor The `SimpleReferenceContributor` implementation is registered with the IntelliJ Platform using the `com.intellij.psi.referenceContributor` extension point. ```xml @@ -129,26 +127,26 @@ The `SimpleReferenceContributor` implementation is registered with the IntelliJ ``` -## 10.8. Run the Project +## Run the Project with the Reference Contributor Rebuild the project, and run `simple_language_plugin` in a Development Instance. The IDE now resolves the property and provides [completion](https://www.jetbrains.com/help/idea/auto-completing-code.html#basic_completion) suggestions: -![Reference Contributor](img/reference_contributor.png){:width="800px"} +![Reference Contributor](reference_contributor.png){width="800"} The [Rename refactoring](https://www.jetbrains.com/help/idea/rename-refactorings.html#invoke-rename-refactoring) functionality is now available from definition and usages. -![Rename](img/rename.png){:width="800px"} +![Rename](rename.png){width="800"} -## 10.9. Define a Refactoring Support Provider +## Define a Refactoring Support Provider Support for in-place refactoring is specified explicitly in a refactoring support provider. Create `SimpleRefactoringSupportProvider` by subclassing [`RefactoringSupportProvider`](upsource:///platform/lang-api/src/com/intellij/lang/refactoring/RefactoringSupportProvider.java) As long as an element is a `SimpleProperty` it is allowed to be refactored: ```java -{% include /code_samples/simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleRefactoringSupportProvider.java %} ``` +{src="simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleRefactoringSupportProvider.java"} -## 10.10. Register the Refactoring Support Provider +## Register the Refactoring Support Provider The `SimpleRefactoringSupportProvider` implementation is registered with the IntelliJ Platform in the plugin configuration file using the `com.intellij.lang.refactoringSupport` extension point. ```xml @@ -158,8 +156,8 @@ The `SimpleRefactoringSupportProvider` implementation is registered with the Int ``` -## 10.11. Run the Project +## Run the Project Rebuild the project, and run `simple_language_plugin` in a Development Instance. The IDE now supports [refactoring](https://www.jetbrains.com/help/idea/rename-refactorings.html) suggestions: -![In Place Rename](img/in_place_rename.png){:width="800px"} +![In Place Rename](in_place_rename.png){width="800"} \ No newline at end of file diff --git a/tutorials/custom_language_support/structure_view_factory.md b/topics/tutorials/custom_language_support/structure_view_factory.md similarity index 77% rename from tutorials/custom_language_support/structure_view_factory.md rename to topics/tutorials/custom_language_support/structure_view_factory.md index e4c361497..5288dbdc3 100644 --- a/tutorials/custom_language_support/structure_view_factory.md +++ b/topics/tutorials/custom_language_support/structure_view_factory.md @@ -1,43 +1,39 @@ ---- -title: 14. Structure View Factory ---- +[//]: # (title: 14. Structure View Factory) + The structure view can be customized for a specific file type. Creating a structure view factory allows showing the structure of any file in a _Structure_ Tool Window for easy navigation between items in the current editor. -**Reference**: [Structure View](/reference_guide/custom_language_support/structure_view.md) +**Reference**: [Structure View](structure_view.md) -* bullet list -{:toc} - -## 14.1. Define a Structure View Factory +## Define a Structure View Factory The structure view factory implements [`PsiStructureViewFactory`](upsource:///platform/editor-ui-api/src/com/intellij/lang/PsiStructureViewFactory.java). The `getStructureViewBuilder()` implementation reuses the IntelliJ Platform class [`TreeBasedStructureViewBuilder`](upsource:///platform/editor-ui-api/src/com/intellij/ide/structureView/TreeBasedStructureViewBuilder.java). At this point the project will not compile until `SimpleStructureViewModel` is [implemented below](#define-a-structure-view-model). ```java -{% include /code_samples/simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleStructureViewFactory.java %} ``` +{src="simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleStructureViewFactory.java"} -## 14.2. Define a Structure View Model +## Define a Structure View Model The `SimpleStructureViewModel` is created by implementing [`StructureViewModel`](upsource:///platform/editor-ui-api/src/com/intellij/ide/structureView/StructureViewModel.java), which defines the model for data displayed in the standard structure view. It also extends [`StructureViewModelBase`](upsource:///platform/editor-ui-api/src/com/intellij/ide/structureView/StructureViewModelBase.java), an implementation that links the model to a text editor. ```java -{% include /code_samples/simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleStructureViewModel.java %} ``` +{src="simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleStructureViewModel.java"} -## 14.3. Define a Structure View Element +## Define a Structure View Element The `SimpleStructureViewElement` implements [`StructureViewTreeElement`](upsource:///platform/editor-ui-api/src/com/intellij/ide/structureView/StructureViewTreeElement.java) and [`SortableTreeElement`](upsource:///platform/editor-ui-api/src/com/intellij/ide/util/treeView/smartTree/SortableTreeElement.java). The `StructureViewTreeElement` represents an element in the Structure View tree model. The `SortableTreeElement` represents an item in a smart tree that allows using text other than the presentable text as a key for alphabetic sorting. ```java -{% include /code_samples/simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleStructureViewElement.java %} ``` +{src="simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleStructureViewElement.java"} -## 14.4. Register the Structure View Factory +## Register the Structure View Factory The `SimpleStructureViewFactory` implementation is registered with the IntelliJ Platform in the plugin configuration file using the `com.intellij.lang.psiStructureViewFactory` extension point. ```xml @@ -47,9 +43,9 @@ The `SimpleStructureViewFactory` implementation is registered with the IntelliJ ``` -## 14.5. Run the Project +## Run the Project Rebuild the project, and run `simple_language_plugin` in a Development Instance. Open the `test.simple` file and choose **View \| Tool Windows \| Structure**. The IDE now supports a structure view of the Simple Language: -![Structure View](img/structure_view.png) +![Structure View](structure_view.png) \ No newline at end of file diff --git a/tutorials/custom_language_support/syntax_highlighter_and_color_settings_page.md b/topics/tutorials/custom_language_support/syntax_highlighter_and_color_settings_page.md similarity index 64% rename from tutorials/custom_language_support/syntax_highlighter_and_color_settings_page.md rename to topics/tutorials/custom_language_support/syntax_highlighter_and_color_settings_page.md index ae2e998b4..7180e064c 100644 --- a/tutorials/custom_language_support/syntax_highlighter_and_color_settings_page.md +++ b/topics/tutorials/custom_language_support/syntax_highlighter_and_color_settings_page.md @@ -1,35 +1,31 @@ ---- -title: 5. Syntax Highlighter and Color Settings Page ---- +[//]: # (title: 5. Syntax Highlighter and Color Settings Page) + The first level of syntax highlighting is based on the lexer output, and is provided by `SyntaxHighlighter`. A plugin can also define color settings based on `ColorSettingPage` so the user can configure highlight colors. The `SimpleSyntaxHighlighter`, `SimpleSyntaxHighlighterFactory`, and `SimpleColorSettingsPage` discussed on this page are demonstrated in the `simple_language_plugin` code sample. -**Reference**: [Syntax Highlighting and Error Highlighting](/reference_guide/custom_language_support/syntax_highlighting_and_error_highlighting.md) +**Reference**: [Syntax Highlighting and Error Highlighting](syntax_highlighting_and_error_highlighting.md) -* bullet list -{:toc} - -## 5.1. Define a Syntax Highlighter +## Define a Syntax Highlighter The Simple Language syntax highlighter class extends [`SyntaxHighlighterBase`](upsource:///platform/editor-ui-api/src/com/intellij/openapi/fileTypes/SyntaxHighlighterBase.java). -As recommended in [Color Scheme Management](/reference_guide/color_scheme_management.md#text-attribute-key-dependency), the Simple Language highlighting text attributes are specified as a dependency on one of standard Intellij Platform keys. +As recommended in [Color Scheme Management](color_scheme_management.md#text-attribute-key-dependency), the Simple Language highlighting text attributes are specified as a dependency on one of standard Intellij Platform keys. For the Simple Language, define only one scheme. ```java -{% include /code_samples/simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleSyntaxHighlighter.java %} ``` +{src="simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleSyntaxHighlighter.java"} -### 5.2. Define a Syntax Highlighter Factory +### Define a Syntax Highlighter Factory The factory provides a standard way for the IntelliJ Platform to instantiate the syntax highlighter for Simple Language files. Here, `SimpleSyntaxHighlighterFactory` subclasses [`SyntaxHighlighterFactory`](upsource:///platform/editor-ui-api/src/com/intellij/openapi/fileTypes/SyntaxHighlighterFactory.java). ```java -{% include /code_samples/simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleSyntaxHighlighterFactory.java %} ``` +{src="simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleSyntaxHighlighterFactory.java"} -### 5.3. Register the Syntax Highlighter Factory +### Register the Syntax Highlighter Factory Register the factory with the IntelliJ Platform in the plugin configuration file using the `com.intellij.lang.syntaxHighlighterFactory` extension point. ```xml @@ -39,21 +35,21 @@ Register the factory with the IntelliJ Platform in the plugin configuration file ``` -### 5.4. Run the Project -Open the example Simple Language [properties file ](/tutorials/custom_language_support/lexer_and_parser_definition.md#run-the-project) (`test.simple`) in the IDE Development Instance. +### Run the Project with Default Colors +Open the example Simple Language [properties file ](lexer_and_parser_definition.md#run-the-project) (`test.simple`) in the IDE Development Instance. The colors for Simple Language Key, Separator, and Value highlighting default to the IDE _Language Defaults_ for Keyword, Braces, Operators, and Strings, respectively. -![Syntax highlighter](img/syntax_highlighter.png) +![Syntax highlighter](syntax_highlighter.png) -## 5.5. Define a Color Settings Page +## Define a Color Settings Page The color settings page adds the ability for users to customize color settings for the highlighting in Simple Language files. The `SimpleColorSettingsPage` implements [`ColorSettingsPage`](upsource:///platform/platform-api/src/com/intellij/openapi/options/colors/ColorSettingsPage.java). ```java -{% include /code_samples/simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleColorSettingsPage.java %} ``` +{src="simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleColorSettingsPage.java"} -### 5.6. Register the Color Settings Page +### Register the Color Settings Page Register the Simple Language color settings page with the IntelliJ Platform in the plugin configuration file using the `com.intellij.colorSettingsPage` extension point. ```xml @@ -62,8 +58,8 @@ Register the Simple Language color settings page with the IntelliJ Platform in t ``` -### 5.7. Run the Project +### Run the Project In the IDE Development Instance, open the Simple Language highlight settings page: **Preferences/Settings \| Editor \| Color Scheme \| Simple**. Each color initially inherits from a _Language Defaults_ value. -![Color Settings Page](img/color_settings_page.png) +![Color Settings Page](color_settings_page.png) \ No newline at end of file diff --git a/topics/tutorials/custom_language_support_tutorial.md b/topics/tutorials/custom_language_support_tutorial.md new file mode 100644 index 000000000..acbb7cdc5 --- /dev/null +++ b/topics/tutorials/custom_language_support_tutorial.md @@ -0,0 +1,32 @@ +[//]: # (title: Custom Language Support Tutorial) + + + +In this tutorial we will add support for a [.properties](https://en.wikipedia.org/wiki/.properties) language and its usages within Java code. + + > IntelliJ Platform support for custom languages is discussed in more depth in the [Custom Language Support](custom_language_support.md) section. +> Corresponding parts are linked under "Reference" on top of each page in this tutorial. + > + {type="tip"} + +The example plugin used in this tutorial is the [`simple_language_plugin`](https://github.com/JetBrains/intellij-sdk-code-samples/tree/master/simple_language_plugin) code sample. +This a step-by-step tutorial, and it requires completing each step, in order: + +* [1. Prerequisites](prerequisites.md) +* [2. Language and File Type](language_and_filetype.md) +* [3. Grammar and Parser](grammar_and_parser.md) +* [4. Lexer and Parser Definition](lexer_and_parser_definition.md) +* [5. Syntax Highlighter and Color Settings Page](syntax_highlighter_and_color_settings_page.md) +* [6. PSI Helpers and Utilities](psi_helper_and_utilities.md) +* [7. Annotator](annotator.md) +* [8. Line Marker Provider](line_marker_provider.md) +* [9. Completion Contributor](completion_contributor.md) +* [10. Reference Contributor](reference_contributor.md) +* [11. Find Usages Provider](find_usages_provider.md) +* [12. Folding Builder](folding_builder.md) +* [13. Go To Symbol Contributor](go_to_symbol_contributor.md) +* [14. Structure View Factory](structure_view_factory.md) +* [15. Formatter](formatter.md) +* [16. Code Style Settings](code_style_settings.md) +* [17. Commenter](commenter.md) +* [18. Quick Fix](quick_fix.md) \ No newline at end of file diff --git a/tutorials/editor_basics.md b/topics/tutorials/editor_basics.md similarity index 75% rename from tutorials/editor_basics.md rename to topics/tutorials/editor_basics.md index 913b96911..7af25c7d0 100644 --- a/tutorials/editor_basics.md +++ b/topics/tutorials/editor_basics.md @@ -1,15 +1,14 @@ ---- -title: Basics of Working with the Editor ---- +[//]: # (title: Basics of Working with the Editor) + This tutorial will lead you through the series of steps showing how to work with the IntelliJ Platform Editor, how to access and modify text it contains, and how to handle events sent to the editor. -* [1. Working With Text](editor_basics/working_with_text.md) -* [2. Editor coordinate systems: positions and offsets](editor_basics/coordinates_system.md) -* [3. Handling Editor Events](editor_basics/editor_events.md) +* [1. Working With Text](working_with_text.md) +* [2. Editor coordinate systems: positions and offsets](coordinates_system.md) +* [3. Handling Editor Events](editor_events.md) **Note:** The part of the API described in this tutorial only allows operations with text. -For operations that require access to the PSI please see the [PSI Cookbook](/basics/psi_cookbook.md) section. +For operations that require access to the PSI please see the [PSI Cookbook](psi_cookbook.md) section. **See also:** The following are referenced in the tutorial: @@ -22,5 +21,5 @@ The following are referenced in the tutorial: * [`TypedAction`](upsource:///platform/platform-api/src/com/intellij/openapi/editor/actionSystem/TypedAction.java). **Related topics:** -* [Action System](/tutorials/action_system.md) -* [Threading Issues](/basics/architectural_overview/general_threading_rules.md) +* [Action System](action_system.md) +* [Threading Issues](general_threading_rules.md) \ No newline at end of file diff --git a/tutorials/editor_basics/coordinates_system.md b/topics/tutorials/editor_basics/coordinates_system.md similarity index 94% rename from tutorials/editor_basics/coordinates_system.md rename to topics/tutorials/editor_basics/coordinates_system.md index 4cbcc488d..60d462edf 100644 --- a/tutorials/editor_basics/coordinates_system.md +++ b/topics/tutorials/editor_basics/coordinates_system.md @@ -1,28 +1,23 @@ ---- -title: Editor Coordinate Systems - Caret Positions and Offsets ---- +[//]: # (title: Editor Coordinate Systems - Caret Positions and Offsets) + The previous tutorial [Working with Text](working_with_text.md) demonstrated how to use actions to access a caret placed in a document open in an editor. The examples replaced selected text in a document by using information about the caret. -Every caret has a set of properties describing its position in one of several coordinate systems. -This tutorial describes how to access information about the caret(s) in an editor. -The tutorial presents the following sections: - -* bullet list -{:toc} +Every caret has a set of properties describing its position in one of several coordinate systems. +This tutorial describes how to access information about the caret(s) in an editor. ## Introduction In this tutorial, the [editor_basics](https://github.com/JetBrains/intellij-sdk-code-samples/tree/master/editor_basics) code sample is used to explore caret positions. In particular, the **Caret Position** action added by `editor_basics` to the editor context menu is used to retrieve information about the current caret position. A keyboard shortcut can also initiate the action. -![Editor Basics Menu](img/basics.png){:width="600px"} +![Editor Basics Menu](basics.png){width="600"} The source code for the Java class behind the menu action is [EditorAreaIllustration](https://github.com/JetBrains/intellij-sdk-code-samples/blob/master/editor_basics/src/main/java/org/intellij/sdk/editor/EditorAreaIllustration.java). The focus of discussion will be the `EditorAreaIllustration.actionPerformed()` method. -For more information about creating action classes, see the [Actions Tutorial](/tutorials/action_system.md) which covers the topic in depth. +For more information about creating action classes, see the [Actions Tutorial](action_system.md) which covers the topic in depth. ## Caret Positions from the CaretModel and Caret Objects The properties of a caret can be accessed by obtaining an instance of the [`CaretModel`](upsource:///platform/editor-ui-api/src/com/intellij/openapi/editor/CaretModel.java) object. @@ -56,9 +51,9 @@ The character "s" in the red box represents placing the cursor on that character It has the caret position of line 1, column 9, and Offset 28. More about caret [Offsets](#caret-offset) is discussed below. -![Editor Coordinates](img/editor_coords.png){:width="800px"} +![Editor Coordinates](editor_coords.png){width="800"} -The [Multiple Carets](/reference_guide/multiple_carets.md) documentation covers the subject of more than one caret in an Editor. +The [Multiple Carets](multiple_carets.md) documentation covers the subject of more than one caret in an Editor. For this tutorial, be aware there may be more than one caret in an `Editor` at any given time. Consequently, examples use the _Primary Caret_ in an `Editor`. If there is only one caret in an `Editor`, it is the Primary Caret. @@ -77,7 +72,7 @@ The caret - a blue block - is placed on the letter "p" in "public." Using the `editor_basics` **Caret Position** action to inspect the caret, it is reported to be at Logical Position (5,0) - which is line 5, character 0 - the first character in the line. This means that caret Logical Position is not changed by Code Folding: -![Caret Logical Position with Folding](img/logical_pos_folded.png){:width="800px"} +![Caret Logical Position with Folding](logical_pos_folded.png){width="800"} However, note that applying Code Folding _does change the reported Visual Position_ of the caret even if the Logical Position stays constant. More about [Visual Position](#caret-visual-position) is discussed below. @@ -95,7 +90,7 @@ With the caret placed at the same character location as in previous tests, it is However, the Visual Position line number has increased by one! The comments on each line illustrate how the Soft Wrap portion of Logical line three is evaluated as Visual Position line four, as though it was a separate line. -![Caret Visual Position with Soft-Wrap](img/vis_pos_soft_wrap.png){:width="800px"} +![Caret Visual Position with Soft-Wrap](vis_pos_soft_wrap.png){width="800"} The Logical and Visual Position objects for a caret are obtained from the [`Caret`](upsource:///platform/editor-ui-api/src/com/intellij/openapi/editor/Caret.java) object, as shown in the code snippet below. @@ -140,9 +135,9 @@ Note that the text is unidirectional in this example. In the Logical Position the caret leans forward, meaning it is associated with the succeeding character in the Logical line. For the Visual Position the caret leans right, indicating its association with the succeeding character in the Visual line. -![Caret Column Position - Block Caret](img/caret_col_pos_block.png){:width="800px"} +![Caret Column Position - Block Caret](caret_col_pos_block.png){width="800"} -
+
Consider the Java snippet below, and use the `editor_basics` **Caret Position** action to report caret information at each step. Be sure to use the keyboard shortcut to invoke the action so that the caret position is not disturbed. @@ -185,8 +180,7 @@ The example below demonstrates the Offset of a caret placed at the first charact Note the Offset is 22, which is one greater than the number of visible characters on line zero, and the first character on line one. This apparent discrepancy is actually correct because the Offset includes the newline character for line zero. -![Line 2 Caret Offset](img/caret_offset_l2.png){:width="800px"} - +![Line 2 Caret Offset](caret_offset_l2.png){width="800"} ## Displaying Caret Positions To display the values of caret Logical and Visual positions, and Offset, a @@ -214,4 +208,4 @@ public class EditorAreaIllustration extends AnAction { } } -``` +``` \ No newline at end of file diff --git a/tutorials/editor_basics/editor_events.md b/topics/tutorials/editor_basics/editor_events.md similarity index 96% rename from tutorials/editor_basics/editor_events.md rename to topics/tutorials/editor_basics/editor_events.md index 6e65cf813..76963d843 100644 --- a/tutorials/editor_basics/editor_events.md +++ b/topics/tutorials/editor_basics/editor_events.md @@ -1,6 +1,5 @@ ---- -title: 3. Handling Editor Events ---- +[//]: # (title: 3. Handling Editor Events) + The previous tutorial [Editor Coordinate Systems](coordinates_system.md) described working with caret coordinate systems in an editor window. @@ -10,21 +9,16 @@ Two classes from the [editor_basics](https://github.com/JetBrains/intellij-sdk-c * Using an IntelliJ Platform [`EditorActionHandler`](upsource:///platform/platform-api/src/com/intellij/openapi/editor/actionSystem/EditorActionHandler.java) to manipulate a caret. * Creating and registering a custom [`TypedActionHandler`](upsource:///platform/platform-api/src/com/intellij/openapi/editor/actionSystem/TypedActionHandler.java) to intercept keystrokes and change the document. -The tutorial presents the following sections: - -* bullet list -{:toc} - ## Using an IntelliJ Platform EditorActionHandler In this portion of the tutorial, the [editor_basics](https://github.com/JetBrains/intellij-sdk-code-samples/tree/master/editor_basics) code sample is used to demonstrate cloning an existing caret. A custom action class will use `EditorActionManager` to access a specific `EditorActionHandler` for caret cloning. The `editor_basics` code sample adds an **Editor Add Caret** menu item to the editor context menu: -![Editor Basics Menu](img/basics.png){:width="600px"} +![Editor Basics Menu](basics.png){width="600"} ### Creating the Menu Action Class The source code for the Java action class is [EditorHandlerIllustration](https://github.com/JetBrains/intellij-sdk-code-samples/blob/master/editor_basics/src/main/java/org/intellij/sdk/editor/EditorHandlerIllustration.java), a subclass of `AnAction`. -For more information about creating action classes, see the [Actions Tutorial](/tutorials/action_system.md) which covers the topic in depth. +For more information about creating action classes, see the [Actions Tutorial](action_system.md) which covers the topic in depth. The `EditorHandlerIllustration` action is registered in the _editor_basic_ [`plugin.xml`](https://github.com/JetBrains/intellij-sdk-code-samples/blob/master/editor_basics/src/main/resources/META-INF/plugin.xml) file. Note that this action class is registered to appear on the Editor context menu. @@ -98,7 +92,6 @@ public class EditorHandlerIllustration extends AnAction { } ``` - ## Creating a Custom TypedActionHandler The [`TypedActionHandler`](upsource:///platform/platform-api/src/com/intellij/openapi/editor/actionSystem/TypedActionHandler.java) interface is the basis for classes that handle keystroke events from the editor. Custom implementations of the class are registered to handle editor keystroke events, and receive a callback for each keystroke. @@ -148,4 +141,4 @@ public class EditorHandlerIllustration extends AnAction { Placing the registration code in the `EditorHandlerIllustration` class is somewhat arbitrary in the sense that the registration of `MyTypedHandler` has nothing to do with the `EditorHandlerIllustration` class. However, the `EditorHandlerIllustration` class is convenient because as an action it gets instantiated at application startup. On instantiation, the `static` block of code in `EditorHandlerIllustration` gets evaluated. -In the `editor_basics` code sample any of the `AnAction` derived classes would work for registering `MyTypedHandler`. +In the `editor_basics` code sample any of the `AnAction` derived classes would work for registering `MyTypedHandler`. \ No newline at end of file diff --git a/tutorials/editor_basics/working_with_text.md b/topics/tutorials/editor_basics/working_with_text.md similarity index 89% rename from tutorials/editor_basics/working_with_text.md rename to topics/tutorials/editor_basics/working_with_text.md index d8c7663ce..e24a0947b 100644 --- a/tutorials/editor_basics/working_with_text.md +++ b/topics/tutorials/editor_basics/working_with_text.md @@ -1,30 +1,25 @@ ---- -title: Working with Text ---- +[//]: # (title: Working with Text) + -This tutorial shows how to use actions to access a caret placed in a document open in an editor. -Using information about the caret, replace selected text in a document with a string. -The tutorial presents the following sections: - -* bullet list -{:toc} +This tutorial shows how to use actions to access a caret placed in a document open in an editor. +Using information about the caret, replace selected text in a document with a string. ## Introduction The approach in this tutorial relies heavily on creating and registering actions. -To review the fundamentals of creating and registering actions, refer to the [Actions Tutorial](/tutorials/action_system.md). +To review the fundamentals of creating and registering actions, refer to the [Actions Tutorial](action_system.md). Multiple examples are used from the [editor_basics](https://github.com/JetBrains/intellij-sdk-code-samples/tree/master/editor_basics) plugin code sample from the IntelliJ Platform SDK. It may be helpful to open that project in an IntelliJ Platform-based IDE, build the project, run it, select some text in the editor, and invoke the **Editor Replace Text** menu item on the editor context menu. -![Editor Basics Menu](img/basics.png){:width="600px"} +![Editor Basics Menu](basics.png){width="600"} ## Creating a New Menu Action In this example, we access the `Editor` from an action. The source code for the Java class in this example is [EditorIllustrationAction](https://github.com/JetBrains/intellij-sdk-code-samples/blob/master/editor_basics/src/main/java/org/intellij/sdk/editor/EditorIllustrationAction.java). To register the action, we must add the corresponding elements to the `` section of the plugin configuration file [plugin.xml](https://github.com/JetBrains/intellij-sdk-code-samples/blob/master/editor_basics/src/main/resources/META-INF/plugin.xml). -For more information, refer to the [Registering Actions](/tutorials/action_system/working_with_custom_actions.md#registering-a-custom-action) section of the Actions Tutorial. +For more information, refer to the [Registering Actions](working_with_custom_actions.md#registering-a-custom-action) section of the Actions Tutorial. The `EditorIllustrationAction` action is registered in the group `EditorPopupMenu` so it will be available from the context menu when focus is on the editor: ```xml @@ -39,7 +34,7 @@ The `EditorIllustrationAction` action is registered in the group `EditorPopupMen ## Defining the Menu Action's Visibility To determine conditions by which the action will be visible and available requires `EditorIllustrationAction` to override the `AnAction.update()` method. -For more information, refer to [Extending the Update Method](/tutorials/action_system/working_with_custom_actions.md#extending-the-update-method) section of the Actions Tutorial. +For more information, refer to [Extending the Update Method](working_with_custom_actions.md#extending-the-update-method) section of the Actions Tutorial. To work with a selected part of the text, it's reasonable to make the menu action available only when the following requirements are met: * There is a [`Project`](upsource:///platform/core-api/src/com/intellij/openapi/project/Project.java) object, @@ -99,7 +94,6 @@ The model classes are located in [editor](upsource:///platform/editor-ui-api/src * [`ScrollingModel`](upsource:///platform/editor-ui-api/src/com/intellij/openapi/editor/ScrollingModel.java), * [`SoftWrapModel`](upsource:///platform/editor-ui-api/src/com/intellij/openapi/editor/SoftWrapModel.java) - ## Safely Replacing Selected Text in the Document Based on the evaluation of conditions by `EditorIllustrationAction.update()`, the `EditorIllustrationAction` action menu item is visible. To make the menu item do something, the `EditorIllustrationAction` class must override the `AnAction.actionPerformed()` method. @@ -109,7 +103,7 @@ As explained below, this will require the `EditorIllustrationAction.actionPerfor * Safely replace the contents of the selection. Modifying the selected text requires an instance of the [`Document`](upsource:///platform/core-api/src/com/intellij/openapi/editor/Document.java) object, which is accessed from the `Editor` object. -The [Document](/basics/architectural_overview/documents.md) represents the contents of a text file loaded into memory and opened in an IntelliJ Platform-based IDE editor. +The [Document](documents.md) represents the contents of a text file loaded into memory and opened in an IntelliJ Platform-based IDE editor. An instance of the `Document` will be used later when a text replacement is performed. The text replacement will also require information about where the selection is in the document, which is provided by the primary `Caret` object, obtained from the `CaretModel`. @@ -117,7 +111,7 @@ Selection information is measured in terms of [Offset](coordinates_system.md#car Text replacement could be done by calling the `Document` object's `replaceString()` method. However, safely replacing the text requires the `Document` to be locked and any changes performed in a write action. -See the [Threading Issues](/basics/architectural_overview/general_threading_rules.md) section to learn more about synchronization issues and changes safety on the IntelliJ Platform. +See the [Threading Issues](general_threading_rules.md) section to learn more about synchronization issues and changes safety on the IntelliJ Platform. This example changes the document within a [`WriteCommandAction`](upsource:///platform/core-api/src/com/intellij/openapi/command/WriteCommandAction.java). The complete `EditorIllustrationAction.actionPerformed()` method is shown below: @@ -148,4 +142,4 @@ public class EditorIllustrationAction extends AnAction { primaryCaret.removeSelection(); } } -``` +``` \ No newline at end of file diff --git a/tutorials/framework.md b/topics/tutorials/framework.md similarity index 94% rename from tutorials/framework.md rename to topics/tutorials/framework.md index b95f544cc..863bbbb95 100644 --- a/tutorials/framework.md +++ b/topics/tutorials/framework.md @@ -1,12 +1,11 @@ ---- -title: Supporting Frameworks ---- +[//]: # (title: Supporting Frameworks) + The following tutorial shows how to support a custom framework type for a project and make this framework type embedded in a project wizard as a UI component. The examples in this tutorial rely heavily on the [framework_basics](https://github.com/JetBrains/intellij-sdk-code-samples/tree/master/framework_basics) code sample. -## 1. Creating a New Framework +## Creating a New Framework In oder to make a custom framework available and configurable for a project the [`FrameworkTypeEx`](upsource:///java/idea-ui/src/com/intellij/framework/FrameworkTypeEx.java) class needs to be extended, in this example to make the [DemoFramework](https://github.com/JetBrains/intellij-sdk-code-samples/blob/master/framework_basics/src/main/java/org/intellij/sdk/framework/DemoFramework.java) class. ```java @@ -14,7 +13,7 @@ public class DemoFramework extends FrameworkTypeEx { } ``` -## 2. Registering Framework +## Registering Framework The newly created framework class should be registered as an extension point by adding `com.intellij.framework.type` extension in [`plugin.xml`](https://github.com/JetBrains/intellij-sdk-code-samples/blob/master/framework_basics/src/main/resources/META-INF/plugin.xml) configuration file: ```xml @@ -23,7 +22,7 @@ The newly created framework class should be registered as an extension point by ``` -## 3. Setting up Mandatory Attributes +## Setting up Mandatory Attributes The framework component should have a unique name passed as a string literal to the constructor. It is best if this is the FQN name of the class: @@ -54,7 +53,7 @@ public class DemoFramework extends FrameworkTypeEx { } ``` -## 4. Creating Provider for Enabling Framework Support +## Creating Provider for Enabling Framework Support To make the framework set up available while executing the steps to create a project, the `DemoFramework.createProvider()` method must be implemented to return an object of type [`FrameworkSupportInModuleConfigurable`](upsource:///java/idea-ui/src/com/intellij/framework/addSupport/FrameworkSupportInModuleConfigurable.java), which adds the framework to a module. In this example the framework is added to any [`ModuleType`](upsource:///platform/lang-api/src/com/intellij/openapi/module/ModuleType.java) without checking, which is usually not the case. @@ -98,4 +97,4 @@ public FrameworkSupportInModuleProvider createProvider() { After compiling and running the code sample above an extra option for configuring the newly created Demo custom framework should be available in the Project Wizard: -![Custom Framework Support](framework/img/custom_framework.png) +![Custom Framework Support](custom_framework.png) \ No newline at end of file diff --git a/tutorials/github_template.md b/topics/tutorials/github_template.md similarity index 90% rename from tutorials/github_template.md rename to topics/tutorials/github_template.md index ffab31697..d1d92a3cd 100644 --- a/tutorials/github_template.md +++ b/topics/tutorials/github_template.md @@ -1,9 +1,8 @@ ---- -title: IntelliJ Platform Plugin Template ---- +[//]: # (title: IntelliJ Platform Plugin Template) + -[**IntelliJ Platform Plugin Template**][gh:ippt] is a repository that provides a pure boilerplate template to make it easier to create a new plugin project using the recommended [Gradle setup](/tutorials/build_system.md). +[**IntelliJ Platform Plugin Template**][gh:ippt] is a repository that provides a pure boilerplate template to make it easier to create a new plugin project using the recommended [Gradle setup](gradle_build_system.md). The main goal of this template is to speed up the setup phase of plugin development for both new and experienced developers by preconfiguring the project scaffold and CI, linking to the proper documentation pages, and keeping everything organized. @@ -16,4 +15,4 @@ Once this is complete, the project is ready to be cloned to your local environme For more details, please refer to the [IntelliJ Platform Plugin Template][gh:ippt] project documentation. [gh:ippt]: https://github.com/JetBrains/intellij-platform-plugin-template -[jb:download-ij]: https://www.jetbrains.com/idea/download +[jb:download-ij]: https://www.jetbrains.com/idea/download \ No newline at end of file diff --git a/topics/tutorials/gradle_build_system.md b/topics/tutorials/gradle_build_system.md new file mode 100644 index 000000000..72343830b --- /dev/null +++ b/topics/tutorials/gradle_build_system.md @@ -0,0 +1,32 @@ +[//]: # (title: Building Plugins with Gradle) + + + +The [gradle-intellij-plugin](https://github.com/JetBrains/gradle-intellij-plugin) Gradle plugin is the recommended solution for building IntelliJ plugins. +The plugin takes care of the dependencies of your plugin project - both the base IDE and other plugin dependencies. + + > [IntelliJ Platform Plugin Template](https://github.com/JetBrains/intellij-platform-plugin-template) makes it easier to create and maintain your IDE plugins, having the Gradle plugin already integrated and CI covered with GitHub Actions. + > + {type="tip"} + + > If a new plugin will be Scala-based, a dedicated SBT plugin [sbt-idea-plugin](https://github.com/JetBrains/sbt-idea-plugin) is available. + > + {type="note"} + +The gradle-intellij-plugin provides tasks to run the IDE with your plugin and to publish your plugin to the [JetBrains Plugins Repository](https://plugins.jetbrains.com). +To make sure that your plugin is not affected by [API changes](api_changes_list.md), which may happen between major releases of the platform, you can quickly build your plugin against many versions of the base IDE. + + > When adding additional repositories to your Gradle build script, always use HTTPS protocol. + > + {type="warning"} + + > Please make sure to always upgrade to the latest version of `gradle-intellij-plugin`. +Follow releases on [GitHub](https://github.com/JetBrains/gradle-intellij-plugin/releases). + > + {type="note"} + +Below are a series of guides to developing and deploying Gradle-based IntelliJ Platform Plugins: + +* [Getting Started with Gradle](gradle_prerequisites.md) +* [Configuring Gradle Projects](gradle_guide.md) +* [Publishing Plugins with Gradle](deployment.md) \ No newline at end of file diff --git a/tutorials/project_wizard.md b/topics/tutorials/intro_project_wizard.md similarity index 72% rename from tutorials/project_wizard.md rename to topics/tutorials/intro_project_wizard.md index b9778ea71..4d4285538 100644 --- a/tutorials/project_wizard.md +++ b/topics/tutorials/intro_project_wizard.md @@ -1,17 +1,16 @@ ---- -title: Project Wizard ---- +[//]: # (title: Project Wizard) + This set of tutorials shows how to manipulate the process of project creation. Configuring Project Wizard automatically allows you to do the following: -1. [Adding New Steps to Project Wizard](project_wizard/adding_new_steps.md) -2. [Supporting Module Types](project_wizard/module_types.md) +1. [Adding New Steps to Project Wizard](adding_new_steps.md) +2. [Supporting Module Types](module_types.md) 3. Handling activities during project creation 4. Initial environment configuration **Note:** Main utilities to configure a custom project wizard can be found in the package -[lang-api.ide.util.projectWizard](upsource:///platform/lang-api/src/com/intellij/ide/util/projectWizard). +[lang-api.ide.util.projectWizard](upsource:///platform/lang-api/src/com/intellij/ide/util/projectWizard). \ No newline at end of file diff --git a/tutorials/kotlin.md b/topics/tutorials/kotlin.md similarity index 87% rename from tutorials/kotlin.md rename to topics/tutorials/kotlin.md index 26b10cc6f..122ada27f 100644 --- a/tutorials/kotlin.md +++ b/topics/tutorials/kotlin.md @@ -1,9 +1,8 @@ ---- -title: Kotlin for Plugin Developers ---- +[//]: # (title: Kotlin for Plugin Developers) + -## 1. Why Kotlin? +## Why Kotlin? Using Kotlin to write plugins for the IntelliJ Platform is very similar to writing plugins in Java. Existing plugin developers can get started by converting boilerplate Java classes to their Kotlin equivalents by using the [J2K compiler](https://kotlinlang.org/docs/tutorials/mixing-java-kotlin-intellij.html#converting-an-existing-java-file-to-kotlin-with-j2k) bundled with the IntelliJ Platform (versions 143.+), and developers can easily mix and match Kotlin classes with their existing Java code. @@ -34,17 +33,19 @@ Now we can directly write `logger.debug { "..." }` to receive all the benefits o With practice, you will be able to recognize many idioms in the IntelliJ Platform that can be simplified with Kotlin. To learn more about building IntelliJ Platform plugins with Kotlin, this tutorial will help you get started. -## 2. Adding Kotlin Support +## Adding Kotlin Support -> **TIP** The [GitHub Template](/tutorials/github_template.md) provides a preconfigured project using Kotlin. + > The [GitHub Template](github_template.md) provides a preconfigured project using Kotlin. + > + {type="tip"} Plugins targeting the IntelliJ Platform versions 143 and above are easy to migrate: just start writing Kotlin. The IDE already bundles the necessary Kotlin plugins and libraries, requiring no further configuration. For detailed instructions, please refer to the [Kotlin documentation](https://kotlinlang.org/docs/tutorials/getting-started.html). -## 3. Kotlin Gradle Plugin +## Kotlin Gradle Plugin -For plugins already using the [Gradle Build System](build_system.md), or those that require precise control over the Kotlin build process, we recommend using the [kotlin-gradle-plugin](https://kotlinlang.org/docs/reference/using-gradle.html#configuring-dependencies). +For plugins already using the [Gradle Build System](gradle_build_system.md), or those that require precise control over the Kotlin build process, we recommend using the [kotlin-gradle-plugin](https://kotlinlang.org/docs/reference/using-gradle.html#configuring-dependencies). This [Gradle plugin](https://mvnrepository.com/artifact/org.jetbrains.kotlin/kotlin-gradle-plugin-core) greatly simplifies building Kotlin projects in a controlled and reproducible manner. Your `build.gradle` file may look like so: @@ -87,7 +88,7 @@ intellij { } ``` -### 3.1. Use Kotlin to Write Gradle Script +### Use Kotlin to Write Gradle Script Starting with 4.4, Gradle supports `build.gradle.kts`, an alternative to `build.gradle` written in Kotlin. @@ -136,23 +137,23 @@ intellij { } ``` -## 4. UI in Kotlin +## UI in Kotlin -The best way to create user interfaces with Kotlin is to use a [type safe DSL](/user_interface_components/kotlin_ui_dsl.md) for building forms. +The best way to create user interfaces with Kotlin is to use a [type safe DSL](kotlin_ui_dsl.md) for building forms. Using a GUI designer with Kotlin is currently [not supported](https://youtrack.jetbrains.com/issue/KT-6660). -## 5. Handling Kotlin Code +## Handling Kotlin Code If a plugin processes Kotlin code (e.g., providing inspections), it needs to add a dependency on the Kotlin plugin (Plugin ID `org.jetbrains.kotlin`) itself. -Please refer to [Plugin Dependencies](/basics/plugin_structure/plugin_dependencies.md) for more information. +Please refer to [Plugin Dependencies](plugin_dependencies.md) for more information. -## 6. Caution +## Caution -Plugins *must* use Kotlin classes to implement declarations in the [plugin configuration file](/basics/plugin_structure/plugin_configuration_file.md). +Plugins *must* use Kotlin classes to implement declarations in the [plugin configuration file](plugin_configuration_file.md). When registering an extension, the platform uses a dependency injection framework to instantiate these classes. For this reason, plugins *must not* use [Kotlin objects](https://kotlinlang.org/docs/reference/object-declarations.html) to implement any `plugin.xml` declarations. -## 7. Examples +## Examples There are many [open-source Kotlin projects](https://github.com/search?l=Kotlin&q=+intellij&ref=searchresults&type=Repositories) built on the IntelliJ Platform. For a readily available source of up to date examples and applications of the Kotlin language for building developer tools with the IntelliJ Platform, developers may look to these projects for inspiration: @@ -161,4 +162,4 @@ For a readily available source of up to date examples and applications of the Ko * [Rust](https://github.com/intellij-rust/intellij-rust) * [HashiCorp Terraform / HCL language support](https://github.com/VladRassokhin/intellij-hcl) * [TeXiFy IDEA](https://github.com/Hannah-Sten/TeXiFy-IDEA) -* [Makefile support](https://github.com/kropp/intellij-makefile) +* [Makefile support](https://github.com/kropp/intellij-makefile) \ No newline at end of file diff --git a/tutorials/live_templates.md b/topics/tutorials/live_templates.md similarity index 85% rename from tutorials/live_templates.md rename to topics/tutorials/live_templates.md index ac2b98cf2..b250058b0 100644 --- a/tutorials/live_templates.md +++ b/topics/tutorials/live_templates.md @@ -1,6 +1,5 @@ ---- -title: Live Templates ---- +[//]: # (title: Live Templates) + *Live Templates* are customizable rules that allow developers to abbreviate repetitive patterns of text in the editor. @@ -20,6 +19,6 @@ As the user completes each section of the `for` loop and presses `Tab`, the curs For more information about creating Custom Live Templates, refer to the [corresponding documentation](https://www.jetbrains.com/idea/help/creating-and-editing-live-templates.html). These sections describe how to add Live Templates, and their associated building blocks, to plugins. - * [Adding Live Templates to a Plugin](live_templates/template_support.md) - * [Creating New Functions for Live Templates](live_templates/new_macros.md) - * Surround Templates + * [Adding Live Templates to a Plugin](template_support.md) + * [Creating New Functions for Live Templates](new_macros.md) + * Surround Templates \ No newline at end of file diff --git a/tutorials/live_templates/new_macros.md b/topics/tutorials/live_templates/new_macros.md similarity index 92% rename from tutorials/live_templates/new_macros.md rename to topics/tutorials/live_templates/new_macros.md index f875cdee6..a466112e7 100644 --- a/tutorials/live_templates/new_macros.md +++ b/topics/tutorials/live_templates/new_macros.md @@ -1,6 +1,5 @@ ---- -title: Creating New Functions for Live Templates ---- +[//]: # (title: Creating New Functions for Live Templates) + The [Predefined Functions](https://www.jetbrains.com/help/idea/template-variables.html?s=quick#predefined_functions) are the building blocks for creating [Parameterized Templates and Surround Templates](https://www.jetbrains.com/help/idea/using-live-templates.html?s=quick#live_templates_types). @@ -10,9 +9,6 @@ This tutorial illustrates how to add custom functions to an IntelliJ Platform pl As an example, a function is created to convert a selection to Title Case. Refer to the SDK code sample [`live_templates`](https://github.com/JetBrains/intellij-sdk-code-samples/tree/master/live_templates). -* bullet -{:toc} - ## Implementing a New Function Under the hood, the predefined functions for Live Templates are called _macros_. A new custom function for Live Templates is implemented in `TitleCaseMacro`, which extends [`MacroBase`](upsource:///platform/lang-impl/src/com/intellij/codeInsight/template/macro/MacroBase.java). @@ -24,8 +20,8 @@ Three `TitleCaseMacro` methods are of particular interest: The text to be capitalized is retrieved from the Live Template and converted to Title Case. ```java -{% include /code_samples/live_templates/src/main/java/org/intellij/sdk/liveTemplates/TitleCaseMacro.java%} ``` +{src="live_templates/src/main/java/org/intellij/sdk/liveTemplates/TitleCaseMacro.java"} ## Adding a Live Template Using the procedures previously discussed for [Template Creation](template_support.md#template-creation) and [Export the Live Template](template_support.md#export-the-live-template), add a Live Template to the [Markdown.xml](https://github.com/JetBrains/intellij-sdk-code-samples/tree/master/live_templates/src/main/resources/liveTemplates) file for the plugin. @@ -64,9 +60,9 @@ Now verify the plugin is working correctly. * Highlight the text and enter ⌥⌘J to open the Select Template popup. Confirm that the _SDK: Convert to title case_ is available in the popup, and select it. -![Convert to title case](img/invoke_titleCase.png){:width="700px"} +![Convert to title case](invoke_titleCase.png){width="700"} Test that the Live Template works by entering m or return. The text will change to have each word capitalized: -![Converted to title case](img/applied_titleCase.png){:width="700px"} +![Converted to title case](applied_titleCase.png){width="700"} \ No newline at end of file diff --git a/tutorials/live_templates/template_support.md b/topics/tutorials/live_templates/template_support.md similarity index 92% rename from tutorials/live_templates/template_support.md rename to topics/tutorials/live_templates/template_support.md index f815a8150..773085a4b 100644 --- a/tutorials/live_templates/template_support.md +++ b/topics/tutorials/live_templates/template_support.md @@ -1,6 +1,5 @@ ---- -title: Adding Live Templates to a Plugin ---- +[//]: # (title: Adding Live Templates to a Plugin) + This tutorial illustrates how to add default Custom Live Templates to an IntelliJ Platform plugin, and assign valid contexts for these templates based on the surrounding code and file type. @@ -9,9 +8,6 @@ Any Live Template that can be created and exported can be added to a plugin by f This tutorial uses the SDK code sample [`live_templates`](https://github.com/JetBrains/intellij-sdk-code-samples/tree/master/live_templates). -* bullet -{:toc} - ## Template Creation Get started by [creating a new Live Template](https://www.jetbrains.com/idea/help/creating-and-editing-live-templates.html) within the IntelliJ Platform-based IDE: * Add a new Template Group, "Markdown" and create a new Live Template under this group. @@ -28,7 +24,9 @@ In the *Edit variables* dialog, set the `Expression` for the `LINK` to `complete There are many other [predefined functions](https://www.jetbrains.com/idea/help/creating-and-editing-template-variables.html) that developers should become familiar with before implementing any unique functionality in a plugin. -> **TIP** Consider iteratively testing the Live Template using the current editor and a markdown file to minimize debugging later. + > Consider iteratively testing the Live Template using the current editor and a markdown file to minimize debugging later. + > + {type="tip"} ## Export the Live Template Once the Live Template produces the expected result, [export the Live Template](https://www.jetbrains.com/help/idea/sharing-live-templates.html). @@ -58,10 +56,12 @@ The `MarkdownContext` class defines it for Markdown files. Ultimately, a file's extension determines the applicable Markdown context. ```java -{% include /code_samples/live_templates/src/main/java/org/intellij/sdk/liveTemplates/MarkdownContext.java%} ``` +{src="live_templates/src/main/java/org/intellij/sdk/liveTemplates/MarkdownContext.java"} -> **NOTE** Once the `MarkdownContext` is defined, be sure to add the new context type to the previously created Live Template settings file. + > Once the `MarkdownContext` is defined, be sure to add the new context type to the previously created Live Template settings file. + > + {type="note"} Within the `` elements in the `Markdown.xml` [Live Template definition file](#export-the-live-template), add the following context elements: @@ -123,7 +123,7 @@ public class MarkdownTemplateProvider implements DefaultLiveTemplatesProvider { } ``` -#### Register Extension Points +#### Register DefaultLiveTemplatesProvider Extension Point Using the `com.intellij.defaultLiveTemplatesProvider` and `com.intellij.liveTemplateContext` extension points, register the implementations with the IntelliJ Platform. ```xml @@ -137,4 +137,4 @@ Using the `com.intellij.defaultLiveTemplatesProvider` and `com.intellij.liveTemp Now verify the plugin is working correctly. Run the plugin in a Development Instance and verify there is a new entry under **Settings/Preferenes \| Live Templates \| Markdown \| \{ (SDK: New link reference)**. -Finally, create a new file `test.md` and confirm that the Live Template works by entering a { character and then pressing Tab. +Finally, create a new file `test.md` and confirm that the Live Template works by entering a { character and then pressing Tab. \ No newline at end of file diff --git a/tutorials/project_wizard/adding_new_steps.md b/topics/tutorials/project_wizard/adding_new_steps.md similarity index 85% rename from tutorials/project_wizard/adding_new_steps.md rename to topics/tutorials/project_wizard/adding_new_steps.md index eec48a53e..84c480731 100644 --- a/tutorials/project_wizard/adding_new_steps.md +++ b/topics/tutorials/project_wizard/adding_new_steps.md @@ -1,6 +1,5 @@ ---- -title: Adding New Steps to Project Wizard ---- +[//]: # (title: Adding New Steps to Project Wizard) + This tutorial shows how to add an extra step to the Project Wizard to provide additional project configuration settings. @@ -8,9 +7,9 @@ This tutorial shows how to add an extra step to the Project Wizard to provide ad ## Pre-Requirements Create an empty plugin project. -See [Creating a Plugin Project](/tutorials/build_system.md) to know how to do it. +See [Creating a Plugin Project](gradle_build_system.md) to know how to do it. -## 1. Register Module Builder +## Register Module Builder Project configuration settings depend on the project's module type. Register a new `com.intellij.moduleBuilder` extension point in the `plugin.xml` configuration file. @@ -22,7 +21,7 @@ Register a new `com.intellij.moduleBuilder` extension point in the `plugin.xml` ``` -## 2. Create a Custom Module Builder +## Create a Custom Module Builder Extend [`ModuleBuilder`](upsource:///platform/lang-api/src/com/intellij/ide/util/projectWizard/ModuleBuilder.java) class to provide custom configuration. @@ -34,7 +33,7 @@ public class DemoModuleWizardStep extends ModuleBuilder { } ``` -## 3. Define Module Type +## Define Module Type Set a module type for the extra wizard step to provide. In this example, choose an `EMPTY` module type. @@ -50,11 +49,10 @@ public class DemoModuleWizardStep extends ModuleBuilder { } ``` -## 4. Design and Implement Wizard Steps +## Design and Implement Wizard Steps Provide an implementation of a custom UI component to be added to the Wizard. In this case, leave it as a label. - ```java public class DemoModuleWizardStep extends ModuleBuilder { public void setupRootModel(ModifiableRootModel modifiableRootModel) throws ConfigurationException { @@ -82,13 +80,13 @@ public class DemoModuleWizardStep extends ModuleBuilder { } ``` -## 5. Checking UI Appearance +## Checking UI Appearance After compiling and running the plugin, create a new project using a source-compiled instance of *IntelliJ IDEA*. -![New Project](img/empty_project.png) +![New Project](empty_project.png) Choose an *Empty Module* type, click next, and get to the just added extra step. -![Extra Step](img/extra_step.png) +![Extra Step](extra_step.png) -Modify and tune the UI component depending on requirements. +Modify and tune the UI component depending on requirements. \ No newline at end of file diff --git a/tutorials/project_wizard/module_types.md b/topics/tutorials/project_wizard/module_types.md similarity index 68% rename from tutorials/project_wizard/module_types.md rename to topics/tutorials/project_wizard/module_types.md index 3d6c8ce8f..bc121e9da 100644 --- a/tutorials/project_wizard/module_types.md +++ b/topics/tutorials/project_wizard/module_types.md @@ -1,6 +1,5 @@ ---- -title: Supporting Module Types ---- +[//]: # (title: Supporting Module Types) + *IntelliJ Platform* provides a set of standard module types. @@ -9,11 +8,13 @@ This tutorial shows how to register a new module type and link it to the project ## Pre-Requirements -Create an empty plugin project, see [Creating a Plugin Project](/tutorials/build_system.md). +Create an empty plugin project, see [Creating a Plugin Project](gradle_build_system.md). -> **NOTE** The UI for selecting module types and the creation of modules through project wizard is IntelliJ IDEA-specific. + > The UI for selecting module types and the creation of modules through project wizard is IntelliJ IDEA-specific. + > + {type="note"} -## 1. Register a New Module Type +## Register a New Module Type Add a new `com.intellij.moduleType` implementation with the IntelliJ Platform in the `plugin.xml` configuration file. ```xml @@ -22,31 +23,31 @@ Add a new `com.intellij.moduleType` implementation with the IntelliJ Platform in ``` -## 2. Implement ModuleType Interface +## Implement ModuleType Interface Create the `DemoModuleType` implementation based on [`ModuleType`](upsource:///platform/lang-api/src/com/intellij/openapi/module/ModuleType.java). ```java -{% include /code_samples/module/src/main/java/org/intellij/sdk/module/DemoModuleType.java %} ``` +{src="module/src/main/java/org/intellij/sdk/module/DemoModuleType.java"} -## 3. Implement Custom Module Builder +## Implement Custom Module Builder Create `DemoModuleBuilder` based on [`ModuleBuilder`](upsource:///platform/lang-api/src/com/intellij/ide/util/projectWizard/ModuleBuilder.java). ```java -{% include /code_samples/module/src/main/java/org/intellij/sdk/module/DemoModuleBuilder.java %} ``` +{src="module/src/main/java/org/intellij/sdk/module/DemoModuleBuilder.java"} -## 4. Provide Custom Wizard Steps +## Provide Custom Wizard Steps Provide a straightforward implementation of UI components for the project creating stage. Create a generic `DemoModuleWizardStep` based on [ModuleWizardStep](upsource:///platform/lang-api/src/com/intellij/ide/util/projectWizard/ModuleWizardStep.java) ```java -{% include /code_samples/module/src/main/java/org/intellij/sdk/module/DemoModuleWizardStep.java %} ``` +{src="module/src/main/java/org/intellij/sdk/module/DemoModuleWizardStep.java"} -## 5. Creating a Module of New Type +## Creating a Module of New Type After compiling and running the plugin in a development instance, create a new project. Select **File \| New \| Module...** A new module type and its settings panel are available in the Project Wizard. -![New Module Type](module_types/img/new_module_type.png){:width="800px"} +![New Module Type](new_module_type.png){width="800"} \ No newline at end of file diff --git a/tutorials/run_configurations.md b/topics/tutorials/run_configurations.md similarity index 89% rename from tutorials/run_configurations.md rename to topics/tutorials/run_configurations.md index 3c1329b7d..69f46ad9e 100644 --- a/tutorials/run_configurations.md +++ b/topics/tutorials/run_configurations.md @@ -1,6 +1,5 @@ ---- -title: Run Configurations ---- +[//]: # (title: Run Configurations) + These series of steps show how to register and implement a simple Run Configuration. @@ -9,9 +8,9 @@ To get familiar with the concept of a Run Configuration refer [Run/Debug Configu ## Pre-Requirements -Create an empty plugin project as described in [Creating a Plugin Project](/basics/getting_started.md). +Create an empty plugin project as described in [Creating a Plugin Project](getting_started.md). -## 1. Register a New ConfigurationType +## Register a New ConfigurationType Add new `configurationType` extension to the [plugin.xml](https://github.com/JetBrains/intellij-sdk-code-samples/blob/master/run_configuration/src/main/resources/META-INF/plugin.xml) @@ -21,7 +20,7 @@ Add new `configurationType` extension to the [plugin.xml](https://github.com/Jet ``` -## 2. Implement ConfigurationType +## Implement ConfigurationType Implement [`ConfigurationType`](upsource:///platform/lang-api/src/com/intellij/execution/configurations/ConfigurationType.java) interface registered in the Step 1. @@ -55,7 +54,7 @@ public class DemoRunConfigurationType implements ConfigurationType { } ``` -## 3. Implement a ConfigurationFactory +## Implement a ConfigurationFactory Implement a new [`ConfigurationFactory`](upsource:///platform/lang-api/src/com/intellij/execution/configurations/ConfigurationFactory.java) through which custom run configurations will be created. @@ -80,7 +79,7 @@ public class DemoConfigurationFactory extends ConfigurationFactory { ``` -## 4. Implement a Run Configuration +## Implement a Run Configuration To make your changes visible from the UI, implement a new Run Configuration. @@ -112,7 +111,7 @@ public class DemoRunConfiguration extends RunConfigurationBase { } ``` -## 5. Create and Implement Run Configuration UI Form +## Create and Implement Run Configuration UI Form Make sure _UI Designer_ plugin is [enabled](https://www.jetbrains.com/help/idea/managing-plugins.html). @@ -120,9 +119,9 @@ Create a new [UI form](https://www.jetbrains.com/help/idea/designing-gui-major- Default Run Configuration will be looking like this: -![Default Run Configuration Look](run_configurations/img/ui_form.png) +![Default Run Configuration Look](ui_form.png) -## 6. Bind the UI Form +## Bind the UI Form The UI Form should be bound with a Java class responsible for handling UI components logic. @@ -154,10 +153,10 @@ public class DemoSettingsEditor extends SettingsEditor { } ``` -## 7. Compile and Run the Plugin +## Compile and Run the Plugin -Refer to [Running and Debugging a Plugin](/basics/getting_started/running_and_debugging_a_plugin.md). +Refer to [Running and Debugging a Plugin](running_and_debugging_a_plugin.md). After going through the steps described above you can create a custom Run Configuration from your plugin. -![New Run Configuration Type](run_configurations/img/new_run_configuration.png) +![New Run Configuration Type](new_run_configuration.png) \ No newline at end of file diff --git a/tutorials/settings_tutorial.md b/topics/tutorials/settings_tutorial.md similarity index 74% rename from tutorials/settings_tutorial.md rename to topics/tutorials/settings_tutorial.md index cef2b5060..babaf7d6a 100644 --- a/tutorials/settings_tutorial.md +++ b/topics/tutorials/settings_tutorial.md @@ -1,16 +1,12 @@ ---- -title: Settings Tutorial ---- +[//]: # (title: Settings Tutorial) + ## Introduction -As discussed in the [_Settings_ Guide](/reference_guide/settings_guide.md), plugins can add Settings to IntelliJ Platform-based IDEs. +As discussed in the [_Settings_ Guide](settings_guide.md), plugins can add Settings to IntelliJ Platform-based IDEs. The IDE displays the Settings in response to a user choosing **Settings/Preferences**. Custom Settings are displayed and function just like those native to the IDE. -* bullet list -{:toc} - ## Overview of a Custom Settings Implementation Using the SDK code sample [`settings`](https://github.com/JetBrains/intellij-sdk-code-samples/tree/master/settings), this tutorial illustrates the steps to create custom Application-level Settings. Many IntelliJ Platform Settings implementations use fewer classes, but the `settings` code sample factors the functionality into three classes for clarity: @@ -18,14 +14,14 @@ Many IntelliJ Platform Settings implementations use fewer classes, but the `sett * The [`AppSettingsState`](https://github.com/JetBrains/intellij-sdk-code-samples/blob/master/settings/src/main/java/org/intellij/sdk/settings/AppSettingsState.java) is like a Model because it stores the Settings persistently, * The [`AppSettingsComponent`](https://github.com/JetBrains/intellij-sdk-code-samples/blob/master/settings/src/main/java/org/intellij/sdk/settings/AppSettingsComponent.java) is similar to a View because it displays and captures edits to the values of the Settings. -The structure of the implementation is the same for Project Settings, but there are minor differences in the [`Configurable` implementation](/reference_guide/settings_guide.md#constructors) and [Extension Point (EP) declaration](/reference_guide/settings_guide.md#declaring-project-settings). +The structure of the implementation is the same for Project Settings, but there are minor differences in the [`Configurable` implementation](settings_guide.md#constructors) and [Extension Point (EP) declaration](settings_guide.md#declaring-project-settings). ## The AppSettingsState Class The `AppSettingsState` class persistently stores the custom Settings. -It is based on the [IntelliJ Platform Persistence Model](/basics/persisting_state_of_components.md#using-persistentstatecomponent). +It is based on the [IntelliJ Platform Persistence Model](persisting_state_of_components.md#using-persistentstatecomponent). ### Declaring AppSettingsState -Given a [Light Service](/basics/plugin_structure/plugin_services.md#light-services) is not used, the persistent data class must be declared as a [Service](/basics/plugin_structure/plugin_services.md#declaring-a-service) EP in the `plugin.xml` file. +Given a [Light Service](plugin_services.md#light-services) is not used, the persistent data class must be declared as a [Service](plugin_services.md#declaring-a-service) EP in the `plugin.xml` file. If these were Project Settings, the `com.intellij.projectService` EP would be used. However, because these are Application Settings, the `com.intellij.applicationService` EP is used with the FQN of the implementation class: @@ -36,14 +32,14 @@ However, because these are Application Settings, the `com.intellij.applicationSe ``` ### Creating the AppSettingState Implementation -As discussed in [Implementing the PersistentStateComponent Interface](/basics/persisting_state_of_components.md#implementing-the-persistentstatecomponent-interface), `AppSettingsState` uses the pattern of implementing [`PersistentStateComponent`](upsource:///platform/projectModel-api/src/com/intellij/openapi/components/PersistentStateComponent.java) itself: +As discussed in [Implementing the PersistentStateComponent Interface](persisting_state_of_components.md#implementing-the-persistentstatecomponent-interface), `AppSettingsState` uses the pattern of implementing [`PersistentStateComponent`](upsource:///platform/projectModel-api/src/com/intellij/openapi/components/PersistentStateComponent.java) itself: ```java -{% include /code_samples/settings/src/main/java/org/intellij/sdk/settings/AppSettingsState.java %} ``` +{src="settings/src/main/java/org/intellij/sdk/settings/AppSettingsState.java"} #### Storage Annotation -The [`@State`](upsource:///platform/projectModel-api/src/com/intellij/openapi/components/State.java) annotation, located just above the class declaration, [defines the data storage location](/basics/persisting_state_of_components.md#defining-the-storage-location). +The [`@State`](upsource:///platform/projectModel-api/src/com/intellij/openapi/components/State.java) annotation, located just above the class declaration, [defines the data storage location](persisting_state_of_components.md#defining-the-storage-location). For `AppSettingsState`, the data `name` parameter is the FQN of the class. Using FQN is a best practice to follow, and is required if custom data gets stored in the standard project or workspace files. @@ -53,7 +49,7 @@ In this case, the file is located in the `options` directory of the [configurati #### Persistent Data Fields The `AppSettingState` implementation has two public fields: a `String` and a `boolean`. Conceptually these fields hold the name of a user, and whether that person is an IntelliJ IDEA user, respectively. -See [Implementing the State Class](/basics/persisting_state_of_components.md#implementing-the-state-class) for more information about how `PersistentStateComponent` serializes public fields. +See [Implementing the State Class](persisting_state_of_components.md#implementing-the-state-class) for more information about how `PersistentStateComponent` serializes public fields. #### AppSettingState Methods The fields are so limited and straightforward for this class that encapsulation is not used for simplicity. @@ -71,20 +67,19 @@ The `AppSettingsComponent` is instantiated by `AppSettingsConfigurable`. The `AppSettingsComponent` defines a `JPanel` containing a [`JBTextField`](upsource:///platform/platform-api/src/com/intellij/ui/components/JBTextField.java) and a [`JBCheckBox`](upsource:///platform/platform-api/src/com/intellij/ui/components/JBCheckBox.java) to hold and display the data that maps to the [data fields](#persistent-data-fields) of `AppSettingsState`: ```java -{% include /code_samples/settings/src/main/java/org/intellij/sdk/settings/AppSettingsComponent.java %} ``` +{src="settings/src/main/java/org/intellij/sdk/settings/AppSettingsComponent.java"} #### AppSettingsComponent Methods The constructor builds the `JPanel` using the convenient [`FormBuilder`](upsource:///platform/platform-api/src/com/intellij/util/ui/FormBuilder.java), and saves a reference to the `JPanel`. The rest of the class are simple accessors and mutators to encapsulate the UI components used on the `JPanel`. - ## The AppSettingsConfigurable Class The methods of [`AppSettingsConfigurable`](https://github.com/JetBrains/intellij-sdk-code-samples/blob/master/settings/src/main/java/org/intellij/sdk/settings/AppSettingsConfigurable.java) are called by the IntelliJ Platform, and `AppSettingsConfigurable` in turn interacts with `AppSettingsComponent` and `AppSettingState`. ### Declaring the AppSettingsConfigurable -As described in [Declaring Application Settings](/reference_guide/settings_guide.md#declaring-application-settings), the `com.intellij.applicationConfigurable` is used as the EP. -An explanation of this declaration can be found in [Declaring Application Settings](/reference_guide/settings_guide.md#declaring-application-settings): +As described in [Declaring Application Settings](settings_guide.md#declaring-application-settings), the `com.intellij.applicationConfigurable` is used as the EP. +An explanation of this declaration can be found in [Declaring Application Settings](settings_guide.md#declaring-application-settings): ```xml @@ -94,32 +89,31 @@ An explanation of this declaration can be found in [Declaring Application Settin ``` - ### Creating the AppSettingsConfigurable Implementation The `AppSettingsConfigurable` class implements [`Configurable`](upsource:///platform/platform-api/src/com/intellij/openapi/options/Configurable.java) interface. The class has one field to hold a reference to the `AppSettingsComponent`. ```java -{% include /code_samples/settings/src/main/java/org/intellij/sdk/settings/AppSettingsConfigurable.java %} ``` +{src="settings/src/main/java/org/intellij/sdk/settings/AppSettingsConfigurable.java"} #### AppSettingsConfigurable Methods All the methods in this class are overrides of the methods in the `Configurable` interface. Readers are encouraged to review the Javadoc comments for the `Configurable` methods. -Also review notes about [IntelliJ Platform Interactions](/reference_guide/settings_guide.md#intellij-platform-interactions-with-configurable) with `Configurable` methods. +Also review notes about [IntelliJ Platform Interactions](settings_guide.md#intellij-platform-interactions-with-configurable) with `Configurable` methods. ## Testing the Custom Settings Plugin After performing the steps described above, compile and run the plugin in a Development Instance to see the custom Settings available in the Settings Dialog. Open the IDE Settings by selecting **Settings/Preferences \| Tools \| SDK: Application Settings Example**. The settings are preloaded with the default values: -!["Settings Defaults"](img/settings_defaults.png){:width="600px"} +!["Settings Defaults"](settings_defaults.png){width="600"} Now edit the settings values to "John Doe" and click the checkbox. Click on the **OK** button to close the Settings dialog and save the changes. Exit the Development Instance. Open the file `SdkSettingsPlugin.xml` to see the Settings persistently stored. -In this demonstration the file resides in `code_samples/settings/build/idea-sandbox/config/options/`, but see [IDE Development Instances](/basics/ide_development_instance.md) for the general Development Instance case, or [Default IDE directories](https://www.jetbrains.com/help/idea/tuning-the-ide.html#default-dirs) if you are testing the `settings` plugin directly in an IDE. +In this demonstration the file resides in `code_samples/settings/build/idea-sandbox/config/options/`, but see [IDE Development Instances](ide_development_instance.md) for the general Development Instance case, or [Default IDE directories](https://www.jetbrains.com/help/idea/tuning-the-ide.html#default-dirs) if you are testing the `settings` plugin directly in an IDE. -!["Persisted Settings"](img/settings_persisted.png){:width="600px"} +!["Persisted Settings"](settings_persisted.png){width="600"} \ No newline at end of file diff --git a/tutorials/tree_structure_view.md b/topics/tutorials/tree_structure_view.md similarity index 80% rename from tutorials/tree_structure_view.md rename to topics/tutorials/tree_structure_view.md index 32275327e..c8a0cb08a 100644 --- a/tutorials/tree_structure_view.md +++ b/topics/tutorials/tree_structure_view.md @@ -1,6 +1,5 @@ ---- -title: Tree Structure View ---- +[//]: # (title: Tree Structure View) + This tutorial is meant to illustrate how the project tree structure view appearance can be modified programmatically. @@ -11,9 +10,9 @@ Series of step below show how to filter out and keep visible only text files and ## Pre-Requirements Create an empty plugin project. -See [Creating a Plugin Project](/tutorials/build_system/prerequisites.md). +See [Creating a Plugin Project](gradle_prerequisites.md). -## 1. Register Custom TreeStructure Provider +## Register Custom TreeStructure Provider Add new *treeStructureProvider* extension to the [plugin.xml](https://github.com/JetBrains/intellij-sdk-code-samples/blob/master/tree_structure_provider/src/main/resources/META-INF/plugin.xml) @@ -23,7 +22,7 @@ Add new *treeStructureProvider* extension to the [plugin.xml](https://github.com ``` -## 2. Implement Custom TreeStructureProvider +## Implement Custom TreeStructureProvider To provide custom Structure View behaviour you need to implement TreeStructureProvider interface. @@ -43,23 +42,22 @@ public class TextOnlyTreeStructureProvider implements TreeStructureProvider { } ``` -## 3. Override modify() Method +## Override modify() Method To implement Tree Structure nodes filtering logic, override `modify()` method. The example below shows how to filter out all the Project View nodes except those which correspond to text files and directories. ```java -{% include /code_samples/tree_structure_provider/src/main/java/org/intellij/sdk/treeStructureProvider/TextOnlyTreeStructureProvider.java %} ``` +{src="tree_structure_provider/src/main/java/org/intellij/sdk/treeStructureProvider/TextOnlyTreeStructureProvider.java"} -## 4. Compile and Run the Plugin +## Compile and Run the Plugin Compile and run the code sample from this tutorial. -Refer to [Running and Debugging a Plugin](/basics/getting_started/running_and_debugging_a_plugin.md). +Refer to [Running and Debugging a Plugin](running_and_debugging_a_plugin.md). After going through the steps described above you can see only text files and directories belonging to a project in the Project View. -![Text Files](tree_structure_view/img/text_only.png) +![Text Files](text_only.png) - -Check out [plugin source code](https://github.com/JetBrains/intellij-sdk-code-samples/tree/master/tree_structure_provider) and build the project to see how TreeStructureView provider works in practice. +Check out [plugin source code](https://github.com/JetBrains/intellij-sdk-code-samples/tree/master/tree_structure_provider) and build the project to see how TreeStructureView provider works in practice. \ No newline at end of file diff --git a/topics/tutorials/writing_tests_for_plugins.md b/topics/tutorials/writing_tests_for_plugins.md new file mode 100644 index 000000000..1c3203094 --- /dev/null +++ b/topics/tutorials/writing_tests_for_plugins.md @@ -0,0 +1,24 @@ +[//]: # (title: Testing a Custom Language Plugin) + + + + > Please see [Testing Plugins](testing_plugins.md) for a general introduction. + > + {type="note"} + +This tutorial demonstrates how to write and run automated tests for a custom language plugin. + +As an example, the plugin implemented in the [Custom Language Support Tutorial](custom_language_support_tutorial.md) is used to demonstrate functional test development. + +* [1. Tests Prerequisites](tests_prerequisites.md) +* [2. Parsing Test](parsing_test.md) +* [3. Completion Test](completion_test.md) +* [4. Annotator Test](annotator_test.md) +* [5. Formatter Test](formatter_test.md) +* [6. Rename Test](rename_test.md) +* [7. Folding Test](folding_test.md) +* [8. Find Usages Test](find_usages_test.md) +* [9. Commenter Test](commenter_test.md) +* [10. Reference Test](reference_test.md) + +The plugin and test code can be found in the [simple_language_plugin](https://github.com/JetBrains/intellij-sdk-code-samples/tree/master/simple_language_plugin) code sample. \ No newline at end of file diff --git a/tutorials/writing_tests_for_plugins/annotator_test.md b/topics/tutorials/writing_tests_for_plugins/annotator_test.md similarity index 79% rename from tutorials/writing_tests_for_plugins/annotator_test.md rename to topics/tutorials/writing_tests_for_plugins/annotator_test.md index 26f1777f9..388766944 100644 --- a/tutorials/writing_tests_for_plugins/annotator_test.md +++ b/topics/tutorials/writing_tests_for_plugins/annotator_test.md @@ -1,17 +1,16 @@ ---- -title: 4. Annotator Test ---- +[//]: # (title: 4. Annotator Test) + -This test checks if the Simple Language annotator functionality, implemented in the [Annotator](/tutorials/custom_language_support/annotator.md) section of the Custom Language Support Tutorial, works as expected. +This test checks if the Simple Language annotator functionality, implemented in the [Annotator](annotator.md) section of the Custom Language Support Tutorial, works as expected. -## 4.1. Define Input Test Data +## Define Input Test Data The `DefaultTestData.simple` properties file is reused for this test. Create an input test file `AnnotatorTestData.java` in the `testData` directory. This file contains two instances of Simple Language embedded in the Java code. The first instance is a valid use of the `simple:` prefix followed by the Simple Language key `website`. -The second is a valid prefix but an invalid key, as noted by the test `` [highlighting](/basics/testing_plugins/testing_highlighting.md). +The second is a valid prefix but an invalid key, as noted by the test `` [highlighting](testing_highlighting.md). ```java public class Test { @@ -22,7 +21,7 @@ public class Test { } ``` -## 4.2. Define a Test Method +## Define a Test Method Add the `testAnnotator()` method to the `SimpleCodeInsightTest` class [previously defined](completion_test.md#define-a-test). Again, this method configures the test fixture by using the test files. It then calls the `checkHighlighting()` method to verify weak warnings. @@ -34,5 +33,5 @@ public void testAnnotator() { } ``` -## 4.3. Run the Test -[Run](completion_test.md#run-the-test) the test and make sure it's green. +## Run the Test +[Run](completion_test.md#run-the-test) the test and make sure it's green. \ No newline at end of file diff --git a/tutorials/writing_tests_for_plugins/commenter_test.md b/topics/tutorials/writing_tests_for_plugins/commenter_test.md similarity index 85% rename from tutorials/writing_tests_for_plugins/commenter_test.md rename to topics/tutorials/writing_tests_for_plugins/commenter_test.md index 20d02738e..89e63602d 100644 --- a/tutorials/writing_tests_for_plugins/commenter_test.md +++ b/topics/tutorials/writing_tests_for_plugins/commenter_test.md @@ -1,11 +1,10 @@ ---- -title: 9. Commenter Test ---- +[//]: # (title: 9. Commenter Test) + -This test will check if the commenter, implemented in the [Commenter](/tutorials/custom_language_support/commenter.md) section of the Custom Language Support Tutorial, works as expected. +This test will check if the commenter, implemented in the [Commenter](commenter.md) section of the Custom Language Support Tutorial, works as expected. -## 9.1. Define a Test Method +## Define a Test Method Add the `testCommenter()` method to the `SimpleCodeInsightTest` class [previously defined](completion_test.md#define-a-test). This test constructs a Simple Language properties file containing one line, with the virtual caret positioned at the beginning of the line. The test calls the commenter to insert a comment character at the caret, then verifies the results. @@ -22,5 +21,5 @@ It again calls the line comment action to remove the comment character and verif } ``` -## 9.2. Run the Test -[Run](completion_test.md#run-the-test) the test and make sure it's green. +## Run the Test +[Run](completion_test.md#run-the-test) the test and make sure it's green. \ No newline at end of file diff --git a/tutorials/writing_tests_for_plugins/completion_test.md b/topics/tutorials/writing_tests_for_plugins/completion_test.md similarity index 83% rename from tutorials/writing_tests_for_plugins/completion_test.md rename to topics/tutorials/writing_tests_for_plugins/completion_test.md index 5d65df52a..df2002bc8 100644 --- a/tutorials/writing_tests_for_plugins/completion_test.md +++ b/topics/tutorials/writing_tests_for_plugins/completion_test.md @@ -1,25 +1,24 @@ ---- -title: 3. Completion Test ---- +[//]: # (title: 3. Completion Test) + -This test checks if the Simple Language code completion functionality, implemented in the [Reference Contributor](/tutorials/custom_language_support/reference_contributor.md) section of the Custom Language Support Tutorial, works as expected. +This test checks if the Simple Language code completion functionality, implemented in the [Reference Contributor](reference_contributor.md) section of the Custom Language Support Tutorial, works as expected. -## 3.1. Define Test Data +## Define Test Data Create the `DefaultTestData.simple` properties file in the `testData` directory. ```bash -{% include /code_samples/simple_language_plugin/src/test/testData/DefaultTestData.simple %} ``` +{src="simple_language_plugin/src/test/testData/DefaultTestData.simple"} Create a test input Java file `CompleteTestData.java` in the `testData` directory. This file contains a Simple Language snippet within the Java. ```java -{% include /code_samples/simple_language_plugin/src/test/testData/CompleteTestData.java %} ``` +{src="simple_language_plugin/src/test/testData/CompleteTestData.java"} -## 3.2. Define a Test +## Define a Test Subclass [`LightJavaCodeInsightFixtureTestCase`](upsource:///java/testFramework/src/com/intellij/testFramework/fixtures/LightJavaCodeInsightFixtureTestCase.java) to create `SimpleCodeInsightTest`. Override `getTestDataPath()`, and return the path from the root of this plugin module to the `testData` directory. @@ -47,7 +46,7 @@ public class SimpleCodeInsightTest extends LightJavaCodeInsightFixtureTestCase { } ``` -## 3.3. Run the Test +## Run the Test Run the test by: * Opening the **Gradle** Tool Window. * Select the `simple_language_plugin`. @@ -60,4 +59,4 @@ The results are displayed in the **Run** Tool Window, and also written to the `s If the **Run** Tool Window displays the error *Test events were not received*, do the following: * In the **Gradle** Tool Window, drill down under `simple_language_plugin` to *Tasks*, *build*, *clean* task. * Run the *clean* task, which deletes the `simple_language_plugin/build/` directory. -* Retry the test. +* Retry the test. \ No newline at end of file diff --git a/tutorials/writing_tests_for_plugins/find_usages_test.md b/topics/tutorials/writing_tests_for_plugins/find_usages_test.md similarity index 67% rename from tutorials/writing_tests_for_plugins/find_usages_test.md rename to topics/tutorials/writing_tests_for_plugins/find_usages_test.md index dd2d65a09..02fd0aa93 100644 --- a/tutorials/writing_tests_for_plugins/find_usages_test.md +++ b/topics/tutorials/writing_tests_for_plugins/find_usages_test.md @@ -1,24 +1,23 @@ ---- -title: 8. Find Usages Test ---- +[//]: # (title: 8. Find Usages Test) + -This test ensures the find usages provider, implemented in the [Find Usages Provider](/tutorials/custom_language_support/find_usages_provider.md) section of the Custom Language Support Tutorial, works correctly. +This test ensures the find usages provider, implemented in the [Find Usages Provider](find_usages_provider.md) section of the Custom Language Support Tutorial, works correctly. -## 8.1. Define the Test Data +## Define the Test Data Create the `FindUsagesTestData.simple` properties file in the `testData` directory. ```bash -{% include /code_samples/simple_language_plugin/src/test/testData/FindUsagesTestData.simple %} ``` +{src="simple_language_plugin/src/test/testData/FindUsagesTestData.simple"} Create the test file `FindUsagesTestData.java`, which contains one embedded Simple Language prefix and key. ```java -{% include /code_samples/simple_language_plugin/src/test/testData/FindUsagesTestData.java %} ``` +{src="simple_language_plugin/src/test/testData/FindUsagesTestData.java"} -## 8.2. Define a Test Method +## Define a Test Method Add the `testFindUsages()` method to the `SimpleCodeInsightTest` class [previously defined](completion_test.md#define-a-test). This test verifies the find usage functionality will identify the "key with spaces". @@ -29,5 +28,5 @@ This test verifies the find usage functionality will identify the "key with spac } ``` -## 8.3. Run the Test -[Run](completion_test.md#run-the-test) the test and make sure it's green. +## Run the Test +[Run](completion_test.md#run-the-test) the test and make sure it's green. \ No newline at end of file diff --git a/tutorials/writing_tests_for_plugins/folding_test.md b/topics/tutorials/writing_tests_for_plugins/folding_test.md similarity index 56% rename from tutorials/writing_tests_for_plugins/folding_test.md rename to topics/tutorials/writing_tests_for_plugins/folding_test.md index 332a2ffef..608770b06 100644 --- a/tutorials/writing_tests_for_plugins/folding_test.md +++ b/topics/tutorials/writing_tests_for_plugins/folding_test.md @@ -1,21 +1,22 @@ ---- -title: 7. Folding Test ---- +[//]: # (title: 7. Folding Test) + -This test verifies the Simple Language folding builder, implemented in the [Folding Builder](/tutorials/custom_language_support/folding_builder.md) section of the Custom Language Support Tutorial, works as expected. +This test verifies the Simple Language folding builder, implemented in the [Folding Builder](folding_builder.md) section of the Custom Language Support Tutorial, works as expected. -> **NOTE** A folding builder must implement [`DumbAware`](upsource:///platform/core-api/src/com/intellij/openapi/project/DumbAware.java) to pass tests. See [Define a Folding Builder](/tutorials/custom_language_support/folding_builder.md#define-a-folding-builder) for more information. + > A folding builder must implement [`DumbAware`](upsource:///platform/core-api/src/com/intellij/openapi/project/DumbAware.java) to pass tests. See [Define a Folding Builder](folding_builder.md#define-a-folding-builder) for more information. + > + {type="note"} -## 7.1. Define Test Data +## Define Test Data Create a file `FoldingTestData.java` in the `testData` directory. This java file contains markup instructions for three different cases of code folding. ```java -{% include /code_samples/simple_language_plugin/src/test/testData/FoldingTestData.java %} ``` +{src="simple_language_plugin/src/test/testData/FoldingTestData.java"} -## 7.2. Define a Test +## Define a Test Add the `testFolding()` method to the `SimpleCodeInsightTest` class [previously defined](completion_test.md#define-a-test). This test method reuses the `DefaultTestData.simple` properties file. @@ -26,5 +27,5 @@ This test method reuses the `DefaultTestData.simple` properties file. } ``` -## 7.3. Run the Test -[Run](completion_test.md#run-the-test) the test and make sure it's green. +## Run the Test +[Run](completion_test.md#run-the-test) the test and make sure it's green. \ No newline at end of file diff --git a/tutorials/writing_tests_for_plugins/formatter_test.md b/topics/tutorials/writing_tests_for_plugins/formatter_test.md similarity index 74% rename from tutorials/writing_tests_for_plugins/formatter_test.md rename to topics/tutorials/writing_tests_for_plugins/formatter_test.md index 8e9748f53..f693e895b 100644 --- a/tutorials/writing_tests_for_plugins/formatter_test.md +++ b/topics/tutorials/writing_tests_for_plugins/formatter_test.md @@ -1,18 +1,17 @@ ---- -title: 5. Formatter Test ---- +[//]: # (title: 5. Formatter Test) + -This test checks if the Simple Language formatter, implemented in the [Formatter](/tutorials/custom_language_support/formatter.md) section of the Custom Language Support Tutorial, works as expected. +This test checks if the Simple Language formatter, implemented in the [Formatter](formatter.md) section of the Custom Language Support Tutorial, works as expected. -## 5.1. Define Test Data +## Define Test Data Create the `FormatterTestData.simple` properties file in the `testData` directory. ```bash -{% include /code_samples/simple_language_plugin/src/test/testData/FormatterTestData.simple %} ``` +{src="simple_language_plugin/src/test/testData/FormatterTestData.simple"} -## 5.2. Define a Test Method +## Define a Test Method Add the `testFormatter()` method to the `SimpleCodeInsightTest` class [previously defined](completion_test.md#define-a-test). * Again, this method configures the test fixture by using the test file. * The code style Simple Language settings for spaces and blank lines are set. @@ -32,7 +31,7 @@ Add the `testFormatter()` method to the `SimpleCodeInsightTest` class [previousl } ``` -## 5.3. Run the Test +## Run the Test [Run](completion_test.md#run-the-test) the test and make sure it's green. -> **TIP** See also [`FormatterTestCase`](upsource:///platform/testFramework/src/com/intellij/psi/formatter/FormatterTestCase.java) as convenient base class. + > See also [`FormatterTestCase`](upsource:///platform/testFramework/src/com/intellij/psi/formatter/FormatterTestCase.java) as convenient base class. \ No newline at end of file diff --git a/tutorials/writing_tests_for_plugins/parsing_test.md b/topics/tutorials/writing_tests_for_plugins/parsing_test.md similarity index 73% rename from tutorials/writing_tests_for_plugins/parsing_test.md rename to topics/tutorials/writing_tests_for_plugins/parsing_test.md index 72bcf43e8..7d9360b6e 100644 --- a/tutorials/writing_tests_for_plugins/parsing_test.md +++ b/topics/tutorials/writing_tests_for_plugins/parsing_test.md @@ -1,11 +1,10 @@ ---- -title: 2. Parsing Test ---- +[//]: # (title: 2. Parsing Test) + -The first test checks if the Simple Language parser, implemented in the [Lexer and Parser Definition](/tutorials/custom_language_support/lexer_and_parser_definition.md) section of the Custom Language Support Tutorial, works as expected. +The first test checks if the Simple Language parser, implemented in the [Lexer and Parser Definition](lexer_and_parser_definition.md) section of the Custom Language Support Tutorial, works as expected. -## 2.1. Update Grammar and Regenerate the Parser +## Update Grammar and Regenerate the Parser Before creating the parsing test, ensure the parser definition (`Simple.bnf`) includes the lines shown below. These additional lines facilitate testing incorrect keys. @@ -24,38 +23,38 @@ property ::= (KEY? SEPARATOR VALUE?) | KEY { private recover_property ::= !(KEY|SEPARATOR|COMMENT) ``` -## 2.2. Define Input Test Data +## Define Input Test Data Create the *ParsingTestData.simple* properties file in the *testData* folder. Note the last few lines define a purposely incorrect key. ```bash -{% include /code_samples/simple_language_plugin/src/test/testData/ParsingTestData.simple %} ``` +{src="simple_language_plugin/src/test/testData/ParsingTestData.simple"} -## 2.3. Copy the Expected PSI Tree +## Copy the Expected PSI Tree The easiest way to get the expected PSI structure for any file is to use the PSI Viewer. Run the project and use **Tools \| View PSI Structure**. -![PSI Tree Copy](img/plugin_copy_psi.png) +![PSI Tree Copy](plugin_copy_psi.png) Use the `Copy PSI` button to copy the expected PSI structure to the clipboard. -## 2.3. Define the Output Reference Test Data +## Define the Output Reference Test Data Create a file *ParsingTestData.txt* with the copied PSI tree. ```text -{% include /code_samples/simple_language_plugin/src/test/testData/ParsingTestData.txt %} ``` +{src="simple_language_plugin/src/test/testData/ParsingTestData.txt"} -## 2.4. Define a Parsing Test +## Define a Parsing Test Subclass [`ParsingTestCase`](upsource:///platform/testFramework/src/com/intellij/testFramework/ParsingTestCase.java) to create `SimpleParsingTest`: Override `getTestDataPath()`, and return the path from the root of this plugin module to the `testData` directory. ```java -{% include /code_samples/simple_language_plugin/src/test/java/org/intellij/sdk/language/SimpleParsingTest.java %} ``` +{src="simple_language_plugin/src/test/java/org/intellij/sdk/language/SimpleParsingTest.java"} -## 2.5. Run the Test +## Run the Test Run the test by: * Opening the Gradle Tool Window. * Select the `simple_language_plugin`. @@ -63,4 +62,4 @@ Run the test by: * Drill down under `simple_language_plugin` to *Tasks*, *verification*, *test* task. * Run the *test* task. -The results are displayed in the **Run** Window, and also written to the `simple_language_plugin/build/test-results/test/` directory. +The results are displayed in the **Run** Window, and also written to the `simple_language_plugin/build/test-results/test/` directory. \ No newline at end of file diff --git a/tutorials/writing_tests_for_plugins/reference_test.md b/topics/tutorials/writing_tests_for_plugins/reference_test.md similarity index 76% rename from tutorials/writing_tests_for_plugins/reference_test.md rename to topics/tutorials/writing_tests_for_plugins/reference_test.md index 2a0813e06..2fa98ca39 100644 --- a/tutorials/writing_tests_for_plugins/reference_test.md +++ b/topics/tutorials/writing_tests_for_plugins/reference_test.md @@ -1,21 +1,20 @@ ---- -title: 10. Reference Test ---- +[//]: # (title: 10. Reference Test) + -This test checks if references functionality, implemented in the [Reference Contributor](/tutorials/custom_language_support/reference_contributor.md) section of the Custom Language Support Tutorial, works as expected. +This test checks if references functionality, implemented in the [Reference Contributor](reference_contributor.md) section of the Custom Language Support Tutorial, works as expected. -## 10.1. Define Test Data +## Define Test Data This test reuses the Simple Language properties file `DefaultTestData.simple`. Create the test file `ReferenceTestData.java` in the `testData` directory. This file has one Simple Language prefix and key, with the caret placed after the key. ```java -{% include /code_samples/simple_language_plugin/src/test/testData/ReferenceTestData.java %} ``` +{src="simple_language_plugin/src/test/testData/ReferenceTestData.java"} -## 10.2. Define a Test Method +## Define a Test Method Add the `testReference()` method to the `SimpleCodeInsightTest` class [previously defined](completion_test.md#define-a-test). This test is configured by the test files. The fixture gets the `PsiElement` at the caret, then compares its value with the known value of that key. @@ -28,5 +27,5 @@ The fixture gets the `PsiElement` at the caret, then compares its value with the } ``` -## 10.3. Run the Test -[Run](completion_test.md#run-the-test) the test and make sure it's green. +## Run the Test +[Run](completion_test.md#run-the-test) the test and make sure it's green. \ No newline at end of file diff --git a/tutorials/writing_tests_for_plugins/rename_test.md b/topics/tutorials/writing_tests_for_plugins/rename_test.md similarity index 65% rename from tutorials/writing_tests_for_plugins/rename_test.md rename to topics/tutorials/writing_tests_for_plugins/rename_test.md index d090cbdcf..e7e72fb20 100644 --- a/tutorials/writing_tests_for_plugins/rename_test.md +++ b/topics/tutorials/writing_tests_for_plugins/rename_test.md @@ -1,34 +1,33 @@ ---- -title: 6. Rename Test ---- +[//]: # (title: 6. Rename Test) + -This test verifies the Simple Language in-place rename functionality, implemented in the [Reference Contributor](/tutorials/custom_language_support/reference_contributor.md) section of the Custom Language Support Tutorial, works as expected. +This test verifies the Simple Language in-place rename functionality, implemented in the [Reference Contributor](reference_contributor.md) section of the Custom Language Support Tutorial, works as expected. -## 6.1. Define Input Test Data +## Define Input Test Data Create the `RenameTestData.simple` properties file in the `testData` directory. ```bash -{% include /code_samples/simple_language_plugin/src/test/testData/RenameTestData.simple %} ``` +{src="simple_language_plugin/src/test/testData/RenameTestData.simple"} Create the file `RenameTestData.java` in the `testData` directory. -This file contains one Simple Language reference embedded in Java, with the [caret position](/basics/testing_plugins/test_project_and_testdata_directories.md#special-markup) placed just after a Simple Language key. +This file contains one Simple Language reference embedded in Java, with the [caret position](test_project_and_testdata_directories.md#special-markup) placed just after a Simple Language key. ```java -{% include /code_samples/simple_language_plugin/src/test/testData/RenameTestData.java %} ``` +{src="simple_language_plugin/src/test/testData/RenameTestData.java"} -## 6.2. Create Output Test Data +## Create Output Test Data Create the `RenameTestDataAfter.simple` properties file in the `testData` directory. This file contains the expected outcome of the test. Note the `website =` in `RenameTestData.simple` should be renamed to `websiteUrl =` by the test. ```bash -{% include /code_samples/simple_language_plugin/src/test/testData/RenameTestDataAfter.simple %} ``` +{src="simple_language_plugin/src/test/testData/RenameTestDataAfter.simple"} -## 6.3. Define a Test Method +## Define a Test Method Add the `testRename()` method to the `SimpleCodeInsightTest` class [previously defined](completion_test.md#define-a-test). * Again, this method configures the test fixture by using the test files. * The fixture then renames the Simple Language element at the caret in `RenameTestData.java`. @@ -42,5 +41,5 @@ Add the `testRename()` method to the `SimpleCodeInsightTest` class [previously d } ``` -## 6.4. Run the Test -[Run](completion_test.md#run-the-test) the test and make sure it's green. +## Run the Test +[Run](completion_test.md#run-the-test) the test and make sure it's green. \ No newline at end of file diff --git a/tutorials/writing_tests_for_plugins/tests_prerequisites.md b/topics/tutorials/writing_tests_for_plugins/tests_prerequisites.md similarity index 92% rename from tutorials/writing_tests_for_plugins/tests_prerequisites.md rename to topics/tutorials/writing_tests_for_plugins/tests_prerequisites.md index 57c4ca963..79ddfbdba 100644 --- a/tutorials/writing_tests_for_plugins/tests_prerequisites.md +++ b/topics/tutorials/writing_tests_for_plugins/tests_prerequisites.md @@ -1,11 +1,10 @@ ---- -title: 1. Tests Prerequisites ---- +[//]: # (title: 1. Tests Prerequisites) + This page discusses the steps to configure a plugin project for creating tests. -## 1.1. Create a Folder for Tests +## Create a Folder for Tests Open the plugin project and create a separate folder named `test` under the `src` directory. Under `test`, create the `java` folder for test source code, and the folder `testData` for test data files and reimport the Gradle project. @@ -19,7 +18,7 @@ Under `test`, create the `java` folder for test source code, and the folder `tes └── testData ``` -## 1.2. Set the Run Configuration Parameters +## Set the Run Configuration Parameters Because some of the tests use Java files as test data, the tests need to mock up the project SDK. IntelliJ IDEA does everything automatically when the utility class [`LightJavaCodeInsightFixtureTestCase`](upsource:///java/testFramework/src/com/intellij/testFramework/fixtures/LightJavaCodeInsightFixtureTestCase.java) is used as the basis for the tests. @@ -31,4 +30,4 @@ For example, on macOS the `path/to/community/` might be `/Users//Docu test { systemProperty "idea.home.path", "/path/to/community/" } -``` +``` \ No newline at end of file diff --git a/user_interface_components/dialog_wrapper.md b/topics/user_interface_components/dialog_wrapper.md similarity index 95% rename from user_interface_components/dialog_wrapper.md rename to topics/user_interface_components/dialog_wrapper.md index bd65b6ae6..3bd5e40c1 100644 --- a/user_interface_components/dialog_wrapper.md +++ b/topics/user_interface_components/dialog_wrapper.md @@ -1,6 +1,5 @@ ---- -title: Dialogs ---- +[//]: # (title: Dialogs) + ## DialogWrapper @@ -34,7 +33,9 @@ The [`DialogWrapper`](upsource:///platform/platform-api/src/com/intellij/openapi In this case, bind a GUI Designer form to the class extending `DialogWrapper`, bind the top-level panel of the form to a field and return that field from the `createCenterPanel()` method. When using Kotlin, use [Kotlin UI DSL](kotlin_ui_dsl.md) to provide the dialog's contents. -> **TIP** Existing dialogs can be inspected at runtime using [UI Inspector](/reference_guide/internal_actions/internal_ui_inspector.md), e.g., to locate the underlying implementation of UI components. + > Existing dialogs can be inspected at runtime using [UI Inspector](internal_ui_inspector.md), e.g., to locate the underlying implementation of UI components. + > + {type="tip"} To display the dialog, call the `show()` method and then use the `getExitCode()` method to check how the dialog was closed. The `showAndGet()` method can be used to combine these two calls. @@ -86,4 +87,4 @@ testButton.addActionListener(actionEvent -> { // user pressed OK } }); -``` +``` \ No newline at end of file diff --git a/user_interface_components/editor_components.md b/topics/user_interface_components/editor_components.md similarity index 98% rename from user_interface_components/editor_components.md rename to topics/user_interface_components/editor_components.md index 14f94ba63..60c75c8a2 100644 --- a/user_interface_components/editor_components.md +++ b/topics/user_interface_components/editor_components.md @@ -1,6 +1,5 @@ ---- -title: Editor Components ---- +[//]: # (title: Editor Components) + ## EditorTextField @@ -46,4 +45,4 @@ EditorTextField myInput = new EditorTextField(document, editor.getProject(), Jav However, `createExpressionCodeFragment()` accepts the text for the field as an argument. The empty string can be replaced and create a new document in lieu of `setText()`. * Instances of `JTextField` in the GUI builder can be replaced with a custom replacement component using the right click in your IDE. - Make sure to use "Custom Create", so the initialization code works properly. + Make sure to use "Custom Create", so the initialization code works properly. \ No newline at end of file diff --git a/user_interface_components/file_and_class_choosers.md b/topics/user_interface_components/file_and_class_choosers.md similarity index 97% rename from user_interface_components/file_and_class_choosers.md rename to topics/user_interface_components/file_and_class_choosers.md index cddb38900..b8198314d 100644 --- a/user_interface_components/file_and_class_choosers.md +++ b/topics/user_interface_components/file_and_class_choosers.md @@ -1,6 +1,5 @@ ---- -title: File and Class Choosers ---- +[//]: # (title: File and Class Choosers) + ## File Choosers @@ -42,4 +41,4 @@ To show the dialog, call `showDialog()` on the chooser returned from `createFile If you want to offer the user a possibility to select a Java class, you can use the [`TreeClassChooserFactory`](upsource:///java/openapi/src/com/intellij/ide/util/TreeClassChooserFactory.java) class. Its different methods allow you to specify the scope from which the classes are taken, to restrict the choice to descendants of a specific class or implementations of an interface, and to include or exclude inner classes from the list. -For choosing a Java package, you can use the [`PackageChooserDialog`](upsource:///java/java-impl/src/com/intellij/ide/util/PackageChooserDialog.java) class. +For choosing a Java package, you can use the [`PackageChooserDialog`](upsource:///java/java-impl/src/com/intellij/ide/util/PackageChooserDialog.java) class. \ No newline at end of file diff --git a/user_interface_components/kotlin_ui_dsl.md b/topics/user_interface_components/kotlin_ui_dsl.md similarity index 94% rename from user_interface_components/kotlin_ui_dsl.md rename to topics/user_interface_components/kotlin_ui_dsl.md index 27e95df29..244cdbf48 100644 --- a/user_interface_components/kotlin_ui_dsl.md +++ b/topics/user_interface_components/kotlin_ui_dsl.md @@ -1,12 +1,15 @@ ---- -title: Kotlin UI DSL ---- +[//]: # (title: Kotlin UI DSL) + -> **WARNING** Please note the Kotlin UI DSL is in active development and [breaking changes](../reference_guide/api_changes_list.md) can occur between major releases. + > Please note the Kotlin UI DSL is in active development and [breaking changes](api_changes_list.md) can occur between major releases. + > + {type="warning"} -> **NOTE** This document covers the Kotlin UI DSL in IntelliJ Platform 2019.2. + > This document covers the Kotlin UI DSL in IntelliJ Platform 2019.2. > A lot of the features described in this document are not available for plugins targeting earlier versions. + > + {type="note"} ## Layout Structure @@ -69,7 +72,9 @@ row { } ``` -> **TIP** To visually debug layout, enable _UI DSL Debug Mode_ from [Internal Actions - UI Submenu](/reference_guide/internal_actions/internal_ui_sub.md). + > To visually debug layout, enable _UI DSL Debug Mode_ from [Internal Actions - UI Submenu](internal_ui_sub.md). + > + {type="tip"} ## Adding Components @@ -278,7 +283,6 @@ checkBox("Hide tabs if there is no space", uiSettings::hideTabsIfNeed) myScrollTabLayoutInEditorCheckBox.selected) ``` - ## Example ```kotlin @@ -300,4 +304,4 @@ val panel = panel { ### One Cell Is Minimum, Second One Is Maximum -Set `CCFlags.growX` and `CCFlags.pushX` for some component in the second cell. +Set `CCFlags.growX` and `CCFlags.pushX` for some component in the second cell. \ No newline at end of file diff --git a/user_interface_components/lists_and_trees.md b/topics/user_interface_components/lists_and_trees.md similarity index 99% rename from user_interface_components/lists_and_trees.md rename to topics/user_interface_components/lists_and_trees.md index 4c2c469f9..bf85992bf 100644 --- a/user_interface_components/lists_and_trees.md +++ b/topics/user_interface_components/lists_and_trees.md @@ -1,6 +1,5 @@ ---- -title: List and Tree Controls ---- +[//]: # (title: List and Tree Controls) + ### JBList and Tree @@ -49,4 +48,4 @@ To use a toolbar decorator: +--> \ No newline at end of file diff --git a/user_interface_components/misc_swing_components.md b/topics/user_interface_components/misc_swing_components.md similarity index 93% rename from user_interface_components/misc_swing_components.md rename to topics/user_interface_components/misc_swing_components.md index 7b77f27dd..a781728e2 100644 --- a/user_interface_components/misc_swing_components.md +++ b/topics/user_interface_components/misc_swing_components.md @@ -1,6 +1,5 @@ ---- -title: Miscellaneous Swing Components ---- +[//]: # (title: Miscellaneous Swing Components) + ### Messages @@ -34,4 +33,4 @@ It has a significantly different look & feel compared to the standard Swing tabs See [Toolbar](https://jetbrains.design/intellij/controls/toolbar/) in _IntelliJ Platform UI Guidelines_ for an overview. -[Building UI from Actions](/basics/action_system.md#building-ui-from-actions) covers creating `AnAction`-based toolbars. +[Building UI from Actions](basic_action_system.md#building-ui-from-actions) covers creating `AnAction`-based toolbars. \ No newline at end of file diff --git a/user_interface_components/notifications.md b/topics/user_interface_components/notifications.md similarity index 97% rename from user_interface_components/notifications.md rename to topics/user_interface_components/notifications.md index d6ca1e9a1..8526af81b 100644 --- a/user_interface_components/notifications.md +++ b/topics/user_interface_components/notifications.md @@ -1,6 +1,5 @@ ---- -title: Notifications ---- +[//]: # (title: Notifications) + One of the leading design principles is avoiding the use of modal message boxes for notifying the user about errors and other situations that may warrant the user's attention. As a replacement, the *IntelliJ Platform* provides multiple non-modal notification UI options. @@ -51,7 +50,9 @@ Please see the following two paragraphs for setup, depending on the target platf Registered instances can then be obtained via their `id`. -> **TIP** Code insight is available for parameters expecting notification group `id`. + > Code insight is available for parameters expecting notification group `id`. + > + {type="tip"} ```java public class MyNotifier { @@ -81,4 +82,4 @@ public class MyNotifier { } } -``` +``` \ No newline at end of file diff --git a/user_interface_components/popups.md b/topics/user_interface_components/popups.md similarity index 96% rename from user_interface_components/popups.md rename to topics/user_interface_components/popups.md index c0166cf53..ae702ea51 100644 --- a/user_interface_components/popups.md +++ b/topics/user_interface_components/popups.md @@ -1,6 +1,5 @@ ---- -title: Popups ---- +[//]: # (title: Popups) + ## Popups @@ -31,6 +30,8 @@ By returning a new popup step from the `onChosen()` method, you can implement hi Once you've created the popup, you need to display it by calling one of the `show()` methods. You can let the IntelliJ Platform automatically choose the position based on the context, by calling `showInBestPositionFor()`, or specify the position explicitly through methods like `showUnderneathOf()` and `showInCenterOf()`. -> **NOTE** The `show()` methods return immediately and do not wait for the popup to be closed. + > The `show()` methods return immediately and do not wait for the popup to be closed. + > + {type="note"} -If you need to perform some action when the popup is closed, you can either attach a listener to it using the `addListener()` method, override a method of the popup contents such as [`PopupStep.onChosen()`](upsource:///platform/core-ui/src/openapi/ui/popup/PopupStep.java), or attach an event handler to your own component within the popup. +If you need to perform some action when the popup is closed, you can either attach a listener to it using the `addListener()` method, override a method of the popup contents such as [`PopupStep.onChosen()`](upsource:///platform/core-ui/src/openapi/ui/popup/PopupStep.java), or attach an event handler to your own component within the popup. \ No newline at end of file diff --git a/user_interface_components/tool_windows.md b/topics/user_interface_components/tool_windows.md similarity index 96% rename from user_interface_components/tool_windows.md rename to topics/user_interface_components/tool_windows.md index cd10efeea..f45f372ff 100644 --- a/user_interface_components/tool_windows.md +++ b/topics/user_interface_components/tool_windows.md @@ -1,6 +1,5 @@ ---- -title: Tool Windows ---- +[//]: # (title: Tool Windows) + ## Tool Windows @@ -29,7 +28,7 @@ The extension point attributes specify all the data which is necessary to displa * The `secondary` attribute, specifying whether the tool window is displayed in the primary or the secondary group -* The `icon` to display on the tool window button (13x13 pixels, see [Working with Icons and Images](/reference_guide/work_with_icons_and_images.md)) +* The `icon` to display on the tool window button (13x13 pixels, see [Working with Icons and Images](work_with_icons_and_images.md)) In addition to that, specify the `factoryClass` attribute - the name of a class implementing the [`ToolWindowFactory`](upsource:///platform/platform-api/src/com/intellij/openapi/wm/ToolWindowFactory.java) interface. When the user clicks on the tool window button, the `createToolWindowContent()` method of the factory class is called, and initializes the UI of the tool window. @@ -41,7 +40,7 @@ If the tool window of a plugin doesn't need to be displayed for all projects: Note the condition is evaluated only once when the project is loaded; to show and hide a tool window dynamically while the user is working with the project use the second method for tool window registration. -To provide a localized text for the tool window button, specify matching `toolwindow.stripe.[id]` message key (escape spaces with `_`) in your [message bundle](/reference_guide/localization_guide.md) (code insight supported in 2020.3 and later). +To provide a localized text for the tool window button, specify matching `toolwindow.stripe.[id]` message key (escape spaces with `_`) in your [message bundle](localization_guide.md) (code insight supported in 2020.3 and later). ### Programmatic Setup @@ -80,4 +79,4 @@ This plugin creates the **Sample Calendar** tool window that displays the system The plugin creates the **Sample Calendar** tool window. When opened, this tool window is similar to the following screen: -![Sample Calendar](img/sample_calendar.png) +![Sample Calendar](sample_calendar.png) \ No newline at end of file diff --git a/topics/user_interface_components/user_interface_components.md b/topics/user_interface_components/user_interface_components.md new file mode 100644 index 000000000..fc9085e2b --- /dev/null +++ b/topics/user_interface_components/user_interface_components.md @@ -0,0 +1,34 @@ +[//]: # (title: User Interface Components) + + + +The IntelliJ Platform includes a large number of custom Swing components. +Using those components in your plugins will ensure that your plugin looks and works consistently with the UI of the rest of the IDE, and can often reduce the code size compared to using the default Swing components. + + > Use [UI Inspector](internal_ui_inspector.md) to locate the underlying Swing component implementation or to inspect an existing UI at runtime. + > + {type="tip"} + + > The recommended way of building UIs on the IntelliJ Platform (2019.2 and later) is using [Kotlin UI DSL](kotlin_ui_dsl.md). +> Using GUI designer with Kotlin is currently [not supported](https://youtrack.jetbrains.com/issue/KT-6660). + > + {type="note"} + +Please refer to [Writing short and clear](https://jetbrains.design/intellij/text/writing_short/) in _IntelliJ Platform UI Guidelines_ on writing UI-related texts. + +The following components are particularly noteworthy: + +* Menus and toolbars are built using the [Action System](basic_action_system.md) +* [Tool Windows](tool_windows.md) +* [Dialogs](dialog_wrapper.md) +* [Popups](popups.md) +* [Notifications](notifications.md) +* [File and Class Choosers](file_and_class_choosers.md) +* [Editor Components](editor_components.md) +* [List and Tree Controls](lists_and_trees.md) +* Tables (TableView) (TBD) +* Drag & Drop Helpers (TBD) +* [Miscellaneous Swing Components](misc_swing_components.md) + * Messages + * JBSplitter + * JBTabs \ No newline at end of file diff --git a/tutorials/build_system.md b/tutorials/build_system.md deleted file mode 100644 index 946cd847b..000000000 --- a/tutorials/build_system.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Building Plugins with Gradle ---- - - -The [gradle-intellij-plugin](https://github.com/JetBrains/gradle-intellij-plugin) Gradle plugin is the recommended solution for building IntelliJ plugins. -The plugin takes care of the dependencies of your plugin project - both the base IDE and other plugin dependencies. - -> **TIP** [IntelliJ Platform Plugin Template](https://github.com/JetBrains/intellij-platform-plugin-template) makes it easier to create and maintain your IDE plugins, having the Gradle plugin already integrated and CI covered with GitHub Actions. - -> **NOTE** If a new plugin will be Scala-based, a dedicated SBT plugin [sbt-idea-plugin](https://github.com/JetBrains/sbt-idea-plugin) is available. - -The gradle-intellij-plugin provides tasks to run the IDE with your plugin and to publish your plugin to the [JetBrains Plugins Repository](https://plugins.jetbrains.com). -To make sure that your plugin is not affected by [API changes](/reference_guide/api_changes_list.md), which may happen between major releases of the platform, you can quickly build your plugin against many versions of the base IDE. - -> **WARNING** When adding additional repositories to your Gradle build script, always use HTTPS protocol. - -> **NOTE** Please make sure to always upgrade to the latest version of `gradle-intellij-plugin`. -Follow releases on [GitHub](https://github.com/JetBrains/gradle-intellij-plugin/releases). - -Below are a series of guides to developing and deploying Gradle-based IntelliJ Platform Plugins: - -* [Getting Started with Gradle](build_system/prerequisites.md) -* [Configuring Gradle Projects](build_system/gradle_guide.md) -* [Publishing Plugins with Gradle](build_system/deployment.md) diff --git a/tutorials/custom_language_support_tutorial.md b/tutorials/custom_language_support_tutorial.md deleted file mode 100644 index 5fda06a9c..000000000 --- a/tutorials/custom_language_support_tutorial.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Custom Language Support Tutorial ---- - - -In this tutorial we will add support for a [.properties](https://en.wikipedia.org/wiki/.properties) language and its usages within Java code. - -> **TIP** IntelliJ Platform support for custom languages is discussed in more depth in the [Custom Language Support](/reference_guide/custom_language_support.md) section. -> Corresponding parts are linked under "Reference" on top of each page in this tutorial. - -The example plugin used in this tutorial is the [`simple_language_plugin`](https://github.com/JetBrains/intellij-sdk-code-samples/tree/master/simple_language_plugin) code sample. -This a step-by-step tutorial, and it requires completing each step, in order: - -* [1. Prerequisites](custom_language_support/prerequisites.md) -* [2. Language and File Type](custom_language_support/language_and_filetype.md) -* [3. Grammar and Parser](custom_language_support/grammar_and_parser.md) -* [4. Lexer and Parser Definition](custom_language_support/lexer_and_parser_definition.md) -* [5. Syntax Highlighter and Color Settings Page](custom_language_support/syntax_highlighter_and_color_settings_page.md) -* [6. PSI Helpers and Utilities](custom_language_support/psi_helper_and_utilities.md) -* [7. Annotator](custom_language_support/annotator.md) -* [8. Line Marker Provider](custom_language_support/line_marker_provider.md) -* [9. Completion Contributor](custom_language_support/completion_contributor.md) -* [10. Reference Contributor](custom_language_support/reference_contributor.md) -* [11. Find Usages Provider](custom_language_support/find_usages_provider.md) -* [12. Folding Builder](custom_language_support/folding_builder.md) -* [13. Go To Symbol Contributor](custom_language_support/go_to_symbol_contributor.md) -* [14. Structure View Factory](custom_language_support/structure_view_factory.md) -* [15. Formatter](custom_language_support/formatter.md) -* [16. Code Style Settings](custom_language_support/code_style_settings.md) -* [17. Commenter](custom_language_support/commenter.md) -* [18. Quick Fix](custom_language_support/quick_fix.md) diff --git a/tutorials/writing_tests_for_plugins.md b/tutorials/writing_tests_for_plugins.md deleted file mode 100644 index f5d2a1167..000000000 --- a/tutorials/writing_tests_for_plugins.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Testing a Custom Language Plugin ---- - - -> **NOTE** Please see [Testing Plugins](/basics/testing_plugins/testing_plugins.md) for a general introduction. - -This tutorial demonstrates how to write and run automated tests for a custom language plugin. - -As an example, the plugin implemented in the [Custom Language Support Tutorial](/tutorials/custom_language_support_tutorial.md) is used to demonstrate functional test development. - -* [1. Tests Prerequisites](writing_tests_for_plugins/tests_prerequisites.md) -* [2. Parsing Test](writing_tests_for_plugins/parsing_test.md) -* [3. Completion Test](writing_tests_for_plugins/completion_test.md) -* [4. Annotator Test](writing_tests_for_plugins/annotator_test.md) -* [5. Formatter Test](writing_tests_for_plugins/formatter_test.md) -* [6. Rename Test](writing_tests_for_plugins/rename_test.md) -* [7. Folding Test](writing_tests_for_plugins/folding_test.md) -* [8. Find Usages Test](writing_tests_for_plugins/find_usages_test.md) -* [9. Commenter Test](writing_tests_for_plugins/commenter_test.md) -* [10. Reference Test](writing_tests_for_plugins/reference_test.md) - -The plugin and test code can be found in the [simple_language_plugin](https://github.com/JetBrains/intellij-sdk-code-samples/tree/master/simple_language_plugin) code sample. diff --git a/user_interface_components/user_interface_components.md b/user_interface_components/user_interface_components.md deleted file mode 100644 index 50a3a20f9..000000000 --- a/user_interface_components/user_interface_components.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: User Interface Components ---- - - -The IntelliJ Platform includes a large number of custom Swing components. -Using those components in your plugins will ensure that your plugin looks and works consistently with the UI of the rest of the IDE, and can often reduce the code size compared to using the default Swing components. - -> **TIP** Use [UI Inspector](/reference_guide/internal_actions/internal_ui_inspector.md) to locate the underlying Swing component implementation or to inspect an existing UI at runtime. - -> **NOTE** The recommended way of building UIs on the IntelliJ Platform (2019.2 and later) is using [Kotlin UI DSL](/user_interface_components/kotlin_ui_dsl.md). -> Using GUI designer with Kotlin is currently [not supported](https://youtrack.jetbrains.com/issue/KT-6660). - -Please refer to [Writing short and clear](https://jetbrains.design/intellij/text/writing_short/) in _IntelliJ Platform UI Guidelines_ on writing UI-related texts. - -The following components are particularly noteworthy: - -* Menus and toolbars are built using the [Action System](/basics/action_system.md) -* [Tool Windows](/user_interface_components/tool_windows.md) -* [Dialogs](/user_interface_components/dialog_wrapper.md) -* [Popups](/user_interface_components/popups.md) -* [Notifications](/user_interface_components/notifications.md) -* [File and Class Choosers](/user_interface_components/file_and_class_choosers.md) -* [Editor Components](/user_interface_components/editor_components.md) -* [List and Tree Controls](/user_interface_components/lists_and_trees.md) -* Tables (TableView) (TBD) -* Drag & Drop Helpers (TBD) -* [Miscellaneous Swing Components](/user_interface_components/misc_swing_components.md) - * Messages - * JBSplitter - * JBTabs