[skip changelog] Sync documentation assets with templates #1383
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
per1234
added
type: enhancement
We have assembled a collection of reusable project assets: https://github.com/arduino/tooling-project-assets These assets will be used in the repositories of all Arduino tooling projects. Some significant improvements and standardizations have been made in the upstream "template" assets, and those are introduced to this repository here. Notable: - Use markdownlint to check for common problems and formatting. - Make link check task Windows compatible - Streamline website versioning system - Use modern MkDocs versioning features - Make command reference generation task Windows compatible - Consolidate all Python dependency management to Poetry - Standardize documentation-related task names and deprecate old task names
The sync with the template documentation assets has resulted in new standardized names for some of the documentation management tasks: - `docs:gen:commands` -> `go:cli-docs` - `docs:gen` -> `docs:generate` - `docs:build` -> `docs:check` - `docs:serve` -> `website:serve` - `docs:check-links` -> `markdown:check-links`
This is the standardized ordered list prefix for use in all Arduino Tooling Markdown files. The Markdown renderer will automatically handle numbering. Manual numbering means that either all following list items need to be renumbered every time a list item is added or removed, resulting in more work for contributors and reviewers.
"Code fencing" is superior to the indentation code block syntax of Markdown because it permits syntax highlighting. Even in cases where syntax highlighting is not applicable, a consistent style should be used throughout all the Markdown files of Arduino Tooling projects.
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.
Please check if the PR fulfills these requirements
before creating one)
our contributing guidelines
UPGRADING.mdhas been updated with a migration guide (for breaking changes)Infrastructure update
We have assembled a collection of reusable project assets:
https://github.com/arduino/tooling-project-assets
These assets will be used in the repositories of all Arduino tooling projects.
Some significant improvements and standardizations have been made to the documentation management system in the upstream "template" assets, but have not yet been pulled into this repository.
Workflow is synced with the state of the art from upstream.
Notable changes:
docs:gen:commands->go:cli-docsdocs:gen->docs:generatedocs:build->docs:checkdocs:serve->website:servedocs:check-links->markdown:check-linkstitled accordingly?
The changed task names might be disruptive to development work, but there are no breaking changes to the API.
Yes
"Check Prettier Formatting" workflow run failure is unrelated to the changes made here: #1380 (comment)
Broken link check failure is expected. The badge link will become valid on the workflow run when this PR is merged. Equivalent URL from my fork:
https://github.com/per1234/arduino-cli/actions/workflows/deploy-cobra-mkdocs-versioned-poetry.yml/badge.svg
Demonstration "dev" website deployment:
Demonstration release website deployment: