Skip to content

Commit 960b757

Browse files
knopers8knopers8
committed
[doc] add common.proto and events.proto to aliecs API doc
without these two, protoc doc generator creates broken links to messages in imported protos.
1 parent cbf9ad2 commit 960b757

File tree

3 files changed

+337
-2
lines changed

3 files changed

+337
-2
lines changed

‎Makefile‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -313,7 +313,7 @@ docs/coconut:
313313
docs/grpc:
314314
@echo -e "generating gRPC API documentation \033[1;33m==>\033[0m \033[1;34m./docs\033[0m"
315315
@cd apricot/protos && PATH="$(ROOT_DIR)/tools:$$PATH" protoc --doc_out="$(ROOT_DIR)/docs" --doc_opt=markdown,apidocs_apricot.md "apricot.proto"
316-
@cd core/protos && PATH="$(ROOT_DIR)/tools:$$PATH" protoc -I=. -I=../../common --doc_out="$(ROOT_DIR)/docs" --doc_opt=markdown,apidocs_aliecs.md "o2control.proto"
316+
@cd core/protos && PATH="$(ROOT_DIR)/tools:$$PATH" protoc -I=. -I=../../common --doc_out="$(ROOT_DIR)/docs" --experimental_allow_proto3_optional --doc_opt=markdown,apidocs_aliecs.md o2control.proto ../../common/protos/events.proto ../../common/protos/common.proto
317317
@cd occ/protos && PATH="$(ROOT_DIR)/tools:$$PATH" protoc --doc_out="$(ROOT_DIR)/docs" --doc_opt=markdown,apidocs_occ.md "occ.proto"
318318

319319
docs/swaggo:

‎apricot/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,4 +11,4 @@ Usage of bin/o2-apricot:
1111
--verbose Verbose logging
1212
```
1313

14-
Protofile: [apricot.proto](apricot/protos/apricot.proto)
14+
Protofile: [apricot.proto](protos/apricot.proto)

‎docs/apidocs_aliecs.md‎

Lines changed: 335 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,26 @@
8888

8989
- [Control](#o2control-Control)
9090

91+
- [protos/events.proto](#protos_events-proto)
92+
- [Ev_CallEvent](#events-Ev_CallEvent)
93+
- [Ev_EnvironmentEvent](#events-Ev_EnvironmentEvent)
94+
- [Ev_EnvironmentEvent.VarsEntry](#events-Ev_EnvironmentEvent-VarsEntry)
95+
- [Ev_IntegratedServiceEvent](#events-Ev_IntegratedServiceEvent)
96+
- [Ev_MetaEvent_CoreStart](#events-Ev_MetaEvent_CoreStart)
97+
- [Ev_MetaEvent_FrameworkEvent](#events-Ev_MetaEvent_FrameworkEvent)
98+
- [Ev_MetaEvent_MesosHeartbeat](#events-Ev_MetaEvent_MesosHeartbeat)
99+
- [Ev_RoleEvent](#events-Ev_RoleEvent)
100+
- [Ev_RunEvent](#events-Ev_RunEvent)
101+
- [Ev_TaskEvent](#events-Ev_TaskEvent)
102+
- [Event](#events-Event)
103+
- [Traits](#events-Traits)
104+
105+
- [OpStatus](#events-OpStatus)
106+
107+
- [protos/common.proto](#protos_common-proto)
108+
- [User](#common-User)
109+
- [WorkflowTemplateInfo](#common-WorkflowTemplateInfo)
110+
91111
- [Scalar Value Types](#scalar-value-types)
92112

93113

@@ -1488,6 +1508,321 @@ Not implemented yet
14881508

14891509

14901510

1511+
<a name="protos_events-proto"></a>
1512+
<p align="right"><a href="#top">Top</a></p>
1513+
1514+
## protos/events.proto
1515+
1516+
1517+
1518+
<a name="events-Ev_CallEvent"></a>
1519+
1520+
### Ev_CallEvent
1521+
1522+
1523+
1524+
| Field | Type | Label | Description |
1525+
| ----- | ---- | ----- | ----------- |
1526+
| func | [string](#string) | | name of the function being called, within the workflow template context |
1527+
| callStatus | [OpStatus](#events-OpStatus) | | progress or success/failure state of the call |
1528+
| return | [string](#string) | | return value of the function |
1529+
| traits | [Traits](#events-Traits) | | |
1530+
| output | [string](#string) | | any additional output of the function |
1531+
| error | [string](#string) | | error value, if returned |
1532+
| environmentId | [string](#string) | | |
1533+
| path | [string](#string) | | path to the parent callRole of this call within the environment |
1534+
1535+
1536+
1537+
1538+
1539+
1540+
<a name="events-Ev_EnvironmentEvent"></a>
1541+
1542+
### Ev_EnvironmentEvent
1543+
1544+
1545+
1546+
| Field | Type | Label | Description |
1547+
| ----- | ---- | ----- | ----------- |
1548+
| environmentId | [string](#string) | | |
1549+
| state | [string](#string) | | |
1550+
| runNumber | [uint32](#uint32) | | only when the environment is in the running state |
1551+
| error | [string](#string) | | |
1552+
| message | [string](#string) | | any additional message concerning the current state or transition |
1553+
| transition | [string](#string) | | |
1554+
| transitionStep | [string](#string) | | |
1555+
| transitionStatus | [OpStatus](#events-OpStatus) | | |
1556+
| vars | [Ev_EnvironmentEvent.VarsEntry](#events-Ev_EnvironmentEvent-VarsEntry) | repeated | consolidated environment variables at the root role of the environment |
1557+
| lastRequestUser | [common.User](#common-User) | | |
1558+
| workflowTemplateInfo | [common.WorkflowTemplateInfo](#common-WorkflowTemplateInfo) | | |
1559+
1560+
1561+
1562+
1563+
1564+
1565+
<a name="events-Ev_EnvironmentEvent-VarsEntry"></a>
1566+
1567+
### Ev_EnvironmentEvent.VarsEntry
1568+
1569+
1570+
1571+
| Field | Type | Label | Description |
1572+
| ----- | ---- | ----- | ----------- |
1573+
| key | [string](#string) | | |
1574+
| value | [string](#string) | | |
1575+
1576+
1577+
1578+
1579+
1580+
1581+
<a name="events-Ev_IntegratedServiceEvent"></a>
1582+
1583+
### Ev_IntegratedServiceEvent
1584+
1585+
1586+
1587+
| Field | Type | Label | Description |
1588+
| ----- | ---- | ----- | ----------- |
1589+
| name | [string](#string) | | name of the context, usually the path of the callRole that calls a given integrated service function e.g. readout-dataflow.dd-scheduler.terminate |
1590+
| error | [string](#string) | | error message, if any |
1591+
| operationName | [string](#string) | | name of the operation, usually the name of the integrated service function being called e.g. ddsched.PartitionTerminate()&#34; |
1592+
| operationStatus | [OpStatus](#events-OpStatus) | | progress or success/failure state of the operation |
1593+
| operationStep | [string](#string) | | if the operation has substeps, this is the name of the current substep, like an API call or polling phase |
1594+
| operationStepStatus | [OpStatus](#events-OpStatus) | | progress or success/failure state of the current substep |
1595+
| environmentId | [string](#string) | | |
1596+
| payload | [string](#string) | | any additional payload, depending on the integrated service; there is no schema, it can even be the raw return structure of a remote API call |
1597+
1598+
1599+
1600+
1601+
1602+
1603+
<a name="events-Ev_MetaEvent_CoreStart"></a>
1604+
1605+
### Ev_MetaEvent_CoreStart
1606+
1607+
1608+
1609+
| Field | Type | Label | Description |
1610+
| ----- | ---- | ----- | ----------- |
1611+
| frameworkId | [string](#string) | | |
1612+
1613+
1614+
1615+
1616+
1617+
1618+
<a name="events-Ev_MetaEvent_FrameworkEvent"></a>
1619+
1620+
### Ev_MetaEvent_FrameworkEvent
1621+
1622+
1623+
1624+
| Field | Type | Label | Description |
1625+
| ----- | ---- | ----- | ----------- |
1626+
| frameworkId | [string](#string) | | |
1627+
| message | [string](#string) | | |
1628+
1629+
1630+
1631+
1632+
1633+
1634+
<a name="events-Ev_MetaEvent_MesosHeartbeat"></a>
1635+
1636+
### Ev_MetaEvent_MesosHeartbeat
1637+
1638+
1639+
1640+
1641+
1642+
1643+
1644+
<a name="events-Ev_RoleEvent"></a>
1645+
1646+
### Ev_RoleEvent
1647+
1648+
1649+
1650+
| Field | Type | Label | Description |
1651+
| ----- | ---- | ----- | ----------- |
1652+
| name | [string](#string) | | role name |
1653+
| status | [string](#string) | | posible values: ACTIVE/INACTIVE/PARTIAL/UNDEFINED/UNDEPLOYABLE as defined in status.go. Derived from the state of child tasks, calls or other roles |
1654+
| state | [string](#string) | | state machine state for this role |
1655+
| rolePath | [string](#string) | | path to this role within the environment |
1656+
| environmentId | [string](#string) | | |
1657+
1658+
1659+
1660+
1661+
1662+
1663+
<a name="events-Ev_RunEvent"></a>
1664+
1665+
### Ev_RunEvent
1666+
1667+
1668+
1669+
| Field | Type | Label | Description |
1670+
| ----- | ---- | ----- | ----------- |
1671+
| environmentId | [string](#string) | | |
1672+
| runNumber | [uint32](#uint32) | | |
1673+
| state | [string](#string) | | |
1674+
| error | [string](#string) | | |
1675+
| transition | [string](#string) | | |
1676+
| transitionStatus | [OpStatus](#events-OpStatus) | | |
1677+
| lastRequestUser | [common.User](#common-User) | | |
1678+
1679+
1680+
1681+
1682+
1683+
1684+
<a name="events-Ev_TaskEvent"></a>
1685+
1686+
### Ev_TaskEvent
1687+
1688+
1689+
1690+
| Field | Type | Label | Description |
1691+
| ----- | ---- | ----- | ----------- |
1692+
| name | [string](#string) | | task name, based on the name of the task class |
1693+
| taskid | [string](#string) | | task id, unique |
1694+
| state | [string](#string) | | state machine state for this task |
1695+
| status | [string](#string) | | posible values: ACTIVE/INACTIVE/PARTIAL/UNDEFINED/UNDEPLOYABLE as defined in status.go. |
1696+
| hostname | [string](#string) | | |
1697+
| className | [string](#string) | | name of the task class from which this task was spawned |
1698+
| traits | [Traits](#events-Traits) | | |
1699+
| environmentId | [string](#string) | | |
1700+
| path | [string](#string) | | path to the parent taskRole of this task within the environment |
1701+
1702+
1703+
1704+
1705+
1706+
1707+
<a name="events-Event"></a>
1708+
1709+
### Event
1710+
1711+
1712+
1713+
| Field | Type | Label | Description |
1714+
| ----- | ---- | ----- | ----------- |
1715+
| timestamp | [int64](#int64) | | |
1716+
| timestampNano | [int64](#int64) | | |
1717+
| environmentEvent | [Ev_EnvironmentEvent](#events-Ev_EnvironmentEvent) | | |
1718+
| taskEvent | [Ev_TaskEvent](#events-Ev_TaskEvent) | | |
1719+
| roleEvent | [Ev_RoleEvent](#events-Ev_RoleEvent) | | |
1720+
| callEvent | [Ev_CallEvent](#events-Ev_CallEvent) | | |
1721+
| integratedServiceEvent | [Ev_IntegratedServiceEvent](#events-Ev_IntegratedServiceEvent) | | |
1722+
| runEvent | [Ev_RunEvent](#events-Ev_RunEvent) | | |
1723+
| frameworkEvent | [Ev_MetaEvent_FrameworkEvent](#events-Ev_MetaEvent_FrameworkEvent) | | |
1724+
| mesosHeartbeatEvent | [Ev_MetaEvent_MesosHeartbeat](#events-Ev_MetaEvent_MesosHeartbeat) | | |
1725+
| coreStartEvent | [Ev_MetaEvent_CoreStart](#events-Ev_MetaEvent_CoreStart) | | |
1726+
1727+
1728+
1729+
1730+
1731+
1732+
<a name="events-Traits"></a>
1733+
1734+
### Traits
1735+
1736+
1737+
1738+
| Field | Type | Label | Description |
1739+
| ----- | ---- | ----- | ----------- |
1740+
| trigger | [string](#string) | | |
1741+
| await | [string](#string) | | |
1742+
| timeout | [string](#string) | | |
1743+
| critical | [bool](#bool) | | |
1744+
1745+
1746+
1747+
1748+
1749+
1750+
1751+
1752+
<a name="events-OpStatus"></a>
1753+
1754+
### OpStatus
1755+
1756+
1757+
| Name | Number | Description |
1758+
| ---- | ------ | ----------- |
1759+
| NULL | 0 | |
1760+
| STARTED | 1 | |
1761+
| ONGOING | 2 | |
1762+
| DONE_OK | 3 | |
1763+
| DONE_ERROR | 4 | |
1764+
| DONE_TIMEOUT | 5 | |
1765+
1766+
1767+
1768+
1769+
1770+
1771+
1772+
1773+
1774+
1775+
<a name="protos_common-proto"></a>
1776+
<p align="right"><a href="#top">Top</a></p>
1777+
1778+
## protos/common.proto
1779+
1780+
1781+
1782+
<a name="common-User"></a>
1783+
1784+
### User
1785+
1786+
1787+
1788+
| Field | Type | Label | Description |
1789+
| ----- | ---- | ----- | ----------- |
1790+
| externalId | [int32](#int32) | optional | The unique CERN identifier of this user. |
1791+
| id | [int32](#int32) | optional | The unique identifier of this entity. |
1792+
| name | [string](#string) | | Name of the user. |
1793+
1794+
1795+
1796+
1797+
1798+
1799+
<a name="common-WorkflowTemplateInfo"></a>
1800+
1801+
### WorkflowTemplateInfo
1802+
1803+
1804+
1805+
| Field | Type | Label | Description |
1806+
| ----- | ---- | ----- | ----------- |
1807+
| name | [string](#string) | | |
1808+
| description | [string](#string) | | |
1809+
| path | [string](#string) | | |
1810+
| public | [bool](#bool) | | whether the environment is public or not |
1811+
1812+
1813+
1814+
1815+
1816+
1817+
1818+
1819+
1820+
1821+
1822+
1823+
1824+
1825+
14911826
## Scalar Value Types
14921827

14931828
| .proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby |

0 commit comments

Comments
 (0)