Skip to content

Commit 88c596f

Browse files
AlexanderLaninAlexanderLanin
authored
move docs/_tooling from the score repository
Preserved all commits regarding the moved folders. The original full history is under: https://github.com/eclipse-score/score/commits/1adb7f5917ab1b2c1d60082e65db308ba821d3ca/docs/_tooling
2 parents b9b8583 + db9da3b commit 88c596f

60 files changed

Lines changed: 9475 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎tooling/docs/_tooling/README.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
# S-CORE Project Tooling Development Guide
2+
3+
*This document is meant for *developers* of the `_tooling` of docs in the score repository.*
4+
It should be treated as a 'get-started' guide, giving you all needed information to get up and running.
5+
6+
## Quick Start
7+
8+
1. Clone the repository
9+
2. Setup the environment
10+
- *No Devcontainer*
11+
1. Install Bazelisk (version manager for Bazel)
12+
2. Create the Python virtual environment:
13+
```bash
14+
bazel run //docs:ide_support
15+
```
16+
3. Select `.venv_docs/bin/python` as the python interpreter inside your IDE
17+
*Note: This virtual environment does **not** have pip, therefore `pip install` is not available.*
18+
<br>
19+
20+
- *With Devcontainer (VSCode)*
21+
1. Click the `reopen current folder in dev container` prompt
22+
- If no prompt appears: `ctrl+shift+p` => `Dev Containers: Reopen in Containers`
23+
24+
25+
## Development Environment Requirements
26+
27+
- **Operating System**: Linux (required)
28+
- **Core Tools**:
29+
- Bazel
30+
- Python
31+
- Git
32+
- **VSCode** (Optional)
33+
- Several integrations and guides are development primarily with VS Code in mind.
34+
35+
36+
37+
### Key external tools used inside `_tooling`
38+
39+
1. **Bazel Build System**
40+
- Primary build orchestrator
41+
- Handles dependency management
42+
- Coordinates testing and documentation
43+
- Manages multi-repository setup
44+
45+
2. **Documentation Tools**
46+
- Sphinx with custom extensions
47+
- Esbonio for IDE integration
48+
- Real-time documentation validation
49+
50+
3. **Development Tools**
51+
- Gitlint for commit message standards
52+
- Pytest for testing infrastructure
53+
- Custom formatters and linters
54+
55+
56+
57+
## Tooling Directory Architecture
58+
59+
```
60+
docs/_tooling/
61+
├── assets/ # Documentation styling (CSS)
62+
├── conf_extras/ # Sphinx configuration extensions
63+
├── decision_records/ # Architecture Decision Records (ADRs)
64+
├── extensions/ # Custom Sphinx extensions
65+
│ └── score_metamodel/
66+
│ ├── checks/ # Sphinx-needs validation
67+
│ └── tests/ # Extension test suite
68+
└── templates/ # Documentation templates
69+
```
70+
71+
72+
Find all important bazel commands in the [project README](/README.md)
73+
74+
Find everything related to testing and how to add your on test suite [here](/tools/testing/pytest/README.md)
75+
76+
## Developing new tools
77+
78+
1. Place code in appropriate directory or create new ones. E.g. sphinx-extensions inside `extensions`
79+
2. Create a dedicated test directory
80+
3. Include an appropriate README in markdown
81+
82+
> If you want to develop your own sphinx extension, check out the [extensions guide](/docs/_tooling/extensions/README.md)
83+
84+
## Best Practices
85+
86+
1. **Documentation**
87+
- Keep READMEs up-to-date
88+
- Document architectural decisions in `decision_records/`
89+
- Include examples in extension documentation
90+
91+
2. **Testing**
92+
- Write tests for all new functionality
93+
- Use appropriate test sizes (small/medium/large)
94+
- Include both positive and negative test cases
95+
96+
3. **Code Organization**
97+
- Follow existing directory structure
98+
- Keep extensions modular and focused
99+
- Use consistent naming conventions
100+
101+
## Troubleshooting
102+
103+
Common issues and solutions:
104+
105+
1. **Bazel Build Failures**
106+
- Check Bazel version compatibility
107+
- Verify Python environment
108+
- Review recent changes to BUILD files
109+
110+
2. **Documentation Build Issues**
111+
- Validate Sphinx configuration
112+
- Check for RST syntax errors
113+
- Verify extension dependencies
114+
115+
## Additional Resources
116+
- [Sphinx extension guide](/docs/_tooling/extensions/README.md)
117+
- [S-CORE Metamodel Documentation](/docs/_tooling/extensions/score_metamodel/README.md)
118+
- [Pytest Integration Guide](/tools/testing/pytest/README.md)

