Skip to content

Commit 2504277

Browse files
pcrespovpcrespov
authored
📝 services.md: autodocs openapi specs and images for each service (#6779)
1 parent 5732a12 commit 2504277

File tree

7 files changed

+202
-39
lines changed

7 files changed

+202
-39
lines changed

‎Makefile‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -595,12 +595,17 @@ settings-schema.json: ## [container] dumps json-schema settings of all services
595595

596596

597597
.PHONY: auto-doc
598-
auto-doc: .stack-simcore-version.yml ## updates diagrams for README.md
598+
auto-doc: .stack-simcore-version.yml ## Auto generates diagrams for README.md
599599
# Parsing docker compose config $< and creating graph
600600
@./scripts/docker-compose-viz.bash $<
601601
# Updating docs/img
602602
@mv --verbose $<.png docs/img/
603603

604+
.PHONY: services.md
605+
services.md: ## Auto generates service.md
606+
# Making $@
607+
scripts/echo_services_markdown.py > $@
608+
604609

605610
.PHONY: postgres-upgrade
606611
postgres-upgrade: ## initalize or upgrade postgres db to latest state

‎scripts/echo_services_markdown.py‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
#!/bin/env python
2+
""" Usage
3+
4+
cd osparc-simcore
5+
./scripts/echo_services_markdown.py >services.md
6+
"""
7+
8+
import itertools
9+
import sys
10+
from collections.abc import Iterable
11+
from datetime import datetime
12+
from operator import attrgetter
13+
from pathlib import Path
14+
from typing import Final, NamedTuple
15+
16+
CURRENT_FILE = Path(sys.argv[0] if __name__ == "__main__" else __file__).resolve()
17+
CURRENT_DIR = CURRENT_FILE.parent
18+
19+
_URL_PREFIX: Final[
20+
str
21+
] = "https://raw.githubusercontent.com/ITISFoundation/osparc-simcore/refs/heads/master"
22+
23+
_REDOC_URL_PREFIX: Final[str] = f"https://redocly.github.io/redoc/?url={_URL_PREFIX}"
24+
_SWAGGER_URL_PREFIX: Final[str] = f"https://petstore.swagger.io/?url={_URL_PREFIX}"
25+
26+
27+
class CaptureTuple(NamedTuple):
28+
service_name: str
29+
file_path: Path
30+
31+
32+
_service_names_aliases: dict[str, str] = {
33+
"web": "webserver",
34+
}
35+
36+
37+
def generate_markdown_table(
38+
*captured_files: Iterable[CaptureTuple],
39+
) -> str:
40+
title = ("Name", "Files", " ")
41+
num_cols = len(title)
42+
lines = ["-" * 10] * num_cols
43+
44+
def _to_row_data(values: Iterable) -> list[str]:
45+
row = list(map(str, values))
46+
assert len(row) == num_cols, f"len({row=}) != {num_cols=}"
47+
return row
48+
49+
rows = [
50+
_to_row_data(title),
51+
_to_row_data(lines),
52+
]
53+
54+
found = itertools.groupby(
55+
sorted(itertools.chain(*captured_files), key=attrgetter("service_name")),
56+
key=attrgetter("service_name"),
57+
)
58+
59+
for name, service_files in found:
60+
rows.append(
61+
_to_row_data(
62+
(
63+
f"**{name.upper()}**",
64+
"",
65+
"",
66+
)
67+
)
68+
)
69+
for _, file_path in service_files:
70+
linked_path = f"[{file_path}](./{file_path})"
71+
72+
# SEE https://shields.io/badges
73+
badges = []
74+
75+
if file_path.stem.lower() == "dockerfile":
76+
repo = _service_names_aliases.get(f"{name}") or name
77+
badges = [
78+
f"[![Docker Image Size](https://img.shields.io/docker/image-size/itisfoundation/{repo})](https://hub.docker.com/r/itisfoundation/{repo}/tags)"
79+
]
80+
81+
elif file_path.stem.lower() == "openapi":
82+
badges = [
83+
f"[![ReDoc](https://img.shields.io/badge/OpenAPI-ReDoc-85ea2d?logo=openapiinitiative)]({_REDOC_URL_PREFIX}/{file_path}) "
84+
f"[![Swagger UI](https://img.shields.io/badge/OpenAPI-Swagger_UI-85ea2d?logo=swagger)]({_SWAGGER_URL_PREFIX}/{file_path})",
85+
]
86+
87+
rows.append(
88+
_to_row_data(
89+
(
90+
"",
91+
linked_path,
92+
" ".join(badges),
93+
)
94+
)
95+
)
96+
rows.append(_to_row_data(["" * 10] * num_cols))
97+
98+
# converts to markdown table
99+
return "\n".join(f"| {'|'.join(r)} |" for r in rows)
100+
101+
102+
if __name__ == "__main__":
103+
104+
repo_base_path = CURRENT_DIR.parent.resolve()
105+
services_path = repo_base_path / "services"
106+
107+
def _to_tuple(file: Path):
108+
return CaptureTuple(
109+
f"{file.relative_to(services_path).parents[-2]}",
110+
file.relative_to(repo_base_path),
111+
)
112+
113+
dockerfiles_found = (_to_tuple(file) for file in services_path.rglob("Dockerfile"))
114+
115+
openapi_files_found = (
116+
_to_tuple(file)
117+
for file in services_path.rglob("openapi.*")
118+
if file.suffix in {".json", ".yaml", ".yml"}
119+
)
120+
121+
markdown_table = generate_markdown_table(
122+
openapi_files_found,
123+
dockerfiles_found,
124+
)
125+
now = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
126+
127+
print("# services")
128+
print(">")
129+
print(f"> Auto generated on `{now}` using ")
130+
print("```cmd")
131+
print("cd osparc-simcore")
132+
print(f"python ./{CURRENT_FILE.relative_to(repo_base_path)}")
133+
print("```")
134+
print(markdown_table)

‎services.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# services
2+
>
3+
> Auto generated on `2024-11-21 10:29:41` using
4+
```cmd
5+
cd osparc-simcore
6+
python ./scripts/echo_services_markdown.py
7+
```
8+
| Name|Files| |
9+
| ----------|----------|---------- |
10+
| **AGENT**|| |
11+
| |[services/agent/Dockerfile](./services/agent/Dockerfile)|[![Docker Image Size](https://img.shields.io/docker/image-size/itisfoundation/agent)](https://hub.docker.com/r/itisfoundation/agent/tags) |
12+
| **API-SERVER**|| |
13+
| |[services/api-server/openapi.json](./services/api-server/openapi.json)|[![ReDoc](https://img.shields.io/badge/OpenAPI-ReDoc-85ea2d?logo=openapiinitiative)](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/ITISFoundation/osparc-simcore/refs/heads/master/services/api-server/openapi.json) [![Swagger UI](https://img.shields.io/badge/OpenAPI-Swagger_UI-85ea2d?logo=swagger)](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/ITISFoundation/osparc-simcore/refs/heads/master/services/api-server/openapi.json) |
14+
| |[services/api-server/Dockerfile](./services/api-server/Dockerfile)|[![Docker Image Size](https://img.shields.io/docker/image-size/itisfoundation/api-server)](https://hub.docker.com/r/itisfoundation/api-server/tags) |
15+
| **AUTOSCALING**|| |
16+
| |[services/autoscaling/Dockerfile](./services/autoscaling/Dockerfile)|[![Docker Image Size](https://img.shields.io/docker/image-size/itisfoundation/autoscaling)](https://hub.docker.com/r/itisfoundation/autoscaling/tags) |
17+
| **CATALOG**|| |
18+
| |[services/catalog/openapi.json](./services/catalog/openapi.json)|[![ReDoc](https://img.shields.io/badge/OpenAPI-ReDoc-85ea2d?logo=openapiinitiative)](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/ITISFoundation/osparc-simcore/refs/heads/master/services/catalog/openapi.json) [![Swagger UI](https://img.shields.io/badge/OpenAPI-Swagger_UI-85ea2d?logo=swagger)](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/ITISFoundation/osparc-simcore/refs/heads/master/services/catalog/openapi.json) |
19+
| |[services/catalog/Dockerfile](./services/catalog/Dockerfile)|[![Docker Image Size](https://img.shields.io/docker/image-size/itisfoundation/catalog)](https://hub.docker.com/r/itisfoundation/catalog/tags) |
20+
| **CLUSTERS-KEEPER**|| |
21+
| |[services/clusters-keeper/Dockerfile](./services/clusters-keeper/Dockerfile)|[![Docker Image Size](https://img.shields.io/docker/image-size/itisfoundation/clusters-keeper)](https://hub.docker.com/r/itisfoundation/clusters-keeper/tags) |
22+
| **DASK-SIDECAR**|| |
23+
| |[services/dask-sidecar/Dockerfile](./services/dask-sidecar/Dockerfile)|[![Docker Image Size](https://img.shields.io/docker/image-size/itisfoundation/dask-sidecar)](https://hub.docker.com/r/itisfoundation/dask-sidecar/tags) |
24+
| **DATCORE-ADAPTER**|| |
25+
| |[services/datcore-adapter/Dockerfile](./services/datcore-adapter/Dockerfile)|[![Docker Image Size](https://img.shields.io/docker/image-size/itisfoundation/datcore-adapter)](https://hub.docker.com/r/itisfoundation/datcore-adapter/tags) |
26+
| **DIRECTOR**|| |
27+
| |[services/director/src/simcore_service_director/api/v0/openapi.yaml](./services/director/src/simcore_service_director/api/v0/openapi.yaml)|[![ReDoc](https://img.shields.io/badge/OpenAPI-ReDoc-85ea2d?logo=openapiinitiative)](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/ITISFoundation/osparc-simcore/refs/heads/master/services/director/src/simcore_service_director/api/v0/openapi.yaml) [![Swagger UI](https://img.shields.io/badge/OpenAPI-Swagger_UI-85ea2d?logo=swagger)](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/ITISFoundation/osparc-simcore/refs/heads/master/services/director/src/simcore_service_director/api/v0/openapi.yaml) |
28+
| |[services/director/Dockerfile](./services/director/Dockerfile)|[![Docker Image Size](https://img.shields.io/docker/image-size/itisfoundation/director)](https://hub.docker.com/r/itisfoundation/director/tags) |
29+
| **DIRECTOR-V2**|| |
30+
| |[services/director-v2/openapi.json](./services/director-v2/openapi.json)|[![ReDoc](https://img.shields.io/badge/OpenAPI-ReDoc-85ea2d?logo=openapiinitiative)](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/ITISFoundation/osparc-simcore/refs/heads/master/services/director-v2/openapi.json) [![Swagger UI](https://img.shields.io/badge/OpenAPI-Swagger_UI-85ea2d?logo=swagger)](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/ITISFoundation/osparc-simcore/refs/heads/master/services/director-v2/openapi.json) |
31+
| |[services/director-v2/Dockerfile](./services/director-v2/Dockerfile)|[![Docker Image Size](https://img.shields.io/docker/image-size/itisfoundation/director-v2)](https://hub.docker.com/r/itisfoundation/director-v2/tags) |
32+
| **DYNAMIC-SCHEDULER**|| |
33+
| |[services/dynamic-scheduler/openapi.json](./services/dynamic-scheduler/openapi.json)|[![ReDoc](https://img.shields.io/badge/OpenAPI-ReDoc-85ea2d?logo=openapiinitiative)](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/ITISFoundation/osparc-simcore/refs/heads/master/services/dynamic-scheduler/openapi.json) [![Swagger UI](https://img.shields.io/badge/OpenAPI-Swagger_UI-85ea2d?logo=swagger)](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/ITISFoundation/osparc-simcore/refs/heads/master/services/dynamic-scheduler/openapi.json) |
34+
| |[services/dynamic-scheduler/Dockerfile](./services/dynamic-scheduler/Dockerfile)|[![Docker Image Size](https://img.shields.io/docker/image-size/itisfoundation/dynamic-scheduler)](https://hub.docker.com/r/itisfoundation/dynamic-scheduler/tags) |
35+
| **DYNAMIC-SIDECAR**|| |
36+
| |[services/dynamic-sidecar/openapi.json](./services/dynamic-sidecar/openapi.json)|[![ReDoc](https://img.shields.io/badge/OpenAPI-ReDoc-85ea2d?logo=openapiinitiative)](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/ITISFoundation/osparc-simcore/refs/heads/master/services/dynamic-sidecar/openapi.json) [![Swagger UI](https://img.shields.io/badge/OpenAPI-Swagger_UI-85ea2d?logo=swagger)](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/ITISFoundation/osparc-simcore/refs/heads/master/services/dynamic-sidecar/openapi.json) |
37+
| |[services/dynamic-sidecar/Dockerfile](./services/dynamic-sidecar/Dockerfile)|[![Docker Image Size](https://img.shields.io/docker/image-size/itisfoundation/dynamic-sidecar)](https://hub.docker.com/r/itisfoundation/dynamic-sidecar/tags) |
38+
| **EFS-GUARDIAN**|| |
39+
| |[services/efs-guardian/Dockerfile](./services/efs-guardian/Dockerfile)|[![Docker Image Size](https://img.shields.io/docker/image-size/itisfoundation/efs-guardian)](https://hub.docker.com/r/itisfoundation/efs-guardian/tags) |
40+
| **INVITATIONS**|| |
41+
| |[services/invitations/openapi.json](./services/invitations/openapi.json)|[![ReDoc](https://img.shields.io/badge/OpenAPI-ReDoc-85ea2d?logo=openapiinitiative)](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/ITISFoundation/osparc-simcore/refs/heads/master/services/invitations/openapi.json) [![Swagger UI](https://img.shields.io/badge/OpenAPI-Swagger_UI-85ea2d?logo=swagger)](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/ITISFoundation/osparc-simcore/refs/heads/master/services/invitations/openapi.json) |
42+
| |[services/invitations/Dockerfile](./services/invitations/Dockerfile)|[![Docker Image Size](https://img.shields.io/docker/image-size/itisfoundation/invitations)](https://hub.docker.com/r/itisfoundation/invitations/tags) |
43+
| **MIGRATION**|| |
44+
| |[services/migration/Dockerfile](./services/migration/Dockerfile)|[![Docker Image Size](https://img.shields.io/docker/image-size/itisfoundation/migration)](https://hub.docker.com/r/itisfoundation/migration/tags) |
45+
| **OSPARC-GATEWAY-SERVER**|| |
46+
| |[services/osparc-gateway-server/Dockerfile](./services/osparc-gateway-server/Dockerfile)|[![Docker Image Size](https://img.shields.io/docker/image-size/itisfoundation/osparc-gateway-server)](https://hub.docker.com/r/itisfoundation/osparc-gateway-server/tags) |
47+
| **PAYMENTS**|| |
48+
| |[services/payments/openapi.json](./services/payments/openapi.json)|[![ReDoc](https://img.shields.io/badge/OpenAPI-ReDoc-85ea2d?logo=openapiinitiative)](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/ITISFoundation/osparc-simcore/refs/heads/master/services/payments/openapi.json) [![Swagger UI](https://img.shields.io/badge/OpenAPI-Swagger_UI-85ea2d?logo=swagger)](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/ITISFoundation/osparc-simcore/refs/heads/master/services/payments/openapi.json) |
49+
| |[services/payments/gateway/openapi.json](./services/payments/gateway/openapi.json)|[![ReDoc](https://img.shields.io/badge/OpenAPI-ReDoc-85ea2d?logo=openapiinitiative)](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/ITISFoundation/osparc-simcore/refs/heads/master/services/payments/gateway/openapi.json) [![Swagger UI](https://img.shields.io/badge/OpenAPI-Swagger_UI-85ea2d?logo=swagger)](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/ITISFoundation/osparc-simcore/refs/heads/master/services/payments/gateway/openapi.json) |
50+
| |[services/payments/Dockerfile](./services/payments/Dockerfile)|[![Docker Image Size](https://img.shields.io/docker/image-size/itisfoundation/payments)](https://hub.docker.com/r/itisfoundation/payments/tags) |
51+
| **RESOURCE-USAGE-TRACKER**|| |
52+
| |[services/resource-usage-tracker/openapi.json](./services/resource-usage-tracker/openapi.json)|[![ReDoc](https://img.shields.io/badge/OpenAPI-ReDoc-85ea2d?logo=openapiinitiative)](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/ITISFoundation/osparc-simcore/refs/heads/master/services/resource-usage-tracker/openapi.json) [![Swagger UI](https://img.shields.io/badge/OpenAPI-Swagger_UI-85ea2d?logo=swagger)](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/ITISFoundation/osparc-simcore/refs/heads/master/services/resource-usage-tracker/openapi.json) |
53+
| |[services/resource-usage-tracker/Dockerfile](./services/resource-usage-tracker/Dockerfile)|[![Docker Image Size](https://img.shields.io/docker/image-size/itisfoundation/resource-usage-tracker)](https://hub.docker.com/r/itisfoundation/resource-usage-tracker/tags) |
54+
| **STATIC-WEBSERVER**|| |
55+
| |[services/static-webserver/client/tools/qooxdoo-kit/builder/Dockerfile](./services/static-webserver/client/tools/qooxdoo-kit/builder/Dockerfile)|[![Docker Image Size](https://img.shields.io/docker/image-size/itisfoundation/static-webserver)](https://hub.docker.com/r/itisfoundation/static-webserver/tags) |
56+
| **STORAGE**|| |
57+
| |[services/storage/src/simcore_service_storage/api/v0/openapi.yaml](./services/storage/src/simcore_service_storage/api/v0/openapi.yaml)|[![ReDoc](https://img.shields.io/badge/OpenAPI-ReDoc-85ea2d?logo=openapiinitiative)](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/ITISFoundation/osparc-simcore/refs/heads/master/services/storage/src/simcore_service_storage/api/v0/openapi.yaml) [![Swagger UI](https://img.shields.io/badge/OpenAPI-Swagger_UI-85ea2d?logo=swagger)](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/ITISFoundation/osparc-simcore/refs/heads/master/services/storage/src/simcore_service_storage/api/v0/openapi.yaml) |
58+
| |[services/storage/Dockerfile](./services/storage/Dockerfile)|[![Docker Image Size](https://img.shields.io/docker/image-size/itisfoundation/storage)](https://hub.docker.com/r/itisfoundation/storage/tags) |
59+
| **WEB**|| |
60+
| |[services/web/server/src/simcore_service_webserver/api/v0/openapi.yaml](./services/web/server/src/simcore_service_webserver/api/v0/openapi.yaml)|[![ReDoc](https://img.shields.io/badge/OpenAPI-ReDoc-85ea2d?logo=openapiinitiative)](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/ITISFoundation/osparc-simcore/refs/heads/master/services/web/server/src/simcore_service_webserver/api/v0/openapi.yaml) [![Swagger UI](https://img.shields.io/badge/OpenAPI-Swagger_UI-85ea2d?logo=swagger)](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/ITISFoundation/osparc-simcore/refs/heads/master/services/web/server/src/simcore_service_webserver/api/v0/openapi.yaml) |
61+
| |[services/web/Dockerfile](./services/web/Dockerfile)|[![Docker Image Size](https://img.shields.io/docker/image-size/itisfoundation/webserver)](https://hub.docker.com/r/itisfoundation/webserver/tags) |
62+
| || |

‎services/agent/README.md‎

Lines changed: 0 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,5 @@
11
# agent
22

3-
[![image-size]](https://microbadger.com/images/itisfoundation/agent. "More on itisfoundation/agent.:staging-latest image")
4-
5-
[![image-badge]](https://microbadger.com/images/itisfoundation/agent "More on agent image in registry")
6-
[![image-version]](https://microbadger.com/images/itisfoundation/agent "More on agent image in registry")
7-
[![image-commit]](https://microbadger.com/images/itisfoundation/agent "More on agent image in registry")
8-
9-
Service for executing commands on docker nodes
10-
11-
<!-- Add badges urls here-->
12-
[image-size]:https://img.shields.io/microbadger/image-size/itisfoundation/agent./staging-latest.svg?label=agent.&style=flat
13-
[image-badge]:https://images.microbadger.com/badges/image/itisfoundation/agent.svg
14-
[image-version]https://images.microbadger.com/badges/version/itisfoundation/agent.svg
15-
[image-commit]:https://images.microbadger.com/badges/commit/itisfoundation/agent.svg
16-
<!------------------------->
173

184
To develop this project, just
195

‎services/datcore-adapter/README.md‎

Lines changed: 0 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,5 @@
11
# datcore-adapter
22

3-
[![image-size]](https://microbadger.com/images/itisfoundation/datcore-adapter. "More on itisfoundation/datcore-adapter.:staging-latest image")
4-
5-
[![image-badge]](https://microbadger.com/images/itisfoundation/datcore-adapter "More on datcore-adapter image in registry")
6-
[![image-version]](https://microbadger.com/images/itisfoundation/datcore-adapter "More on datcore-adapter image in registry")
7-
[![image-commit]](https://microbadger.com/images/itisfoundation/datcore-adapter "More on datcore-adapter image in registry")
8-
9-
Interfaces with datcore storage
10-
11-
<!-- Add badges urls here-->
12-
[image-size]:https://img.shields.io/microbadger/image-size/itisfoundation/datcore-adapter./staging-latest.svg?label=datcore-adapter.&style=flat
13-
[image-badge]:https://images.microbadger.com/badges/image/itisfoundation/datcore-adapter.svg
14-
[image-version]https://images.microbadger.com/badges/version/itisfoundation/datcore-adapter.svg
15-
[image-commit]:https://images.microbadger.com/badges/commit/itisfoundation/datcore-adapter.svg
16-
<!------------------------->
17-
183
## Development
194

205
Setup environment

‎services/storage/README.md‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,4 @@
11
# storage
22

3-
[![Docker Pulls](https://img.shields.io/docker/pulls/itisfoundation/storage.svg)](https://hub.docker.com/r/itisfoundation/storage/tags)
4-
[![](https://images.microbadger.com/badges/image/itisfoundation/storage.svg)](https://microbadger.com/images/itisfoundation/storage "More on service image in registry")
5-
[![](https://images.microbadger.com/badges/version/itisfoundation/storage.svg)](https://microbadger.com/images/itisfoundation/storage "More on service image in registry")
6-
[![](https://images.microbadger.com/badges/commit/itisfoundation/storage.svg)](https://microbadger.com/images/itisfoundation/storage "More on service image in registry")
73

84
Service to manage data storage in simcore

0 commit comments

Comments
 (0)