Skip to content

Conversation

per1234
Copy link
Contributor

@per1234 per1234 commented Jan 5, 2024

What This PR Changes

Add Mandatory Prefixes

The system that copies the standard downloadable files to the "resources" folders identifies them by a file suffix which starts with - (e.g., *-schematics.pdf):

find ./content/hardware -type f -name "*-schematics.pdf" -exec cp {} ./static/resources/schematics/ \;
find ./content/hardware -type f -name "*-datasheet.pdf" -exec cp {} ./static/resources/datasheets/ \;
find ./content/hardware -type f -name "*-full-pinout.pdf" -exec cp {} ./static/resources/pinouts/ \;
find ./content/hardware -type f -name "*-pinout.png" -exec cp {} ./static/resources/pinouts/ \;

The website infrastructure has a system for handling files not covered by the "resources" system. However, unlike the "resource" downloadables file copying system of the arduino/docs-content repository, the website generator's system doesn't include the - in the file suffix patterns it uses to identify the resource files (see src/components/product/ProductResources.js:65-109 in that private repo). This means that if a downloadable file has a name matching the resource filename pattern, but without the -, then it slips through a gap between the two systems and the download link on the website for these files will be broken.

Some of the "resource" downloadable files were missing the standard <sku>- prefix and thus did not match the pattern and were not copied to the "resources" folders. This causes the "Schematics" links on those product pages to lead to a 404 page instead of downloading the schematics as expected:

This is fixed by adding the standard prefix to the filenames of the resource downloadables.

Add Non-Mandatory Prefixes

Although a unique dash-separated prefix is mandatory for the "resource" downloadables, it is not mandatory for the non-"resource" downloadables. However, consistency with the established conventions is beneficial regardless so I also propose the addition of this prefix to the filenames of the non-"resource" downloadables that don't have any prefix.

Additional Context

Even though the mismatch between the resource downloadable file identification code in the two systems is a bug, a differentiating prefix on the filenames is also required to avoid collisions in the resources folder so this change is beneficial even after the bug in the infrastructure is fixed.

Contribution Guidelines

The system that copies the standard downloadable files to the "resources" folders identifies them by a file suffix which
starts with `-` (e.g., `*-schematics.pdf`). These files were missing the standard `<sku>-` prefix and thus did not match
the pattern and were not copied to the "resources" folders.

The website infrastructure has a system for handling files not covered by the "resources" system. However, unlike the
resource downloadables file copying system of the `arduino/docs-content` repository, the website generator's system
doesn't include the `-` in the file suffix patterns it uses to identify the resource files. This means that if a
downloadable file has a name matching the resource filename pattern, but without the `-`, then it slips through a gap
between the two systems and the download link on the website for these files will be broken.

This is fixed by adding the standard prefix to the filenames of the resource downloadables.

Even though the mismatch between the resource downloadable file identification code in the two systems is a bug, a
differentiating prefix on the filenames is also required to avoid collisions in the resources folder so this change is
beneficial even after the bug in the infrastructure is fixed.
The established convention is to use a prefix with the form `<sku>-` in the filenames of the downloadables. This sort of
unique prefix is mandatory for the "resource" downloadables. It is not mandatory for the non-"resource" downloadables,
but consistency with the established conventions is beneficial regardless.
@per1234 per1234 added bug Something isn't working arduino Bugs and fixes added by the Arduino Team labels Jan 5, 2024
@jhansson-ard jhansson-ard requested a review from Matteo-it January 8, 2024 07:42
@jhansson-ard
Copy link
Contributor

Hello Per! I am adding @Matteo-it as the main reviewer of this PR, since he is working on the next version of Docs.

Thank you! ⭐

Copy link
Contributor

@sebromero sebromero left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@per1234 per1234 merged commit da3fd04 into arduino:main Jan 9, 2024
@per1234 per1234 deleted the fix-downloadables-filenames branch January 9, 2024 04:48
@jhansson-ard
Copy link
Contributor

Hey @per1234 and @sebromero. As mentioned in the previous message, I wanted to wait until @Matteo-it had time to preview this PR. Why was this merged before that happened?

@Matteo-it
Copy link
Contributor

No problem, will check directly in the active branch for Docs 2 - if i notice problems i will ask!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
arduino Bugs and fixes added by the Arduino Team bug Something isn't working
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants