Random editorial improvements

semantic-conventions/src/opentelemetry/semconv/templating/markdown/__init__.py

@@ -172,11 +172,11 @@ def derive_requirement_level(self, attribute: SemanticAttribute):
             required = "Required"
         elif attribute.requirement_level == RequirementLevel.CONDITIONALLY_REQUIRED:
             if len(attribute.requirement_level_msg) < self.options.break_count:
-                required = "Conditionally Required: " + attribute.requirement_level_msg
+                required = "Conditionally Required " + attribute.requirement_level_msg
             else:
                 # We put the condition in the notes after the table
                 self.render_ctx.add_note(attribute.requirement_level_msg)
-                required = f"Conditionally Required: [{ len(self.render_ctx.notes)}]"
+                required = f"Conditionally Required [{ len(self.render_ctx.notes)}]"
         elif attribute.requirement_level == RequirementLevel.OPT_IN:
             required = "Opt-In"
         else:  # attribute.requirement_level == Required.RECOMMENDED or None
@@ -190,11 +190,11 @@ def derive_requirement_level(self, attribute: SemanticAttribute):
                 if not attribute.requirement_level_msg:
                     required = "Recommended"
                 elif len(attribute.requirement_level_msg) < self.options.break_count:
-                    required = "Recommended: " + attribute.requirement_level_msg
+                    required = "Recommended " + attribute.requirement_level_msg
                 else:
                     # We put the condition in the notes after the table
                     self.render_ctx.add_note(attribute.requirement_level_msg)
-                    required = f"Recommended: [{len(self.render_ctx.notes)}]"
+                    required = f"Recommended [{len(self.render_ctx.notes)}]"
         return required
 
     def write_table_header(self, output: io.StringIO):
@@ -322,8 +322,8 @@ def to_markdown_enum(self, output: io.StringIO):
             if enum.custom_values:
                 output.write(
                     "has the following list of well-known values."
-                    + " If one of them applies, then the respective value MUST be used,"
-                    + " otherwise a custom value MAY be used."
+                    + " If one of them applies, then the respective value MUST be used;"
+                    + " otherwise, a custom value MAY be used."
                 )
             else:
                 output.write("MUST be one of the following:")

semantic-conventions/src/tests/data/markdown/attribute_group/expected.md

@@ -3,6 +3,6 @@
 <!-- semconv span_attribute_group -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `foo.bar` | string | Attribute 1 | `baz` | Recommended: if available |
-| `foo.qux` | int | Attribute 2 | `42` | Conditionally Required: if available |
+| `foo.bar` | string | Attribute 1 | `baz` | Recommended if available |
+| `foo.qux` | int | Attribute 2 | `42` | Conditionally Required if available |
 <!-- endsemconv -->

semantic-conventions/src/tests/data/markdown/deprecated/expected.md

@@ -8,15 +8,15 @@
 | `http.host` | string | The value of the [HTTP host header](https://tools.ietf.org/html/rfc7230#section-5.4). When the header is empty or not present, this attribute should be the same. | `www.example.org` | Recommended |
 | `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required |
 | `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | Recommended |
-| `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: if and only if one was received/sent |
+| `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required if and only if one was received/sent |
 | `http.status_text` | string | **Deprecated: Use attribute `status_description` instead.**<br>[HTTP reason phrase](https://tools.ietf.org/html/rfc7230#section-3.1.2). | `OK` | Recommended |
 | `http.target` | string | The full request target as passed in a HTTP request line or equivalent. | `/path/12314/?q=ddds#123` | Recommended |
 | `http.url` | string | Full HTTP request URL in the form `scheme://host[:port]/path?query[#fragment]`. Usually the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless. | `https://www.foo.bar/search?q=OpenTelemetry#SemConv` | Recommended |
 | `http.user_agent` | string | Value of the [HTTP User-Agent](https://tools.ietf.org/html/rfc7231#section-5.5.3) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3` | Recommended |
 
 **[1]:** If `net.transport` is not specified, it can be assumed to be `IP.TCP` except if `http.flavor` is `QUIC`, in which case `IP.UDP` is assumed.
 
-`http.flavor` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.
+`http.flavor` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
 
 | Value  | Description |
 |---|---|

semantic-conventions/src/tests/data/markdown/deprecated/input.md

@@ -10,7 +10,7 @@
 | `http.target` | The full request target as passed in a [HTTP request line][] or equivalent, e.g. `"/path/12314/?q=ddds#123"`. | Defined later. |
 | `http.host` | The value of the [HTTP host header][]. When the header is empty or not present, this attribute should be the same. | Defined later. |
 | `http.scheme` | The URI scheme identifying the used protocol: `"http"` or `"https"` | Defined later. |
-| `http.status_code` | [HTTP response status code][]. E.g. `200` (integer) | Conditionally Required: if and only if one was received/sent. |
+| `http.status_code` | [HTTP response status code][]. E.g. `200` (integer) | Conditionally Required if and only if one was received/sent. |
 | `http.status_text` | [HTTP reason phrase][]. E.g. `"OK"` | Recommended |
 | `http.flavor` | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"`. |  No |
 | `http.user_agent` | Value of the HTTP [User-Agent][] header sent by the client. | Recommended |

semantic-conventions/src/tests/data/markdown/empty/expected.md

@@ -77,7 +77,7 @@ Note that the items marked with [1] are different from the mapping defined in th
 | `http.target` | The full request target as passed in a [HTTP request line][] or equivalent, e.g. `"/path/12314/?q=ddds#123"`. | Defined later. |
 | `http.host` | The value of the [HTTP host header][]. When the header is empty or not present, this attribute should be the same. | Defined later. |
 | `http.scheme` | The URI scheme identifying the used protocol: `"http"` or `"https"` | Defined later. |
-| `http.status_code` | [HTTP response status code][]. E.g. `200` (integer) | Conditionally Required: if and only if one was received/sent. |
+| `http.status_code` | [HTTP response status code][]. E.g. `200` (integer) | Conditionally Required if and only if one was received/sent. |
 | `http.status_text` | [HTTP reason phrase][]. E.g. `"OK"` | Recommended |
 | `http.flavor` | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"`. |  Opt-In |
 | `http.user_agent` | Value of the HTTP [User-Agent][] header sent by the client. | Recommended |

semantic-conventions/src/tests/data/markdown/empty/input.md

@@ -77,7 +77,7 @@ Note that the items marked with [1] are different from the mapping defined in th
 | `http.target` | The full request target as passed in a [HTTP request line][] or equivalent, e.g. `"/path/12314/?q=ddds#123"`. | Defined later. |
 | `http.host` | The value of the [HTTP host header][]. When the header is empty or not present, this attribute should be the same. | Defined later. |
 | `http.scheme` | The URI scheme identifying the used protocol: `"http"` or `"https"` | Defined later. |
-| `http.status_code` | [HTTP response status code][]. E.g. `200` (integer) | Conditionally Required: if and only if one was received/sent. |
+| `http.status_code` | [HTTP response status code][]. E.g. `200` (integer) | Conditionally Required if and only if one was received/sent. |
 | `http.status_text` | [HTTP reason phrase][]. E.g. `"OK"` | Recommended |
 | `http.flavor` | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"`. |  Opt-In |
 | `http.user_agent` | Value of the HTTP [User-Agent][] header sent by the client. | Recommended |

semantic-conventions/src/tests/data/markdown/extend_constraint/expected.md

@@ -41,8 +41,8 @@ Some database systems may allow a connection to switch to a different `db.user`,
 | `db.user` | string | Username for accessing the database. | `readonly_user`; `reporting_user` | Recommended |
 | `net.peer.ip` | string | Remote address of the peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | See below |
 | `net.peer.name` | string | Remote hostname or similar, see note below. | `example.com` | See below |
-| `net.peer.port` | int | Remote port number. | `80`; `8080`; `443` | Conditionally Required: [2] |
-| `net.transport` | string | Transport protocol used. See note below. | `IP.TCP` | Conditionally Required: [3] |
+| `net.peer.port` | int | Remote port number. | `80`; `8080`; `443` | Conditionally Required [2] |
+| `net.transport` | string | Transport protocol used. See note below. | `IP.TCP` | Conditionally Required [3] |
 
 **[1]:** It is recommended to remove embedded credentials.
 
@@ -55,7 +55,7 @@ Some database systems may allow a connection to switch to a different `db.user`,
 * `net.peer.name`
 * `net.peer.ip`
 
-`db.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.
+`db.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
 
 | Value  | Description |
 |---|---|
@@ -141,9 +141,9 @@ Usually only one `db.name` will be used per connection though.
 <!-- semconv db(tag=call-level,remove_constraints) -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `db.name` | string | If no tech-specific attribute is defined, this attribute is used to report the name of the database being accessed. For commands that switch the database, this should be set to the target database (even if the command fails). [1] | `customers`; `main` | Conditionally Required: [2] |
-| `db.operation` | string | The name of the operation being executed, e.g. the [MongoDB command name](https://docs.mongodb.com/manual/reference/command/#database-operations) such as `findAndModify`. [3] | `findAndModify`; `HMSET` | Conditionally Required: if `db.statement` is not applicable. |
-| `db.statement` | string | The database statement being executed. [4] | `SELECT * FROM wuser_table`; `SET mykey "WuValue"` | Conditionally Required: if applicable. |
+| `db.name` | string | If no tech-specific attribute is defined, this attribute is used to report the name of the database being accessed. For commands that switch the database, this should be set to the target database (even if the command fails). [1] | `customers`; `main` | Conditionally Required [2] |
+| `db.operation` | string | The name of the operation being executed, e.g. the [MongoDB command name](https://docs.mongodb.com/manual/reference/command/#database-operations) such as `findAndModify`. [3] | `findAndModify`; `HMSET` | Conditionally Required if `db.statement` is not applicable. |
+| `db.statement` | string | The database statement being executed. [4] | `SELECT * FROM wuser_table`; `SET mykey "WuValue"` | Conditionally Required if applicable. |
 
 **[1]:** In some SQL databases, the database name to be used is called "schema name".
 
@@ -187,7 +187,7 @@ For example, when retrieving a document, `db.operation` would be set to (literal
 <!-- semconv db.redis -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `db.redis.database_index` | int | The index of the database being accessed as used in the [`SELECT` command](https://redis.io/commands/select), provided as an integer. To be used instead of the generic `db.name` attribute. | `0`; `1`; `15` | Conditionally Required: if other than the default database (`0`). |
+| `db.redis.database_index` | int | The index of the database being accessed as used in the [`SELECT` command](https://redis.io/commands/select), provided as an integer. To be used instead of the generic `db.name` attribute. | `0`; `1`; `15` | Conditionally Required if other than the default database (`0`). |
 <!-- endsemconv -->
 
 #### MongoDB

semantic-conventions/src/tests/data/markdown/extend_constraint/input.md

@@ -41,12 +41,12 @@ Some database systems may allow a connection to switch to a different `db.user`,
 | `db.user` | string | Username for accessing the database. | `readonly_user`<br>`reporting_user` | Recommended |
 | `net.peer.ip` | string | Remote address of the peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | Conditional<br>See below. |
 | `net.peer.name` | string | Remote hostname or similar, see note below. | `example.com` | Conditional<br>See below. |
-| `net.peer.port` | int | Remote port number. | `80`<br>`8080`<br>`443` | Conditionally Required: [2] |
-| `net.transport` | string enum | Transport protocol used. See note below. | `IP.TCP` | Conditionally Required: [3] |
+| `net.peer.port` | int | Remote port number. | `80`<br>`8080`<br>`443` | Conditionally Required [2] |
+| `net.transport` | string enum | Transport protocol used. See note below. | `IP.TCP` | Conditionally Required [3] |
 
 **[1]:** It is recommended to remove embedded credentials.
 
-**[2]:** Conditionally Required: if using a port other than the default port for this DBMS.
+**[2]:** Conditionally Required if using a port other than the default port for this DBMS.
 
 **[3]:** Recommended in general, required for in-process databases (`"inproc"`).
 
@@ -55,7 +55,7 @@ At least one of the following is required:
 * `net.peer.name`
 * `net.peer.ip`
 
-`db.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.
+`db.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
 
 | Value  | Description |
 |---|---|
@@ -141,9 +141,9 @@ Usually only one `db.name` will be used per connection though.
 <!-- semconv db(tag=call-level,remove_constraints) -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `db.name` | string | If no tech-specific attribute is defined, this attribute is used to report the name of the database being accessed. For commands that switch the database, this should be set to the target database (even if the command fails). [1] | `customers`<br>`main` | Conditionally Required: [2] |
-| `db.statement` | string | The database statement being executed. [3] | `SELECT * FROM wuser_table`<br>`SET mykey "WuValue"` | Conditional<br>Conditionally Required: if applicable. |
-| `db.operation` | string | The name of the operation being executed, e.g. the [MongoDB command name](https://docs.mongodb.com/manual/reference/command/#database-operations) such as `findAndModify`. [4] | `findAndModify`<br>`HMSET` | Conditional<br>Conditionally Required: if `db.statement` is not applicable. |
+| `db.name` | string | If no tech-specific attribute is defined, this attribute is used to report the name of the database being accessed. For commands that switch the database, this should be set to the target database (even if the command fails). [1] | `customers`<br>`main` | Conditionally Required [2] |
+| `db.statement` | string | The database statement being executed. [3] | `SELECT * FROM wuser_table`<br>`SET mykey "WuValue"` | Conditional<br>Conditionally Required if applicable. |
+| `db.operation` | string | The name of the operation being executed, e.g. the [MongoDB command name](https://docs.mongodb.com/manual/reference/command/#database-operations) such as `findAndModify`. [4] | `findAndModify`<br>`HMSET` | Conditional<br>Conditionally Required if `db.statement` is not applicable. |
 
 **[1]:** In some SQL databases, the database name to be used is called "schema name".
 

semantic-conventions/src/tests/data/markdown/include/expected.md

@@ -7,11 +7,11 @@
 | `faas.trigger` | string | Type of the trigger on which the function is executed. | `datasource` | Required |
 | `http.host` | string | The value of the [HTTP host header](https://tools.ietf.org/html/rfc7230#section-5.4). When the header is empty or not present, this attribute should be the same. | `www.example.org` | See below |
 | `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required |
-| `http.recommended_attribute` | string | brief | `foo` | Recommended: short note |
-| `http.recommended_attribute_long_note` | string | brief | `bar` | Recommended: [1] |
+| `http.recommended_attribute` | string | brief | `foo` | Recommended short note |
+| `http.recommended_attribute_long_note` | string | brief | `bar` | Recommended [1] |
 | `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | See below |
-| [`http.server_name`](input_http.md) | string | The primary server name of the matched virtual host. [2] | `example.com` | Conditionally Required: [3] |
-| `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: if and only if one was received/sent |
+| [`http.server_name`](input_http.md) | string | The primary server name of the matched virtual host. [2] | `example.com` | Conditionally Required [3] |
+| `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required if and only if one was received/sent |
 | `http.status_text` | string | [HTTP reason phrase](https://tools.ietf.org/html/rfc7230#section-3.1.2). | `OK` | Recommended |
 | `http.target` | string | The full request target as passed in a HTTP request line or equivalent. | `/path/12314/?q=ddds#123` | See below |
 | `http.url` | string | Full HTTP request URL in the form `scheme://host[:port]/path?query[#fragment]`. Usually the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless. | `https://www.foo.bar/search?q=OpenTelemetry#SemConv` | See below |

semantic-conventions/src/tests/data/markdown/metrics_tables/expected.md

@@ -14,7 +14,7 @@
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
 | `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required |
-| `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: if and only if one was received/sent. |
+| `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required if and only if one was received/sent. |
 <!-- endsemconv -->
 
 **`foo.active_eggs`**
@@ -28,7 +28,7 @@
 <!-- semconv metric.foo.active_eggs -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `bar.egg.type` | string | Type of egg. [1] | `chicken`; `emu`; `dragon` | Conditionally Required: if available to instrumentation. |
+| `bar.egg.type` | string | Type of egg. [1] | `chicken`; `emu`; `dragon` | Conditionally Required if available to instrumentation. |
 | `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Opt-In |
 
 **[1]:** Some notes on attribute

semantic-conventions/src/tests/data/markdown/missing_end_tag/input.md

@@ -10,7 +10,7 @@
 | `http.target` | The full request target as passed in a [HTTP request line][] or equivalent, e.g. `"/path/12314/?q=ddds#123"`. | Defined later. |
 | `http.host` | The value of the [HTTP host header][]. When the header is empty or not present, this attribute should be the same. | Defined later. |
 | `http.scheme` | The URI scheme identifying the used protocol: `"http"` or `"https"` | Defined later. |
-| `http.status_code` | [HTTP response status code][]. E.g. `200` (integer) | Conditionally Required: if and only if one was received/sent. |
+| `http.status_code` | [HTTP response status code][]. E.g. `200` (integer) | Conditionally Required if and only if one was received/sent. |
 | `http.status_text` | [HTTP reason phrase][]. E.g. `"OK"` | Recommended |
 | `http.flavor` | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"`. |  Opt-In |
 | `http.user_agent` | Value of the HTTP [User-Agent][] header sent by the client. | Recommended |