‎tooling/docs/_tooling/assets/css/score.css‎

Lines changed: 255 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,255 @@
1+
html {
2+
--pst-font-size-base: 17px;
3+
}
4+
5+
.underline {
6+
text-decoration: underline;
7+
}
8+
9+
/* SCORE specfic colors
10+
A list of available colro variable names for pyData Sphinx Theme can be found at
11+
https://pydata-sphinx-theme.readthedocs.io/en/stable/_downloads/565fbb3ecf2b3048f5fb3953890ba176/_color.scss
12+
13+
The base color is TEAL */
14+
15+
16+
html[data-theme="light"] {
17+
--pst-color-primary: #547980;
18+
--pst-color-secondary: #45ADA8;
19+
--pst-color-accent: #9DE0AD;
20+
--pst-color-target: #E5FCC2;
21+
--pst-color-on-surface: #594F4F;
22+
--pst-color-on-background: var(--pst-color-secondary);
23+
--pst-color-text-muted: #FFFFFF;
24+
--pst-color-table-row-zebra-high-bg: #e6e7e8;
25+
--pst-color-table-row-hover-bg: var(--pst-color-secondary); /*#d7d6d6;*/
26+
}
27+
28+
html[data-theme="dark"] {
29+
--pst-color-primary: #45ADA8;
30+
--pst-color-secondary: #547980;
31+
--pst-color-accent: #9DE0AD;
32+
--pst-color-target: #E5FCC2;
33+
--pst-color-on-surface: #594F4F;
34+
--pst-color-on-background: var(--pst-color-secondary);
35+
--pst-color-text-muted: #FFFFFF;
36+
--pst-color-table-row-zebra-high-bg: #20242b;
37+
--pst-color-table-row-hover-bg: var(--pst-color-secondary); /*#30353e;*/
38+
}
39+
40+
/* Content area size */
41+
/* Docs: https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/layout.html#horizontal-spacing */
42+
.bd-main .bd-content .bd-article-container {
43+
max-width: 100%; /* default is 60em */
44+
}
45+
/* Whole page size */
46+
.bd-page-width {
47+
max-width: 100rem; /* default is 88rem */
48+
}
49+
50+
51+
.search-button-field {
52+
color: var(--pst-color-primary);
53+
}
54+
html .pst-navbar-icon:hover {
55+
border-bottom: max(3px,.1875rem,.12em) solid var(--pst-color-primary) !important;
56+
color: var(--pst-color-primary) !important;
57+
}
58+
59+
.bd-header ul.navbar-nav > li.nav-item.current > .nav-link {
60+
color: var(--pst-color-text-muted) !important;
61+
font-weight: 900 !important;
62+
}
63+
64+
.bd-header ul.navbar-nav > li.nav-item > .nav-link:hover {
65+
color: var(--pst-color-primary);
66+
}
67+
68+
ul.navbar-nav li a {
69+
color: var(--pst-color-primary);
70+
}
71+
72+
.bd-search input.form-control::placeholder,
73+
.bd-search input.form-control {
74+
color: var(--pst-color-primary) !important;
75+
}
76+
77+
/* Right sidebar */
78+
.toc-entry a.nav-link {
79+
color: var(--pst-color-text-base);
80+
}
81+
/* Left, top SCORE brand */
82+
.navbar-brand p
83+
{
84+
color: var(--pst-color-text-muted);
85+
font-weight: 900;
86+
}
87+
.navbar-brand:hover, .navbar-brand:visited:hover {
88+
text-decoration: none;
89+
}
90+
91+
/* GitHub logo for shorten URL */
92+
a.github::before {
93+
content: var(--pst-icon-github);
94+
color: var(--pst-color-text-base);
95+
}
96+
a.github {
97+
text-decoration: none !important;
98+
}
99+
100+
/* Left sidebar links */
101+
nav.bd-links li > a {
102+
color: var(--pst-color-text-base);
103+
}
104+
105+
/* Breadcrumbs, above page content: Link color */
106+
ul.bd-breadcrumbs li.breadcrumb-item a {
107+
color: var(--pst-color-text-base);
108+
text-decoration: none;
109+
}
110+
111+
/* Breadcrumbs, above page content: Arrow color */
112+
ul.bd-breadcrumbs li.breadcrumb-item:not(.breadcrumb-home)::before {
113+
color: var(--pst-color-text-base);
114+
}
115+
/* Next/previous area under content */
116+
.prev-next-area p,
117+
.prev-next-area a {
118+
color: var(--pst-color-text-base);
119+
}
120+
121+
blockquote {
122+
color: var(--pst-color-text-base);
123+
}
124+
125+
.admonition, div.admonition {
126+
background-color: rgba(0,0,0,0.1);
127+
}
128+
129+
/* Left sidebar fix, to hide scrollbar if not needed */
130+
.bd-sidebar-primary .sidebar-primary-items__end {
131+
margin-bottom: 1em;
132+
margin-top: 0;
133+
}
134+
135+
/* Reduce width of left sidebar and set maximum for wide screens */
136+
/* .navbar-header-items__start is the left navbar logo, which needs to */
137+
/* be shorten as well to jkepp the navbar-entries aligned with the content */
138+
.bd-sidebar-primary,
139+
.navbar-header-items__start {
140+
width: 20%; /* default: 25% */
141+
max-width: 350px; /* default: not set */
142+
overflow-x: hidden;
143+
}
144+
145+
@media screen and (max-width: 959px) {
146+
.bd-sidebar-primary,
147+
.navbar-header-items__start {
148+
width: unset;
149+
max-width: 350px; /* default: not set */
150+
overflow-x: hidden;
151+
}
152+
}
153+
154+
/* Less Sidebar border/distance */
155+
.bd-sidebar-primary,
156+
.bd-sidebar-secondary {
157+
padding: 0.5rem 0.2rem 0.2rem;
158+
}
159+
160+
.bd-sidebar-primary li.has-children > details > summary .toctree-toggle {
161+
right: 1em
162+
}
163+
164+
/* SCORE Background video
165+
Source: https://www.imi21.com/background-video-full-screen.php */
166+
167+
div.score_banner {
168+
background-color: var(--pst-color-on-surface);
169+
}
170+
#videowrapper{
171+
position: relative;
172+
overflow: hidden;
173+
margin-bottom: 50px;
174+
}
175+
176+
#fullScreenDiv{
177+
height: 300px;
178+
width: 100%;
179+
padding:0;
180+
margin: 0;
181+
/* background-color: gray;
182+
position: relative; */
183+
container-type: inline-size;
184+
}
185+
186+
#video{
187+
width: 100%;
188+
/* height: auto;
189+
margin: auto;
190+
display: block; */
191+
}
192+
@media (min-aspect-ratio: 16/9) {
193+
#video{
194+
width: 100%;
195+
height:auto;
196+
}
197+
}
198+
199+
#score-title {
200+
width: 100%;
201+
height: 100%;
202+
position: absolute;
203+
top: 0;
204+
left: 0;
205+
display: flex;
206+
justify-content: center;
207+
align-items: center;
208+
flex-direction: column;
209+
color: var(--pst-color-text-base);
210+
/* font-size: 4.5em; */
211+
font-size: 8.0cqw;
212+
font-weight: 900;
213+
margin-bottom: 20px;
214+
/* Is somehow cool with image/video title background */
215+
/*animation: fadeIn 3s; */
216+
}
217+
218+
/* As long as no image or video is shown in
219+
the title, this is not needed, but kept
220+
for future needs */
221+
/* html[data-theme="light"] #score-title {
222+
background-color: rgba(0,0,0,0.3);
223+
}
224+
html[data-theme="dark"] #score-title {
225+
background-color: rgba(0,0,0,0.5);
226+
} */
227+
228+
#score-subtitle {
229+
font-size: 0.4em;
230+
}
231+
232+
#score-phrase {
233+
font-size: 0.3em;
234+
font-weight: 400;
235+
}
236+
237+
#logo_center_drk {
238+
background-color: transparent;
239+
}
240+
241+
@keyframes fadeIn {
242+
0% { opacity: 0; }
243+
100% { opacity: 1; }
244+
}
245+
246+
/* Ensure the version switcher dropdown is scrollable if it exceeds the max height */
247+
.version-switcher__menu {
248+
position: absolute;
249+
width: 100%;
250+
max-height: 300px; /* Adjust this value as needed */
251+
overflow-y: auto;
252+
overflow-x: hidden;
253+
box-sizing: border-box;
254+
}
255+

‎tooling/docs/_tooling/assets/css/score_design.css‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
/* ########################### */
2+
/* SPHINX-DESIGN configs only! */
3+
/* ########################### */
4+
.score-grid a {
5+
color: #FFFFFF;
6+
}
7+
8+
.score-grid .sd-card-header {
9+
background-color: var(--pst-color-secondary) !important;
10+
color: var(--pst-color-text-muted);
11+
font-weight: 900;
12+
font-size: 1.2em;
13+
14+
}
15+
.score-grid .sd-card-body {
16+
text-align: justify;
17+
}
18+
19+
details.sd-dropdown summary.sd-card-header + div.sd-summary-content
20+
{
21+
background-color: transparent;
22+
23+
}

0 commit comments

Comments
 (0)