Setup website for SPDX Using (workflow with mkdocs)

.editorconfig

@@ -0,0 +1,16 @@
+# EditorConfig helps developers define and maintain consistent
+# coding styles between different editors and IDEs
+# See also http://editorconfig.org/
+
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false  # Markdown using two trailing spaces for <br />

.gitattributes

@@ -0,0 +1,16 @@
+# Set the default behavior, in case people don't have core.autocrlf set.
+* text=auto
+
+# Explicitly declare text files you want to always be normalized and converted
+# to native line endings on checkout.
+*.md text eol=lf
+*.py text eol=lf
+*.txt text eol=lf
+*.yml text eol=lf
+
+# Denote all files that are truly binary and should not be modified.
+*.gif binary
+*.jpg binary
+*.pdf binary
+*.png binary
+*.svg binary

.github/workflows/publish.yml

@@ -0,0 +1,36 @@
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch: {}
+permissions:
+    contents: write
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    container: python:3
+    env:
+      REF: "main"                    # source branch/tag release
+      GH_PAGES_BRANCH: "gh-pages"    # target branch (to publish HTML to)
+      GIT_USER_NAME: "publish-github-actions"  # for gh-pages commit
+      GIT_USER_EMAIL: "publish-github-actions[bot]@users.noreply.github.com"  # for gh-pages commit
+    steps:
+      - name: Checkout content
+        uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332  #v4.1.7
+        with:
+          ref: ${{ env.REF }}
+          path: using
+          fetch-depth: 0
+      - name: Install pre-requisites for MkDocs
+        run: pip install -r using/requirements.txt
+      - name: Set Git identity
+        working-directory: using
+        run: |
+          git config user.name ${{ env.GIT_USER_NAME }}
+          git config user.email ${{ env.GIT_USER_EMAIL }}
+      - name: Sync GitHub Pages
+        working-directory: using
+        run: git checkout ${{ env.GH_PAGES_BRANCH }} && git pull && git checkout ${{ env.REF }}
+      - name: Build and deploy docs
+        working-directory: using
+        run: mkdocs gh-deploy --clean --verbose --remote-branch ${{ env.GH_PAGES_BRANCH }}

.gitignore

@@ -0,0 +1,33 @@
+# Ignore all hidden files/dirs except .gitignore
+.*
+!/.gitignore
+!/.github
+
+# Operating system files
+.DS_Store
+._*
+Thumbs.db
+Thumbs.db:encryptable
+*.lnk
+
+# Generated docs
+*.epub
+*.mobi
+*.pdf
+
+# Build output directory
+dist/
+site/
+
+# Build temporary directory
+logs/
+__pycache__/
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/

README.md

@@ -1,3 +1,18 @@
-# using
+---
+SPDX-License-Identifier: Community-Spec-1.0
+---
 
