Skip to content

Commit

Permalink
Add build instruction and flow diagram
Browse files Browse the repository at this point in the history 
Signed-off-by: Arthit Suriyawongkul <arthit@gmail.com>
  • Loading branch information
@bact
bact committed Jun 10, 2024
1 parent 151cd0f commit f237713
Showing 1 changed file with 190 additions and 17 deletions.
207 changes: 190 additions & 17 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,33 +1,206 @@
# The System Package Data Exchange (SPDX®) Specification

The System Package Data Exchange (SPDX®) specification is an open standard capable of representing systems with software components in as SBOMs (Software Bill of Materials) and other AI, data and security references supporting a range of risk management use cases.
The System Package Data Exchange (SPDX®) specification is an open standard
capable of representing systems with software components in as SBOMs
(Software Bill of Materials) and other AI, data and security references
supporting a range of risk management use cases.

The SPDX standard helps facilitate compliance with free and open source software licenses by standardizing the way license information is shared across the software supply chain. SPDX reduces redundant work by providing a common format for companies and communities to share important data about software licenses and copyrights, thereby streamlining and improving compliance.
The SPDX standard helps facilitate compliance with free and open source
software licenses by standardizing the way license information is shared across
the software supply chain. SPDX reduces redundant work by providing a common
format for companies and communities to share important data about software
licenses and copyrights, thereby streamlining and improving compliance.

This repository holds under active development version of the specification as:

