Skip to content

Commit 746b65a

Browse files
rafaelfsilvarafaelfsilva
authored
Merge pull request #133 from wfcommons/improved-docs
Improved docs
2 parents c54975a + c367644 commit 746b65a

12 files changed

Lines changed: 665 additions & 158 deletions

‎README.md‎

Lines changed: 42 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -6,52 +6,64 @@
66
[![Codecov][cov-badge]][cov-link] 
77
[![Downloads](https://static.pepy.tech/personalized-badge/wfcommons?period=total&units=international_system&left_color=grey&right_color=yellowgreen&left_text=Downloads)](https://pepy.tech/project/wfcommons)
88

9-
<a href="https://wfcommons.org" target="_blank"><img src="https://wfcommons.org/images/wfcommons-horizontal.png" width="350" /></a>
10-
<br/>_A Framework for Enabling Scientific Workflow Research and Development_
9+
<a href="https://wfcommons.org" target="_blank"><img src="https://wfcommons.org/images/wfcommons-logo-white.png" width="350" /></a>
10+
<br/>An open-source ecosystem of workflow execution instances, synthetic workflow generators, and benchmark specifications. It helps the community study scheduling, performance, resilience, and emerging AI-driven workflow automation on modern distributed and HPC platforms.
1111

12-
This Python package provides a collection of tools for:
12+
- **Real instances:** Workflow executions curated in a common JSON format (WfFormat).
13+
- **Synthetic realism:** Generate realistic workflows from real traces.
14+
- **Benchmarks:** Produce executable specs for repeatable experiments and fair comparisons.
1315

14-
- Analyzing instances of actual workflow executions;
15-
- Producing recipes structures for creating workflow recipes for workflow generation;
16-
- Generating synthetic realistic workflow instances; and
17-
- Generating realistic workflow benchmark specifications.
16+
Quick links: [Documentation](https://wfcommons.readthedocs.io/en/latest/) · [Website](https://wfcommons.org) · [GitHub Issues](https://github.com/wfcommons/wfcommons/issues)
1817

19-
[![Open In Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/wfcommons/wfcommons/tree/main)
18+
## Quickstart
2019

21-
## Installation
20+
WfCommons requires Python 3.11+ and has been tested on Linux and macOS.
2221

23-
WfCommons is available on [PyPI](https://pypi.org/project/wfcommons).
24-
WfCommons requires Python3.11+ and has been tested on Linux and MacOS.
22+
```
23+
python3 -m venv .venv
24+
source .venv/bin/activate
25+
python3 -m pip install wfcommons
26+
```
2527

26-
### Installation using pip
28+
Generate a synthetic workflow in a few lines:
2729

28-
While `pip` can be used to install WfCommons, we suggest the following
29-
approach for reliable installation when many Python environments are available:
30+
```python
31+
import pathlib
32+
from wfcommons.wfchef.recipes import SeismologyRecipe
33+
from wfcommons import WorkflowGenerator
3034

31-
```
32-
$ python3 -m pip install wfcommons
35+
generator = WorkflowGenerator(SeismologyRecipe.from_num_tasks(250))
36+
workflow = generator.build_workflow()
37+
workflow.write_json(pathlib.Path("seismology-workflow.json"))
3338
```
3439

35-
### Retrieving the latest unstable version
40+
Next steps:
3641

37-
If you want to use the latest WfCommons unstable version, that will contain
38-
brand new features (but also contain bugs as the stabilization work is still
39-
underway), you may consider retrieving the latest unstable version.
42+
- Learn how to build recipes in the [WfChef guide](https://wfcommons.readthedocs.io/en/latest/generating_workflows_recipe.html).
43+
- Generate larger workflow families in the [WfGen guide](https://wfcommons.readthedocs.io/en/latest/generating_workflows.html).
44+
- Produce benchmark specs in the [WfBench guide](https://wfcommons.readthedocs.io/en/latest/generating_workflow_benchmarks.html).
4045

41-
Cloning from [WfCommons's GitHub](https://github.com/wfcommons/wfcommons)
42-
repository:
46+
## Installation
47+
48+
WfCommons is available on [PyPI](https://pypi.org/project/wfcommons).
49+
50+
```
51+
python3 -m pip install wfcommons
52+
```
53+
54+
### Installing from source (latest)
4355

4456
```
45-
$ git clone https://github.com/wfcommons/wfcommons
46-
$ cd wfcommons
47-
$ pip install .
57+
git clone https://github.com/wfcommons/wfcommons
58+
cd wfcommons
59+
python3 -m pip install .
4860
```
4961

5062
### Optional Requirements
5163

5264
#### Graphviz
53-
WfCommons uses _pygraphviz_ for generating visualizations for the workflow task graph.
54-
If you want to enable this feature, you will have to install the
65+
WfCommons uses _pygraphviz_ for generating visualizations for the workflow task graph.
66+
If you want to enable this feature, you will have to install the
5567
[graphviz](https://www.graphviz.org/) package (version 2.16 or later).
5668
You can install graphviz easily on Linux with your favorite package manager,
5769
for example for Debian-based distributions:
@@ -82,15 +94,14 @@ python3 -m pip install pydot
8294

8395
## Get in Touch
8496

85-
The main channel to reach the WfCommons team is via the support email:
97+
The main channel to reach the WfCommons team is via the support email:
8698
[support@wfcommons.org](mailto:support@wfcommons.org).
8799

88-
**Bug Report / Feature Request:** our preferred channel to report a bug or request a feature is via
100+
**Bug Report / Feature Request:** our preferred channel to report a bug or request a feature is via
89101
WfCommons's [Github Issues Track](https://github.com/wfcommons/wfcommons/issues).
90102

91-
92103
## Citing WfCommons
93-
When citing WfCommons, please use the following paper. You should also actually read
104+
When citing WfCommons, please use the following paper. You should also actually read
94105
that paper, as it provides a recent and general overview on the framework.
95106

96107
```

‎docs/requirements.txt‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
sphinx>=5.3.0
2+
furo>=2024.5.6
23
sphinx_rtd_theme>=1.2.0
34
recommonmark>=0.7.1
45
jsonschema~=3.2.0
@@ -12,4 +13,4 @@ setuptools>=49.3.1
1213
pyyaml>=5.3.1
1314
pandas>=1.2.4
1415
stringcase>=1.2.0
15-
filelock>=3.6.0
16+
filelock>=3.6.0

‎docs/source/_static/css/custom.css‎

Lines changed: 248 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,248 @@
1+
:root {
2+
--content-max-width: 72rem;
3+
--sidebar-width: 18rem;
4+
--color-background-primary: #f7f6f2;
5+
--color-background-secondary: #f0efe9;
6+
--color-sidebar-background: #f0efe9;
7+
--color-background-hover: #e9ecf2;
8+
--color-background-border: #e1e4ee;
9+
--color-brand-primary: #1f5eff;
10+
--color-brand-content: #1a55e6;
11+
--color-foreground-primary: #16181d;
12+
--color-foreground-secondary: #4b5563;
13+
--accent-warm: #ff7a59;
14+
--accent-mint: #22c997;
15+
--accent-sky: #4cc9f0;
16+
--accent-violet: #9b5de5;
17+
color-scheme: light;
18+
}
19+
20+
article h1 {
21+
letter-spacing: -0.01em;
22+
}
23+
24+
article h2 {
25+
letter-spacing: -0.005em;
26+
}
27+
28+
body {
29+
background:
30+
radial-gradient(1200px 600px at 10% -10%, rgba(155, 93, 229, 0.12), transparent 60%),
31+
radial-gradient(900px 500px at 90% -15%, rgba(76, 201, 240, 0.15), transparent 55%),
32+
radial-gradient(700px 400px at 50% 110%, rgba(34, 201, 151, 0.12), transparent 60%),
33+
var(--color-background-primary);
34+
}
35+
36+
.sidebar-drawer,
37+
.sidebar-container,
38+
.toc-drawer,
39+
.page-sidebar,
40+
.sidebar-tree {
41+
background: var(--color-sidebar-background);
42+
}
43+
44+
.content {
45+
background: transparent;
46+
}
47+
48+
/* Ensure any theme variant still uses the light palette. */
49+
html[data-theme="dark"],
50+
html[data-theme="auto"],
51+
body[data-theme="dark"],
52+
body[data-theme="auto"] {
53+
color-scheme: light;
54+
}
55+
56+
html[data-theme="dark"],
57+
html[data-theme="auto"],
58+
body[data-theme="dark"],
59+
body[data-theme="auto"] {
60+
--color-background-primary: #f7f6f2;
61+
--color-background-secondary: #f0efe9;
62+
--color-sidebar-background: #f0efe9;
63+
--color-background-hover: #e9ecf2;
64+
--color-background-border: #e1e4ee;
65+
--color-brand-primary: #1f5eff;
66+
--color-brand-content: #1a55e6;
67+
--color-foreground-primary: #16181d;
68+
--color-foreground-secondary: #4b5563;
69+
--accent-warm: #ff7a59;
70+
--accent-mint: #22c997;
71+
--accent-sky: #4cc9f0;
72+
--accent-violet: #9b5de5;
73+
}
74+
75+
body[data-theme="dark"],
76+
body[data-theme="auto"] {
77+
background:
78+
radial-gradient(1200px 600px at 10% -10%, rgba(155, 93, 229, 0.12), transparent 60%),
79+
radial-gradient(900px 500px at 90% -15%, rgba(76, 201, 240, 0.15), transparent 55%),
80+
radial-gradient(700px 400px at 50% 110%, rgba(34, 201, 151, 0.12), transparent 60%),
81+
var(--color-background-primary);
82+
}
83+
84+
body[data-theme="dark"] .sidebar-drawer,
85+
body[data-theme="auto"] .sidebar-drawer,
86+
body[data-theme="dark"] .sidebar-container,
87+
body[data-theme="auto"] .sidebar-container,
88+
body[data-theme="dark"] .toc-drawer,
89+
body[data-theme="auto"] .toc-drawer,
90+
body[data-theme="dark"] .page-sidebar,
91+
body[data-theme="auto"] .page-sidebar,
92+
body[data-theme="dark"] .sidebar-tree,
93+
body[data-theme="auto"] .sidebar-tree,
94+
body[data-theme="dark"] .mobile-header,
95+
body[data-theme="auto"] .mobile-header {
96+
background: var(--color-sidebar-background);
97+
}
98+
99+
/* Never show dark-only elements. */
100+
.only-dark {
101+
display: none !important;
102+
}
103+
104+
article {
105+
background:
106+
linear-gradient(180deg, rgba(255, 255, 255, 0.85), rgba(255, 255, 255, 0.92));
107+
border: 1px solid var(--color-background-border);
108+
border-radius: 20px;
109+
box-shadow: 0 24px 48px rgba(19, 25, 39, 0.08);
110+
padding: 2.25rem 2.5rem;
111+
}
112+
113+
article h1 {
114+
color: #0f172a;
115+
}
116+
117+
article h1::after {
118+
content: "";
119+
display: block;
120+
width: 72px;
121+
height: 6px;
122+
margin-top: 0.5rem;
123+
border-radius: 999px;
124+
background: linear-gradient(90deg, var(--accent-warm), var(--accent-sky), var(--accent-mint));
125+
}
126+
127+
article h2 {
128+
color: #1e293b;
129+
}
130+
131+
article h3 {
132+
color: #1f2937;
133+
}
134+
135+
article a {
136+
color: var(--color-brand-primary);
137+
font-weight: 600;
138+
}
139+
140+
article a:hover {
141+
color: var(--accent-violet);
142+
}
143+
144+
code,
145+
pre {
146+
background: #eef2ff;
147+
border-color: #d8def2;
148+
}
149+
150+
pre {
151+
box-shadow: inset 0 0 0 1px rgba(26, 85, 230, 0.08);
152+
}
153+
154+
.sidebar-tree .current > a {
155+
background: rgba(26, 85, 230, 0.08);
156+
border-radius: 8px;
157+
}
158+
159+
.sidebar-tree a:hover {
160+
background: rgba(34, 201, 151, 0.12);
161+
border-radius: 8px;
162+
}
163+
164+
.toc-drawer .toc-tree li > a,
165+
.toc-tree li > a {
166+
border-radius: 8px;
167+
}
168+
169+
.toc-tree li > a:hover {
170+
background: rgba(76, 201, 240, 0.14);
171+
}
172+
173+
table {
174+
border-radius: 12px;
175+
overflow: hidden;
176+
box-shadow: 0 12px 24px rgba(15, 23, 42, 0.08);
177+
}
178+
179+
th {
180+
background: rgba(31, 94, 255, 0.08);
181+
}
182+
183+
hr {
184+
border: none;
185+
height: 1px;
186+
background: linear-gradient(90deg, transparent, rgba(31, 94, 255, 0.3), transparent);
187+
}
188+
189+
/* Hide heading link glyphs while keeping the anchor element. */
190+
.headerlink {
191+
color: transparent !important;
192+
text-decoration: none !important;
193+
font-size: 0 !important;
194+
width: 0;
195+
margin-left: 0;
196+
}
197+
198+
.headerlink::before {
199+
content: "";
200+
}
201+
202+
/* Force light palette even if the theme requests dark mode. */
203+
html[data-theme="dark"],
204+
html[data-theme="dark"] body,
205+
html[data-theme="auto"],
206+
html[data-theme="auto"] body {
207+
--color-background-primary: #f7f6f2;
208+
--color-background-secondary: #f0efe9;
209+
--color-sidebar-background: #f0efe9;
210+
--color-background-hover: #e9ecf2;
211+
--color-background-border: #e1e4ee;
212+
--color-brand-primary: #1f5eff;
213+
--color-brand-content: #1a55e6;
214+
--color-foreground-primary: #16181d;
215+
--color-foreground-secondary: #4b5563;
216+
--accent-warm: #ff7a59;
217+
--accent-mint: #22c997;
218+
--accent-sky: #4cc9f0;
219+
--accent-violet: #9b5de5;
220+
color-scheme: light;
221+
}
222+
223+
html[data-theme="dark"] body,
224+
html[data-theme="auto"] body {
225+
background:
226+
radial-gradient(1200px 600px at 10% -10%, rgba(155, 93, 229, 0.12), transparent 60%),
227+
radial-gradient(900px 500px at 90% -15%, rgba(76, 201, 240, 0.15), transparent 55%),
228+
radial-gradient(700px 400px at 50% 110%, rgba(34, 201, 151, 0.12), transparent 60%),
229+
var(--color-background-primary);
230+
}
231+
232+
/* Hide the theme toggle UI entirely. */
233+
.theme-toggle,
234+
.theme-toggle-container,
235+
.theme-toggle-container button {
236+
display: none !important;
237+
}
238+
239+
/* Hide project title text in the sidebar, keep the logo visible. */
240+
.sidebar-brand-text,
241+
.sidebar-brand .brand-text,
242+
.sidebar-brand .title {
243+
display: none !important;
244+
}
245+
246+
article .align-left {
247+
float: none !important
248+
}

0 commit comments

Comments
 (0)