Skip to content

Commit bade09d

Browse files
MaximilianSoerenPollakMaximilianSoerenPollak
authored
publish documentation to github pages (#55)
1 parent 75db1e9 commit bade09d

20 files changed

+604
-21
lines changed

‎.github/workflows/docs-cleanup.yml

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# *******************************************************************************
2+
# Copyright (c) 2025 Contributors to the Eclipse Foundation
3+
#
4+
# See the NOTICE file(s) distributed with this work for additional
5+
# information regarding copyright ownership.
6+
#
7+
# This program and the accompanying materials are made available under the
8+
# terms of the Apache License Version 2.0 which is available at
9+
# https://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# SPDX-License-Identifier: Apache-2.0
12+
# *******************************************************************************
13+
14+
name: Documentation Cleanup
15+
16+
permissions:
17+
contents: write
18+
pages: write
19+
id-token: write
20+
21+
on:
22+
schedule:
23+
- cron: '0 0 * * *' # Runs every day at midnight UTC
24+
25+
jobs:
26+
docs-cleanup:
27+
uses: eclipse-score/cicd-workflows/.github/workflows/docs-cleanup.yml@main
28+
secrets:
29+
token: ${{ secrets.GITHUB_TOKEN }}

‎.github/workflows/docs.yml

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# *******************************************************************************
2+
# Copyright (c) 2025 Contributors to the Eclipse Foundation
3+
#
4+
# See the NOTICE file(s) distributed with this work for additional
5+
# information regarding copyright ownership.
6+
#
7+
# This program and the accompanying materials are made available under the
8+
# terms of the Apache License Version 2.0 which is available at
9+
# https://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# SPDX-License-Identifier: Apache-2.0
12+
# *******************************************************************************
13+
14+
name: Documentation
15+
16+
permissions:
17+
contents: write
18+
pages: write
19+
pull-requests: write
20+
id-token: write
21+
22+
on:
23+
pull_request_target:
24+
types: [opened, reopened, synchronize] # Allows forks to trigger the docs build
25+
push:
26+
branches:
27+
- main
28+
merge_group:
29+
types: [checks_requested]
30+
31+
jobs:
32+
build-docs:
33+
uses: eclipse-score/cicd-workflows/.github/workflows/docs.yml@main
34+
permissions:
35+
contents: write
36+
pages: write
37+
pull-requests: write
38+
id-token: write
39+
40+
with:
41+
bazel-target: "//docs:github_pages__release"
42+
retention-days: 3

‎docs.bzl

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -178,6 +178,7 @@ def _docs(name = "docs", suffix = "", format = "html", external_needs_deps = lis
178178
srcs = native.glob([
179179
"**/*.png",
180180
"**/*.svg",
181+
"**/*.md",
181182
"**/*.rst",
182183
"**/*.html",
183184
"**/*.css",

‎docs/BUILD

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# *******************************************************************************
2+
# Copyright (c) 2025 Contributors to the Eclipse Foundation
3+
#
4+
# See the NOTICE file(s) distributed with this work for additional
5+
# information regarding copyright ownership.
6+
#
7+
# This program and the accompanying materials are made available under the
8+
# terms of the Apache License Version 2.0 which is available at
9+
# https://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# SPDX-License-Identifier: Apache-2.0
12+
# *******************************************************************************
13+
14+
load("@aspect_rules_py//py:defs.bzl", "py_library")
15+
load("//:docs.bzl", "docs")
16+
17+
# Creates all documentation targets:
18+
# - `docs:incremental` for building docs incrementally at runtime
19+
# - `docs:live_preview` for live preview in the browser without an IDE
20+
# - `docs:ide_support` for creating python virtualenv for IDE support
21+
# - `docs:docs` for building documentation at build-time
22+
23+
docs(
24+
conf_dir = "docs",
25+
docs_targets = [
26+
{
27+
"suffix": "latest", # latest main branch documentation build
28+
"external_needs_info": [
29+
{
30+
"base_url": "https://eclipse-score.github.io/score/main",
31+
"json_url": "https://eclipse-score.github.io/score/main/needs.json",
32+
"id_prefix": "score_",
33+
},
34+
],
35+
},
36+
{
37+
"suffix": "release", # The version imported from MODULE.bazel
38+
"target": ["@score_platform//docs:docs_needs"],
39+
"external_needs_info": [
40+
{
41+
"base_url": "https://eclipse-score.github.io/score/main",
42+
"json_path": "/score_platform~/docs/docs_needs/_build/needs/needs.json",
43+
"id_prefix": "score_",
44+
},
45+
],
46+
},
47+
],
48+
source_dir = "docs",
49+
source_files_to_scan_for_needs_links = [
50+
"//src:score_extension_files",
51+
],
52+
)

‎docs/conf.py

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# *******************************************************************************
2+
# Copyright (c) 2025 Contributors to the Eclipse Foundation
3+
#
4+
# See the NOTICE file(s) distributed with this work for additional
5+
# information regarding copyright ownership.
6+
#
7+
# This program and the accompanying materials are made available under the
8+
# terms of the Apache License Version 2.0 which is available at
9+
# https://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# SPDX-License-Identifier: Apache-2.0
12+
# *******************************************************************************
13+
14+
# Configuration file for the Sphinx documentation builder.
15+
#
16+
# For the full list of built-in configuration values, see the documentation:
17+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
18+
19+
20+
# -- Project information -----------------------------------------------------
21+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
22+
23+
project = "Score Docs-as-Code"
24+
author = "S-CORE"
25+
version = "0.1"
26+
27+
# -- General configuration ---------------------------------------------------
28+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
29+
30+
31+
extensions = [
32+
"sphinx_design",
33+
"sphinx_needs",
34+
"myst_parser",
35+
"sphinxcontrib.plantuml",
36+
"score_plantuml",
37+
"score_metamodel",
38+
"score_draw_uml_funcs",
39+
"score_source_code_linker",
40+
"score_layout",
41+
]
42+
43+
exclude_patterns = [
44+
# The following entries are not required when building the documentation via 'bazel
45+
# build //docs:docs', as that command runs in a sandboxed environment. However, when
46+
# building the documentation via 'bazel run //docs:incremental' or esbonio, these
47+
# entries are required to prevent the build from failing.
48+
"bazel-*",
49+
".venv_docs",
50+
]
51+
52+
# Enable markdown rendering
53+
source_suffix = {
54+
".rst": "restructuredtext",
55+
".md": "markdown",
56+
}
57+
58+
templates_path = ["templates"]
59+
60+
61+
# Enable numref
62+
numfig = True

‎src/extensions/score_source_code_linker/data_flow.png renamed to ‎docs/docs-as-code/extensions/data_flow.png

File renamed without changes.

‎src/extensions/README.md renamed to ‎docs/docs-as-code/extensions/extension_guide.md

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
(extension-guide)=
12
# Guide to Creating a Sphinx Extension
23

34
This document will help you with the most important building blocks and provide all information needed to start writing your own Sphinx extension in the S-CORE project.
@@ -118,13 +119,13 @@ To create a Sphinx testing app, you need the same components as a normal Sphinx
118119
In addition, you can provide anything else that you might need to test your specific extension.
119120

120121

121-
For examples on how to use and implement the sphinx testing app, you can check out the [source code linker](docs/_tooling/score_source_code_linker/tests)
122+
For examples on how to use and implement the sphinx testing app, you can check out the [source code linker](https://github.com/eclipse-score/docs-as-code/tree/main/src/extensions/score_source_code_linker/)
122123

123-
Find everything related to testing within Bazel and how to add your test suite to it, [see here](/tools/testing/pytest/README.md)
124+
Find everything related to testing within Bazel and how to add your test suite to it, [see here](https://github.com/eclipse-score/tooling/blob/main/python_basics/score_pytest/README.md)
124125

125126
Also look at already built extensions inside S-CORE. They can be found in their respective folders:
126-
- [score_metamodel](/docs/_tooling/extensions/score_metamodel/README.md)
127-
- [score_draw_uml_funcs](/docs/_tooling/extensions/score_draw_uml_funcs/__init__.py)
127+
- [score_metamodel](https://github.com/eclipse-score/docs-as-code/tree/main/src/extensions/score_metamodel)
128+
- [score_draw_uml_funcs](https://github.com/eclipse-score/docs-as-code/tree/main/src/extensions/score_draw_uml_funcs)
128129

129130
## Further Resources
130131

‎src/extensions/score_header_service/README.md renamed to ‎docs/docs-as-code/extensions/header_service.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
(header-service)=
12
# Automatic Header Generation Service
23

34
## Purpose

‎docs/docs-as-code/extensions/index.rst

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
.. # *******************************************************************************
2+
# Copyright (c) 2025 Contributors to the Eclipse Foundation
3+
#
4+
# See the NOTICE file(s) distributed with this work for additional
5+
# information regarding copyright ownership.
6+
#
7+
# This program and the accompanying materials are made available under the
8+
# terms of the Apache License Version 2.0 which is available at
9+
# https://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# SPDX-License-Identifier: Apache-2.0
12+
# *******************************************************************************
13+
14+
.. _extensions:
15+
16+
17+
==========
18+
Extensions
19+
==========
20+
21+
Hello there
22+
23+
24+
.. grid:: 1 1 3 3
25+
:class-container: score-grid
26+
27+
.. grid-item-card::
28+
29+
Metamodel
30+
^^^
31+
Learn more about our Metamodel extension and what this extension takes care of.
32+
:ref:`Metamodel Extension<metamodel>`.
33+
34+
.. grid-item-card::
35+
36+
Header Service
37+
^^^
38+
Learn about the Header Service extension, and how you can configure it.
39+
It creates RST Tables and automatically fills our information needed.
40+
:ref:`Header Service Extension <header-service>`
41+
42+
.. grid-item-card::
43+
44+
Source Code Linker
45+
^^^
46+
Learn about the Source Code Linker extension, and how you can configure it.
47+
It enables the possibility to link source code to requirements.
48+
:ref:`Source Code Linker Extension <source-code-linker>`
49+
50+
.. grid-item-card::
51+
52+
RST Filebased testing
53+
^^^
54+
A new testing approach that we have integrated. It makes it easy to ensure that the metamodel and it's checks
55+
work as intended. Create new checks simply by writing RST files.
56+
Head over to :ref:`File Based Testing <file-based-testing>` to learn more.
57+
58+
.. grid-item-card::
59+
60+
Extension Guide
61+
^^^
62+
Want to learn how to write your own sphinx extension, or see how others have done it?
63+
Head over to :ref:`Building an Extension<extension-guide>` to dive in.
64+
65+
66+
67+
.. toctree::
68+
:maxdepth: 1
69+
:caption: Contents:
70+
71+
Metamodel <metamodel>
72+
Filebased Testing <rst_filebased_testing>
73+
Header Service <header_service>
74+
Source Code Linker <source_code_linker>
75+
Extension Guide <extension_guide>

‎src/extensions/score_metamodel/README.md renamed to ‎docs/docs-as-code/extensions/metamodel.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,10 @@
1+
(metamodel)=
12
# score_metamodel
23

34
This extension provides the Metamodel and corresponding checks of the SCORE
45
project as a Sphinx extension.
56

6-
See [../README](../README.md) for more information on why we use extensions.
7+
See [Getting started](../getting_started) for more information on why we use extensions.
78

89
## Naming
910

‎src/extensions/score_metamodel/tests/README.md renamed to ‎docs/docs-as-code/extensions/rst_filebased_testing.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
(file-based-testing)=
12
# File based rule checks
23

34
## Test Function

‎src/extensions/score_source_code_linker/README.md renamed to ‎docs/docs-as-code/extensions/source_code_linker.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
(source-code-linker)=
12
# Source Link Extension Details
23

34
A Sphinx extension for source code traceability for requirements. This extension works with the Bazel system and Sphinx-needs to provide automatic source code traceability.

‎README.md renamed to ‎docs/docs-as-code/getting_started.md

Lines changed: 13 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Score-Docs-As-Code Module
1+
(getting_started)=
2+
# Using Docs-As-Code
3+
24

35
A Bazel module providing tools and extensions to enable and simplify documentation building via Sphinx
46

@@ -23,7 +25,7 @@ This module allows you to easily integrate Sphinx documentation generation into
2325
Add the module to your `MODULE.bazel` file:
2426

2527
```starlark
26-
bazel_dep(name = "score_docs_as_code", version = "0.2.5")
28+
bazel_dep(name = "score_docs_as_code", version = "0.2.7")
2729
```
2830

2931
And make sure to also add the S-core Bazel registry to your `.bazelrc` file
@@ -93,7 +95,7 @@ bazel build //path/to/BUILD-file:docs_latest # documentation at 'bazel-bin/
9395
<br>
9496
<br>
9597

96-
> ### *For the full example as well as more complex ones, check out the [examples directory](examples/)*
98+
> ### *For the full example as well as more complex ones, check out the {doc}`example <../example/index>`
9799
98100
---
99101

@@ -129,37 +131,37 @@ The `docs()` macro accepts the following arguments:
129131
| `visibility` | Bazel visibility | No | `None` |
130132

131133
---
132-
---
134+
133135

134136
## Available Extensions
135137
This module includes several custom Sphinx extensions to enhance your documentation:
136138

137139
### Score Layout Extension
138140

139-
Custom layout options for Sphinx HTML output.
140-
[Learn more](src/extensions/score_layout/README.md)
141+
Custom layout options for Sphinx HTML output are defined in `score_layout`
142+
<README missing>
141143

142144
### Score Header Service
143145

144146
Consistent header styling across documentation pages.
145-
[Learn more](src/extensions/score_header_service/README.md)
147+
{doc}`Learn more <extensions/header_service>`
146148

147149
### Score Metamodel
148150

149151
Validation and checking of documentation structure against a defined Metamodel.
150-
[Learn more](src/extensions/score_metamodel/README.md)
152+
{doc}`Learn more <extensions/metamodel>`
151153

152154
### Score Source Code Linker
153155

154156
Links between requirements documentation and source code implementations.
155-
[Learn more](src/extensions/score_source_code_linker/README.md)
157+
{doc}`Learn more <extensions/source_code_linker.md>
156158

157159
### Score PlantUML
158160

159161
Integration with PlantUML for generating diagrams.
160-
[Learn more](src/extensions/README.md)
162+
<README missing>
161163

162164
### Score Draw UML Functions
163165

164166
Helper functions for creating UML diagrams.
165-
[Learn more](src/extensions/score_draw_uml_funcs/README.md)
167+
<README missing>

0 commit comments

Comments
 (0)