-Information on how to use the SPDX specification
+# Using SPDX
+
+Information on how to use the
+[SPDX specification](https://spdx.dev/use/specifications/).
+
+This is not part of the specification.
+
+Everything in this repository is for informative purpose only.
+
+Copyright © 2024, The Linux Foundation and its Contributors.
+
+This work is licensed under the
+[Community Specification License 1.0](./LICENSE)
+(Community-Spec-1.0).

docs/using-SPDX-to-comply-with-industry-guidance.md → docs/comply-with-norms.md

@@ -1,4 +1,11 @@
-# Using SPDX to comply with Norms, Standards and Regulation
+---
+SPDX-License-Identifier: Community-Spec-1.0
+tags:
+  - compliance
+  - v3.0
+---
+
+# Using SPDX to comply with norms, standards and regulation
 
 ## Satisfying NTIA Minimum Elements for an SBOM using SPDX / US Executive Order 14028
 

docs/cross-reference.md → docs/cross-ref.md

@@ -1,3 +1,10 @@
+---
+SPDX-License-Identifier: Community-Spec-1.0
+tags:
+  - reference
+  - v3.0
+---
+
 # Cross referencing in SPDX 3
 
 This document will walk though how to refer to SPDX Elements across documents
@@ -7,7 +14,7 @@ If you do would like to construct the complete example documents from this
 Markdown file, use the following command:
 
 ```shell
-cat cross-reference.md | awk 'BEGIN{flag=0} /^```json/, $0=="```" { if (/^---$/){flag++} else if ($0 !~ /^```.*/ ) print $0 > "doc-" flag ".spdx.json"}'
+cat cross-ref.md | awk 'BEGIN{flag=0} /^```json/, $0=="```" { if (/^---$/){flag++} else if ($0 !~ /^```.*/ ) print $0 > "doc-" flag ".spdx.json"}'
 ```
 
 ## Linking via spdxId

docs/diffs-from-previous-editions.md

@@ -1,4 +1,17 @@
-# Annex A: Differences from previous editions (Informative)
+---
+SPDX-License-Identifier: Community-Spec-1.0
+tags:
+  - v3.0
+  - v2.3
+  - v2.2.2
+  - v2.2.1
+  - v2.2
+  - v2.1
+  - v2.0
+  - v1.2
+---
+
+# Differences from previous editions
 
 ## A.1 Differences between V3.0 and V2.3 <a name="A.1"></a>
 

docs/getting-started.md

@@ -1,6 +1,12 @@
+---
+SPDX-License-Identifier: Community-Spec-1.0
+tags:
+  - v3.0
+---
+
 # Getting started writing SPDX 3
 
-## (a.k.a My First SPDX File)
+(a.k.a My First SPDX File)
 
 This guide is designed to walk you through the concepts behind an SPDX
 document, by walking through writing one by hand. While it is possible to write

docs/index.md

@@ -0,0 +1,20 @@
+---
+SPDX-License-Identifier: Community-Spec-1.0
+---
+
+# Using SPDX
+
+Information on how to use the
+[SPDX specification](https://spdx.dev/use/specifications/).
+
+Copyright © 2024, The Linux Foundation and its Contributors.
+
+This work is licensed under the
+[Community Specification License 1.0](https://spdx.org/licenses/Community-Spec-1.0.html)
+(Community-Spec-1.0).
+
+!!! info
+
+    This is not part of the specification.
+
+    Everything on this website is for informative purpose only.

docs/using-SPDX-short-identifiers-in-source-files.md → docs/license-id-in-source.md

@@ -1,4 +1,11 @@
-# Using SPDX license list short identifiers in source files
+---
+SPDX-License-Identifier: Community-Spec-1.0
+tags:
+  - license
+  - compliance
+---
+
+# Using SPDX License List short identifiers in source files
 
 TODO: update for SPDXv3
 
@@ -8,23 +15,27 @@ Identifying the license for open source software is critical for both reporting
 
 [Short identifiers](https://spdx.org/licenses/) from the SPDX License List can be used to indicate license info at the file level. The advantages of doing this are numerous but include:
 
-* It is precise.
-* It is concise.
-* It is language neutral.
-* It is easy and more reliable to machine process.
-* Leads to code that is easier to reuse.
-* The license information travels with the file (as sometimes not entire projects are used or license files are removed).
-* It is a standard and can be universal. There is no need for variation.
-* An SPDX short identifier is immutable.
-* Easy look-ups and cross-references to the SPDX License List website.
+- It is precise.
+- It is concise.
+- It is language neutral.
+- It is easy and more reliable to machine process.
+- Leads to code that is easier to reuse.
+- The license information travels with the file (as sometimes not entire projects are used or license files are removed).
+- It is a standard and can be universal. There is no need for variation.
+- An SPDX short identifier is immutable.
+- Easy look-ups and cross-references to the SPDX License List website.
 
 If using SPDX short identifiers in individual files, it is recommended to reproduce the full license in the projects LICENSE file and indicate that SPDX short identifiers are being used to refer to it. For links to projects illustrating these scenarios, see <https://spdx.dev/ids-where>.
 
 ## Format for `SPDX-License-Identifier`
 
-The `SPDX-License-Identifier` tag declares the license the file is under and should be placed at or near the top of the file in a comment. 
+The `SPDX-License-Identifier` tag declares the license the file is under and should be placed at or near the top of the file in a comment.
 
-The SPDX License Identifier syntax may consist of a single license (represented by a short identifier from the [SPDX license list](https://spdx.org/licenses/)) or a compound set of licenses (represented by joining together multiple licenses using the license expression syntax).
+The SPDX License Identifier syntax may consist of a single license
+(represented by a short identifier from the
+[SPDX License List](https://spdx.org/licenses/)) or a compound set of licenses
+(represented by joining together multiple licenses using the license expression
+syntax).
 
 The tag should appear on its own line in the source file, generally as part of a comment.
 
@@ -34,7 +45,9 @@ SPDX-License-Identifier: <SPDX License Expression>
 
 ## Representing single license
 
-A single license is represented by using the short identifier from [SPDX license list](https://spdx.org/licenses/), optionally with a unary "+" operator following it to indicate "or later" versions may be applicable.
+A single license is represented by using the short identifier from
+[SPDX License List](https://spdx.org/licenses/), optionally with a unary "+"
+operator following it to indicate "or later" versions may be applicable.
 
 Examples:
 
@@ -71,4 +84,3 @@ SPDX-License-Identifier: LicenseRef-my-special-license
 ```
 
 The `LicenseRef-` format is defined in the SPDX specification Annex defining license expressions. When using a custom `LicenseRef-` identifier, you will also need to provide a way for others to determine what license text corresponds to it. The [REUSE Software Specification](https://reuse.software/spec/) provides a standardized format that can optionally be used for providing the corresponding license text for these identifiers.
-