Skip to content

Commit 91f1f1a

Browse files
jkowalleckjkowalleck
authored
Docs: render sphinx (#1028)
 Signed-off-by: Jan Kowalleck <[email protected]>
1 parent 4eade7e commit 91f1f1a

File tree

15 files changed

+276
-6
lines changed

15 files changed

+276
-6
lines changed

‎.readthedocs.yaml‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Read the Docs configuration file for Sphinx projects
2+
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
3+
4+
# Required
5+
version: 2
6+
7+
# Set the OS, Python version and other tools you might need
8+
build:
9+
os: ubuntu-22.04
10+
tools:
11+
python: "3.12"
12+
nodejs: "20"
13+
# You can also specify other tool versions:
14+
# rust: "1.70"
15+
# golang: "1.20"
16+
jobs:
17+
pre_build:
18+
- npm i --ignore-scripts --include=optional
19+
- npm run api-doc
20+
21+
# Build documentation in the docs/ directory with Sphinx
22+
sphinx:
23+
configuration: docs/conf.py
24+
25+
# Formats
26+
formats:
27+
- htmlzip
28+
29+
# Optionally declare the Python requirements required to build your docs
30+
python:
31+
install:
32+
- requirements: docs/requirements.txt

‎README.md‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
# CycloneDX JavaScript Library
22

33
[![shield_npm-version]][link_npm]
4+
[![shield_rtfd]][link_rtfd]
45
[![shield_gh-workflow-test]][link_gh-workflow-test]
56
[![shield_coverage]][link_codacy]
67
[![shield_ossf-best-practices]][link_ossf-best-practices]
@@ -173,8 +174,9 @@ bom.metadata.component.dependencies.add(componentA.bomRef)
173174

174175
## API documentation
175176

176-
There is no pre-rendered documentation at the time.
177-
Instead, there are annotated type definitions, so that your IDE and tools may pick up the documentation when you use this library downstream.
177+
We ship annotated type definitions, so that your IDE and tools may pick up the documentation when you use this library downstream.
178+
179+
There are also pre-rendered documentations hosted on [readthedocs][link_rtfd].
178180

179181
Additionally, there is a prepared set of configs for [TypeDoc](https://typedoc.org), so that you can build the API documentation from source via `npm run api-doc`.
180182

@@ -193,8 +195,10 @@ See the [LICENSE][license_file] file for the full license.
193195
[license_file]: https://github.com/CycloneDX/cyclonedx-javascript-library/blob/main/LICENSE
194196
[contributing_file]: https://github.com/CycloneDX/cyclonedx-javascript-library/blob/main/CONTRIBUTING.md
195197
[examples]: https://github.com/CycloneDX/cyclonedx-javascript-library/tree/main/examples/README.md
198+
[link_rtfd]: https://cyclonedx-javascript-library.readthedocs.io
196199

197200
[shield_npm-version]: https://img.shields.io/npm/v/@cyclonedx/cyclonedx-library?logo=npm&logoColor=white "npm"
201+
[shield_rtfd]: https://img.shields.io/readthedocs/cyclonedx-javascript-library?logo=readthedocs&logoColor=white "Read the Docs"
198202
[shield_gh-workflow-test]: https://img.shields.io/github/actions/workflow/status/CycloneDX/cyclonedx-javascript-library/nodejs.yml?branch=main&logo=GitHub&logoColor=white "tests"
199203
[shield_coverage]: https://img.shields.io/codacy/coverage/ae6c086b53d54653ad5077b12ec22264?logo=Codacy&logoColor=white "test coverage"
200204
[shield_ossf-best-practices]: https://img.shields.io/cii/level/7883?label=OpenSSF%20best%20practices "OpenSSF best practices"
@@ -206,6 +210,7 @@ See the [LICENSE][license_file] file for the full license.
206210

207211
[link_website]: https://cyclonedx.org/
208212
[link_npm]: https://www.npmjs.com/package/@cyclonedx/cyclonedx-library
213+
209214
[link_gh-workflow-test]: https://github.com/CycloneDX/cyclonedx-javascript-library/actions/workflows/nodejs.yml?query=branch%3Amain
210215
[link_codacy]: https://app.codacy.com/gh/CycloneDX/cyclonedx-javascript-library/dashboard
211216
[link_ossf-best-practices]: https://www.bestpractices.dev/projects/7883

‎docs/.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,2 @@
11
/api/
2+
/_build/

‎docs/Makefile‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = .
9+
BUILDDIR = _build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/api.rst‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
API Reference
2+
=============
3+
4+
For Node
5+
--------
6+
7+
See the rendered `TypeDoc for Node API <api_node/index.html>`_
8+
9+
For Web
10+
-------
11+
12+
See the rendered `TypeDoc for Web API <api_web/index.html>`_
13+

‎docs/changelog.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
.. mdinclude:: ../HISTORY.md

‎docs/conf.py‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
from json import load as json_load
2+
from os.path import dirname, join
3+
4+
5+
project = 'CycloneDX JavaScript Library'
6+
copyright = 'Copyright (c) OWASP Foundation'
7+
author = 'Jan Kowalleck'
8+
9+
with open(join(dirname(__file__), '..', 'package.json'), 'rt') as package:
10+
release = json_load(package)['version']
11+
12+
# -- General configuration ---------------------------------------------------
13+
14+
extensions = [
15+
"sphinx_rtd_theme",
16+
"m2r2"
17+
]
18+
19+
source_suffix = ['.rst', '.md']
20+
21+
22+
23+
# List of patterns, relative to source directory, that match files and
24+
# directories to ignore when looking for source files.
25+
# This pattern also affects html_static_path and html_extra_path.
26+
# see https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-exclude_patterns
27+
exclude_patterns = [
28+
'processes', 'dev', # internal docs
29+
'_build', # build target
30+
'.*', '**/.*', # dotfiles and folders
31+
'Thumbs.db', '**/Thumbs.db',
32+
]
33+
34+
35+
# -- Options for HTML output -------------------------------------------------
36+
37+
# The theme to use for HTML and HTML Help pages. See the documentation for
38+
# a list of builtin themes.
39+
#
40+
html_theme = 'sphinx_rtd_theme'
41+
42+
43+
html_extra_path = ['api']

‎docs/contributing.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
.. mdinclude:: ../CONTRIBUTING.md

‎docs/examples.rst‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
========
2+
Examples
3+
========
4+
5+
For Node
6+
========
7+
8+
JavaScript
9+
----------
10+
11+
JavaScript as CommonJS
12+
^^^^^^^^^^^^^^^^^^^^^^
13+
14+
.. literalinclude:: ../examples/node/javascript/example.cjs
15+
:language: javascript
16+
:linenos:
17+
18+
19+
JavaScript as module
20+
^^^^^^^^^^^^^^^^^^^^
21+
22+
.. literalinclude:: ../examples/node/javascript/example.mjs
23+
:language: javascript
24+
:linenos:
25+
26+
TypeScript
27+
----------
28+
29+
TypeScript for CommonJS
30+
^^^^^^^^^^^^^^^^^^^^^^^
31+
32+
.. literalinclude:: ../examples/node/typescript/example.cjs/src/example.ts
33+
:language: typescript
34+
:linenos:
35+
36+
TypeScript for module
37+
^^^^^^^^^^^^^^^^^^^^^
38+
39+
.. literalinclude:: ../examples/node/typescript/example.mjs/src/example.ts
40+
:language: typescript
41+
:linenos:
42+
43+
For Web
44+
=======
45+
46+
With Parcel
47+
-----------
48+
49+
.. literalinclude:: ../examples/web/parcel/src/app.js
50+
:language: javascript
51+
:linenos:
52+
53+
With webpack
54+
------------
55+
56+
.. literalinclude:: ../examples/web/webpack/src/index.js
57+
:language: javascript
58+
:linenos:

‎docs/index.rst‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
2+
CycloneDX’s JavaScript Library documentation
3+
====================================================
4+
5+
OWASP `CycloneDX`_ is a full-stack Bill of Materials (BOM) standard
6+
that provides advanced supply chain capabilities for cyber risk reduction.
7+
8+
This JavaScript library provides data models, validators and more,
9+
to help you create/render CycloneDX documents.
10+
11+
12+
.. _CycloneDX: https://cyclonedx.org/
13+
.. _CycloneDX Tool Center: https://cyclonedx.org/tool-center/
14+
15+
16+
.. toctree::
17+
:maxdepth: 2
18+
:caption: Contents:
19+
20+
install
21+
examples
22+
contributing
23+
changelog
24+
api

0 commit comments

Comments
 (0)