* [MarkDown](https://github.com/spdx/spdx-spec/tree/master/chapters) (`master` branch)
* HTML (gh-pages branch, built on every commit to `master` and `development/` branches)
* [Current](https://spdx.github.io/spdx-spec/v3.0/)
- Markdown:
[`development/v3.0.1`](https://github.com/spdx/spdx-spec/tree/development/v3.0.1/docs)
branch
- HTML: `gh-pages` branch, built on every commit to the development branch,
see the workflow in
[`.github/workflows/publish_v3.yml`](/.github/workflows/publish_v3.yml)
- Current (3.0): <https://spdx.github.io/spdx-spec/v3.0/>

See for the official [releases of the specification](https://spdx.org/specifications) or additional information also the [SPDX website](https://spdx.org).
The model itself is under active development at
[spdx/spdx-3-model](https://github.com/spdx/spdx-3-model/)
repo (`main` branch).

## Specification Structure
See for the official
[releases of the specification](https://spdx.org/specifications)
or additional information also the SPDX website at <https://spdx.org>.

The specification consists of a model which is generated from the [spdx-3-model](https://github.com/spdx/spdx-3-model) repository and additional information in the `docs` directory.
## Specification structure

The `examples` directory contains examples of various SPDX serializations for the current version of the spec.
This repository consists of these files and directories:

# Building the specification
- `bin/` - Scripts for spec generation.
- `docs/` - Specification content:
- `annexes/` - Annexes for the specification.
- `css/` - Style sheets for HTML.
- `images/` - Model diagrams. These image files are to be generated from a
diagram description file
[model.drawio](https://github.com/spdx/spdx-3-model/blob/main/model.drawio)
in `spdx/spdx-3-model` repo and manually copied here.
- `licenses/` - Licenses that used by the SPDX specifications.
- `model/` - Model files*. This subdirectory _is to be created_ by a script
from `spdx/spec-parser` repo, using model information from
`spdx/spdx-3-model` repo (see the build instructions below).
- `examples/` - Examples of various SPDX serializations for the current version
of the spec.
- `mkdocs.yml` - MkDocs recipe for the spec documentation generation. The
inclusion of model files and the order of chapters are defined here.

## Prerequisites
The specification consists of documents in the `docs/` directory from this
`spdx/spdx-spec` repository and a model which is generated from Markdown files
in the `spdx/spdx-3-model` repository.

You have to [MkDocs](http://mkdocs.org) installed on your machine. If you don't have it yet installed please follow these [installation instructions](http://www.mkdocs.org/#installation).
Note: The model Markdown files in the `spdx/spdx-3-model` repository use a
constrained format. Only a limited set of headings are allowed for processing
by the spec-parser.

## Building HTML
## Building the specification

# Execute built-in dev-server that lets you preview the specification
$ mkdocs serve
The specification building flow looks like this:

# Building static HTML site
$ mkdocs build
```text
+-------------------+
|[spdx-3-model] |
| | |
| +- model/ ---- Constrained-Markdown files -+
| | | |
| +- model.drawio -----------------+ |
+-------------------+ | |
| |
| |
+-------------------+ v |
|[spdx-spec] | draw.io |
| | | (manual) |
| +- docs/ | | |
| | | | |
| +- annexes/ | | v
| | | | spec-parser
| +- images/ <---- PNG images --+ |
| | | |
| +- licenses/ | |
| | | |
| +- model/ <----- Processed Markdown files ---+
| | |
| +- index.md |
| | |
| +- *.md |
+-------------------+
|
mike & mkdocs
|
v
+-------------------+
| HTML website |
+-------------------+
```

### Prerequisites

Apart from Git and Python, you have to have [MkDocs](http://mkdocs.org)
installed on your machine. If you don't have it yet installed please follow
these [installation instructions](http://www.mkdocs.org/#installation).

[WeasyPrint](https://doc.courtbouillon.org/weasyprint/stable/first_steps.html#installation)
is also required for generating PDF files. To disable PDF generation, comment
out the these lines in your `mkdocs.yml` configuration file:

```yaml
#- pdf-export:
# combined: true
```

### Preparing input files

Next, you have to prepare the model files, the other specification files,
and the model parser, by cloning these repositoriess:
[`spdx/spdx-3-model`](https://github.com/spdx/spdx-3-model),
[`spdx/spdx-spec`](https://github.com/spdx/spdx-spec), and
[`spdx/spec-parser`](https://github.com/spdx/spec-parser)
to these paths: `spdx-3-model`, `spdx-spec`, and `spec-parser`, respectively:

```shell
git clone https://github.com/spdx/spdx-3-model.git
git clone https://github.com/spdx/spdx-spec.git
git clone https://github.com/spdx/spec-parser.git
```

Install prerequisites for Python:

```shell
pip3 install -r spdx-spec/requirements.txt
pip3 install -r spec-parser/requirements.txt
```

### Generating formatted Markdown files for MkDocs

Model files in `spdx/spdx-3-model` repo are written in a specific format of
Markdown, with a limited set of allowed headings. The `spec-parser` processes
these model files to generate both ontology and final Markdown files suitable
for MkDocs.

The `spec-parser` also performs automatic formatting on the resulting Markdown
files. For instance, it converts a list under the "Properties" heading into a
table.

To check the model files and generate formatted files for MkDocs, run the
following command:

```shell
python3 spec-parser/main.py spdx-3-model/model spdx-spec/docs/model
```

This will create well-formatted model files in the `spdx-spec/docs/model/`
directory. This directory contains two components:

- Model ontology and diagram files: These files (`model.plantuml`,
`spdx-context.jsonld`, `spdx-model.dot`, `spdx-model.json-ld`,
`spdx-model.pretty-xml`, `spdx-model.ttl`, `spdx-model.xml`)
are ready for immediate use.
- Formatted Makdown files: These files (`.md` extension) are located in various
subdirectories and are intended for processing by MkDocs in the next step.

### Building HTML

With all spec and model files prepared, we will use MkDocs to assemble them
into a website.

In side `spdx-spec/` directory, execute a built-in dev-server that let you
preview the specification:

```shell
mkdocs serve
```

Or building a static HTML site:

```shell
mkdocs build
```

## Configuring the website

Inside `spdx-spec/` directory, there is a file `mkdocs.yml`. This is a
configuration file for MkDocs.

Files intended for display and linking in the navigation bar should be
included in the `nav:` section. The order of filenames in this section
determines their order on the navigation bar.

## Specifications on spdx.github.io/spdx-spec/

The SPDX specifications on <https://spdx.github.io/spdx-spec/> are built
by using a workflow in
[`.github/workflows/publish_v3.yml`](/.github/workflows/publish_v3.yml).
This workflow uses [mike](https://github.com/jimporter/mike) to deploy multiple
versions of MkDocs-powered documentation.

Deployed versions, their titles, and their aliases, can be seen in the file
[versions.json](https://github.com/spdx/spdx-spec/blob/gh-pages/versions.json)
in the `gh-pages` branch.

mike is not required for local testing of a specific version of the
specification.

0 comments on commit f237713

Please sign in to comment.