Setup website for SPDX Using (workflow with mkdocs)

[bact]

What this PR does

• This PR setup a workflow to publish documents in docs/ to a website, using MkDocs.
• See demo at https://bact.github.io/using/
• This should resolve Set up mkdocs #4

Pre-requisite

• A gh-pages branch in GitHub repo is needed for publication to https://spdx.github.io/using/
• The branch has to be created before the workflow starts

After merge (Optional)

• After merge, the redirect map on the spdx-spec repo can be updated to make the old Annex links redirected to pages in the SPDX Using website.

Details

• Material theme is used for two reasons:
  1. It doesn't look like the spec website, so people will not confused it with the spec
  2. It has features that help organizing documents, like tags
• The logo is taken from https://spdx.dev/ (the one at the bottom image link)
• Some page names are summarized to make the URLs shorter
• Headings in "Including security information in SPDX document" document are renumbered to remove references to Annex G
• See demo at https://bact.github.io/using/
  • Note that the "Differences between editions" section is different from what it has in this PR
    • That one is the demo for PR Smaller "Difference from previous editions" chapter, one file per one version pair #13
    • The docs/diffs-from-previous-editions.md in this PR is still in one big file
  • Tags index demo is at https://bact.github.io/using/tags/
• Material theme also generated a social card for each page, so the title of the page can be displayed as an image when shared on social media platform.
  • For example, when sharing this page https://bact.github.io/using/security-info-in-spdx/, this image will be shown
    

[bact]

This PR is to setup https://spdx.github.io/using/ - Please review @licquia @zvr @goneall @kestewart

[zvr]

May I suggest that we simplify our lives and do not use mkdocs for this repo?

This is simply a collection of independent texts, no need to generate a single website. There is not even an ordering of the texts.

Why don't we simply move them all to wiki pages?

[bact]

• Wiki should be fine as well.
• In that case we can just close Set up mkdocs #4

[bact]

If we're going to use GitHub wiki, may be it's even possible to use the wiki of spdx-spec repo?

[zvr]

My vote/preference would be to leave the spec repo for spec stuff (actual specification), and have supporting documentation elsewhere...

[goneall]

Discussed on the tech call 10 Dec 2024:

• We would need to do some admin work - permissions etc. for the Wiki
• Existing markdown would need to be translated
• May be work work than Markdown
• Sharing links would be easier with the published markdown
• Downside with the markdown is more maint.
• Joshua prefers markdown
• Markdown is more portable
• Henk - prefers markdown
• Sean - prefers markdown
• Can do pull requests

General consensus on the call is Markdown - but we don't have full representation of contributor using

[zvr]

@goneall sorry, since I wasn't in the call, I am not sure I understood what was discussed from the comment above.
Lots of people "prefer markdown", but what does that mean?
We will obviously use Markdown, one way or another -- that's what GitHub supports. I hope no one made a point of moving to RST.

The question should be: do we have markdown files/pages in a "wiki" (e.g. automatically published by GitHub) or do we have markdown files that are processed and published by our own infrastructure (mkdocs or something else) in custom workflows?

[goneall]

@goneall sorry, since I wasn't in the call, I am not sure I understood what was discussed from the comment above. Lots of people "prefer markdown", but what does that mean? We will obviously use Markdown, one way or another -- that's what GitHub supports. I hope no one made a point of moving to RST.

The question should be: do we have markdown files/pages in a "wiki" (e.g. automatically published by GitHub) or do we have markdown files that are processed and published by our own infrastructure (mkdocs or something else) in custom workflows?

@zvr - on the call, I don't think we had a good idea on what is involved in the "wiki" - we were assuming it was not markdown. I think we should replay the conversation once you're on the call. Perhaps you can give us a demo of what the wiki workflow would look like.

[bobmartin3000]

Nice job - LGTM

[kestewart]

This looks excellent, Art.

[swinslow]

+1, this is great!

[kestewart]

Given I'm not seeing any disagreement, going ahead and merging this.

[bact]

@kestewart @goneall in order to have the website up and running, at https://spdx.github.io/using/, we need to enable GitHub Pages in the settings

[goneall]

@kestewart @goneall in order to have the website up and running, at https://spdx.github.io/using/, we need to enable GitHub Pages in the settings

This is now enabled, but it may not be configured correctly since the pages are not published

[bact]

@goneall probably need to have gh-pages branch? From this log

https://github.com/spdx/using/actions/runs/18481357657/job/52656519585#step:6:1

[bact]

@goneall looks like the git clone & sync approach is no longer working (or can work but need to fiddle with permissions, which we shouldn't).

PR #27 update the CI by using the official GitHub Pages deploy action.
This approach do not need the gh-pages branch (and related branch permission).