Sync website assets from templates #225
Merged
Conversation
This file contains hidden or 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
These comments add nothing of value to the file.
This will provide contributors with ready access to information about the purpose and usage of the file.
This will encourage readers to submit pull requests for any corrections or improvements to the website content that might occur to them while using it.
No functional effect, but can make it a little easier for the contributor to find the item of interest.
The previous "Documentation Home" was unnecessarily verbose.
NOTE: the outdated versions of mike and mkdocs-material, previously in use required an approach to creating the version selector menu the author describes as "hacky". That "hacky" approach no longer works with the modern version of mkdocs-material. Fortunately, this is not a problem since the material theme now has official support for versioning via mike: https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/ This avoids the need for us to maintain JavaScript and CSS files. This does result in a change in the website GUI. The version selector menu has moved from where it was previously in the navigation panel to the title bar.
This is the template workflow filename, which is intended to serve as a unique identifier, and thus must be a bit more verbose.
Thus is the naming convention established in the standardized template project assets.
These are the naming conventions established in the standardized template workflow.
Even though this project's generated documentation is currently limited to the CLI reference, this might not always be so, and anyway this is intended to follow a universally applicable template. `docs:generate` is an "umbrella" task that collects all the specific documentation generation subtasks a project has, and so it should be used whenever the documentation needs to be generated.
Sync with the "template" task.
The project name is defined in the `PROJECT_NAME` taskfile variable. In order to make it easier to share task "templates" among projects, this should always be used in place of the project name in the taskfile.
This new approach to versioning the website uses the workflow as the sole central orchestrator of the documentation deployment system, restricting the role of the Python script (here renamed from "build.py" to "siteversion") to solely to determining the appropriate version for the deployment. Since deployment of the website is the exclusive domain of the automated systems, there is no point in using Task for that operation, so the deployment commands are moved from the taskfile to the workflow.
… files The paths filter is used to make GitHub Actions workflows more efficient and contributor friendly by preventing pointless workflow runs from happening when only irrelevant files were modified. However, careful consideration must be given to which files are relevant.
No functional difference, and neither is necessarily superior, but that is how it is in the template, and so it must be here too.
During the development phase of the previous attempt at setting up an official collection of template workflows, I investigated dependencies caching and added it to all workflows where applicable. Afterwards, doubts were raised about whether it provided any benefits. I don't know enough about this subject to make a call on that and I have been unable to get any more information on the subject. Since the caching significantly increases the complexity of the workflows, which may make them more difficult to maintain and contribute to, I think it's best to just remove all the caching for now. I hope to eventually be able to revisit this topic and restore caching in any workflows where it is definitely beneficial. This particular caching step was in the source workflow in the Arduino CLI repository from the very beginning, and was my inspiration for using caching in the first place. However, none of the other workflows with Python dependencies have caching at this point, so having this one as an exception to the otherwise fairly standardized workflow format is confusing.
This is a standardized "template" program that is intended to be added to any project with the minimum of changes. The project specific references are unnecessary and some even were not updated when the file was copied from its original source in the Arduino CLI repository.
The command line reference documentation for Cobra-based Go projects is output to the docs/commands/ folder. Since this documentation is generated, it is not stored in the repository. Previously, the generation program required this output folder to already exist. This meant that the otherwise empty folder had to be added to the repository, with a `.gitkeep` placeholder file since Git does not track empty folders in repositories. This added clutter to the repository. A better approach is for the documentation generation program to simply create the output folder before generating the content.
Thus is the naming convention established in the standardized template project assets.
Sync with "template" tasks.
A dedicated task has been added for installing the project's Python depencies, and this should be used throughout the taskfile in place of redundant direct commands.
This allows the dependency tasks to run in parallel.
The `mkdocs serve` command builds the website before serving it, so it is not necessary to do a run of `mkdocs build` first.
This is the template workflow filename, which is intended to serve as a unique identifier, and thus must be a bit more verbose.
These are the naming conventions established in the standardized template workflow.
…files The paths filter is used to make GitHub Actions workflows more efficient and contributor friendly by preventing pointless workflow runs from happening when only irrelevant files were modified. However, careful consideration must be given to which files are relevant.
No functional change, and neither is necessarily superior, but this is how it is in the template, and so it must be here as well.
The `workflow_dispatch` event allows triggering the workflow via the GitHub web interface. This makes it easy to trigger an immediate workflow run after some relevant external change. The `repository_dispatch` event allows triggering workflows via the GitHub API. This might be useful for triggering an immediate check in multiple relevant repositories after an external change, or some automated process. Although we don't have any specific need for this event at the moment, the event has no impact on the workflow, so there is no reason against having it. It is the sort of thing that can end up being useful if it is already in consistently in place, but not worth setting up on demand, since the effort to set it up is greater than the effort to trigger all the workflows manually.
No functional difference, and neither is necessarily superior, but that is how it is in the template, and so it must be here too.
I'm actually not sure that this is an improvement, but it's this way in the template, so it's best to just sync it for now and hopefully take a closer look at some point in the future.
The badges provide a prominent indication of the repository's CI status at a glance. This may help to bring potential issues to the attention of the maintainers.
This will make it easier for the maintainers to sync fixes and improvements in either direction between the upstream "template" assets and their installations in this repository.
Placement of this information at the top of the file, where it is easy to find and edit, facilitates updates to the workflows as the tool version used for project development are bumped periodically.
per1234
added
type: enhancement
per1234
changed the title
silvanocerza
approved these changes
Aug 4, 2021
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.
We have assembled a collection of reusable project assets:
https://github.com/arduino/tooling-project-assets
These workflows will be used in the repositories of all Arduino tooling projects.
Some significant improvements and standardizations have been made in the upstream "template" workflow, and those are introduced to this repository via this pull request.
Demo dev deployment in my fork:
Demo release deployment in my fork:
NOTE: the failure of the link check job from the "Check Markdown" workflow is expected. The link will be valid after the first run of the website deployment workflow under the new file name, as shown by the equivalent badge from my fork: https://github.com/per1234/arduino-lint/actions/workflows/deploy-cobra-mkdocs-versioned-poetry.yml/badge.svg