SPDX CryptAlg List website publishing technical implementation

[toscalix]

Background

Rationale

Publishing the List of the website requires the creation of different artifacts.

Description

Action

• Development of the script that
  • Add the table with the names, IDs and cryptoClass of each algorithm
  • Transform the YAML files into one html file per algorithm
• Validation of the script
• Creation of the PR
• PR merged

DoD

• Link to the PR
• Link to the script:

[ortizjeronimo]

Hello everyone!

I've worked on the script during the weekend, you will see it on branch 'feature/spdx-style-html-generator'.

I would really appreciate some feedback on my work, below you'll find relevant links:

• script
• instructions

Let me know your thoughts.

[toscalix]

@goneall @zvr can you take a look? I added them as assignees for now.

[zvr]

@ortizjeronimo great work, thanks!
However, as a general practice, please add your work as PRs (Pull Requests), so the built-in GitHub tools and workflow can be used to review it. Now that you've already pushed it to the repo, we have to manually duplicate this functionality with comments.

Instructions

You'll need to be more explicit than "generate the index by running ruby script.rb". The typical output for this command would be ruby: command not found ;-)

Please spell out things like:

• "you have to install ruby, here's how to do it"
• "you have to install these external modules (if there are any), here's how to do it"
• "you have to be in this directory to run the script" (if there is such need)
• "the output will be created in ..." or "the output location can be specified by ...."
• etc. etc.

Keep in mind, that all this information will come handy when the automated action to run the script is created; all these steps will have to be implemented.

Functionality

There should be two distinct functionalities of the script:

• generate the index
• validate the input

These are run in different times: you validate the input on every commit push, to make sure everything is fine; and the actual generation only happens when you want to publish a new version of the list.

It's perfectly fine that this first version of the script does not implement the input validation part. I am only mentioning it here to not forget it.

The trigger for this was your "output validation" option. I am not sure what this does: if it's useful, why have it as optional and not do it every time?

Script

The choice of Ruby as implementation language is... interesting. Nothing wrong with it technically, but I am worried we are introducing yet another dependency in our ecosystem. I mean, years from now, there will be need to find someone competent in it to maintain the script. We've already had this issue (with other technologies) in other SPDX repos.
I am not an expert Ruby programmer, so the following are just notes on the code based on my simple reading:

• lines 61ff: Is the CSS something you created yourself, or was it copied/inspired by what is already used in the License List? It might be better to not have very different visual styles in various tables of the SPDX project.
• lines 189-190: name and cryptoClass have to exist (same as id above) and should never be the default value "N/A". This is an example of the input validation I mentioned above.
• lines 243ff: why did you choose to use a monospace font for all the information on the algorithm pages?
• line 286: using the raw algorithm id as the filename will result in errors if the id has, for example, a "/" character in it

That's all I saw with a quick look at the code (I repeat, I am not a Ruby programmer).

[ortizjeronimo]

Hi @zvr

Regarding the pull request, that was a mistake on my side, should I issue one or continue communicating through this chat?

I chose Ruby because I've been working on personal projects with it recently. However, if you prefer the script be written in another language, let me know and I'll work on it.

Let me address your questions/comments:

1. I built it myself, following the style used in the License List
   2 & 4. Understood
2. What font would you like me to use? That was a placeholder font I left, no reason behind it

Let me work on these items, and I'll get back to you.

Thanks for the feedback!