Replace IDE 2.x configuration file content with link to source #418
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Arduino IDE 2.x allows the user to customize the output of the "Auto Format" feature via a configuration file. This system is documented in the "Customizing the Auto Formatter Feature" tutorial. When the user customizes the formatter, their configuration file is used exclusively by the formatter tool rather than being merged into the standard configuration. Since the user is likely only interested in modifying a small number of specific aspect of the standard configuration (e.g., wishing to use "broken" rather than "attached" braces), they will find it convenient to use Arduino's standard configuration as a base for their custom configuration. For this reason, the standard configuration is offered in the tutorial. Previously, the full YAML code of the standard configuration was included in the tutorial page itself. This was the best approach at the time the tutorial was created because what was the canonical source in the Arduino IDE code base is in a format not usable in this application. Since that time, the ClangFormat native YAML file has been published in a dedicated permanent location where it is hosted as the canonical source for all projects that use the configuration. This enabled the removal of the configuration code from the tutorial, replaced by a link to the source file. This change provides the following benefits: ### Reduce maintenance burden The configuration code must be updated periodically in parallel to bumps of the version of ClangFormat used by Arduino IDE 2.x and other Arduino development tools. This is handled as a matter of course in the canonical source file, but the copy hosted in the tutorial content would have needed updates as well (or else become outdated). Pointing the reader to the source ensures they will always have the current configuration without any need to maintain the documentation content. ### Improves approachability of tutorial The configuration code added a large block of complex YAML to the tutorial. Although it will be necessary for the reader to eventually work with this code, they don't have any need to browse through it while reading the tutorial. So having the code as part of the tutorial content didn't add anything of value and also harmed the readability.
Arduino IDE 2.x allows the user to customize the output of the "Auto Format" feature via a configuration file. This system is documented in the "Customizing the Auto Formatter Feature" tutorial. Arduino's standard formatter configuration file is offered as part of the tutorial. Originally, the full YAML code of the standard configuration was included in the tutorial page itself. Since that consisted as a large block of cryptic code, it made sense to place it at the bottom of that section of the tutorial, after the section's prose content, following this structure: - Introduction - Supplemental note - Configuration code Since that time, the code content has been replaced by a link to the source file. After this change, the placement of this essential link (which is less visibly prominent in the page) makes less sense. The content will be easier to follow with the new structure: - Introduction - Configuration file link - Supplemental note
per1234
added
enhancement
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Background
Arduino IDE 2.x allows the user to customize the output of the "Auto Format" feature via a configuration file.
This system is documented in the "Customizing the Auto Formatter Feature" tutorial.
When the user customizes the formatter, their configuration file is used exclusively by the formatter tool rather than being merged into the standard configuration. Since the user is likely only interested in modifying a small number of specific aspect of the standard configuration (e.g., wishing to use "broken" rather than "attached" braces), they will find it convenient to use Arduino's standard configuration as a base for their custom configuration. For this reason, the standard configuration is offered in the tutorial.
Previously, the full YAML code of the standard configuration was included in the tutorial page itself. This was the best approach at the time the tutorial was created because what was the canonical source in the Arduino IDE code base is in a format not usable in this application.
Since that time, the ClangFormat native YAML file has been published in a dedicated permanent location where it is hosted as the canonical source for all projects that use the configuration (arduino/tooling-project-assets#250).
What This PR Changes
This pull request proposes the removal the configuration code from the tutorial, replaced by a link to the source file.
This change would provide the following benefits:
Reduce maintenance burden
The configuration code must be updated periodically in parallel to bumps of the version of ClangFormat used by Arduino IDE 2.x and other Arduino development tools.
This is handled as a matter of course in the canonical source file, but the copy hosted in the tutorial content would have needed updates as well (or else become outdated).
Pointing the reader to the source ensures they will always have the current configuration without any need to maintain the documentation content.
Improves approachability of tutorial
The configuration code added a large block of complex YAML to the tutorial. Although it will be necessary for the reader to eventually work with this code, they don't have any need to browse through it while reading the tutorial. So having the code as part of the tutorial content didn't add anything of value and also harmed the readability.
Contribution Guidelines