Skip to content

Commit 0b1a74c

Browse files
ThomsonTanThomsonTan
authored
Enable line-length lint for markdown docs (#1268)
1 parent 49648bd commit 0b1a74c

17 files changed

+732
-374
lines changed

‎.markdownlint.json‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
11
{
22
"default": true,
3-
"line-length": false
3+
"MD013":
4+
{
5+
"code_blocks": false,
6+
"tables": false
7+
}
48
}

‎CHANGELOG.md‎

Lines changed: 327 additions & 155 deletions
Large diffs are not rendered by default.

‎INSTALL.md‎

Lines changed: 50 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,10 @@ build systems for opentelemetry-cpp.
55

66
## Dependencies
77

8-
You can link OpenTelemetry C++ SDK with libraries provided in [dependencies.md](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/docs/dependencies.md) (complete list of libraries with versions used in our CI can be found [here](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/third_party_release)).
8+
You can link OpenTelemetry C++ SDK with libraries provided in
9+
[dependencies.md](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/docs/dependencies.md)
10+
(complete list of libraries with versions used in our CI can be found
11+
[here](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/third_party_release)).
912

1013
## Build instructions using CMake
1114

@@ -23,14 +26,17 @@ You can link OpenTelemetry C++ SDK with libraries provided in [dependencies.md](
2326
unittests. We use CMake version 3.15.2 in our build system. To install CMake,
2427
consult the [Installing CMake](https://cmake.org/install/) guide.
2528
- [GoogleTest](https://github.com/google/googletest) framework to build and run
26-
the unittests. Refer to [third_party_release](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/third_party_release#L5)
27-
for version of GoogleTest used in CI. To
28-
install GoogleTest, consult the [GoogleTest Build
29+
the unittests. Refer to
30+
[third_party_release](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/third_party_release#L5)
31+
for version of GoogleTest used in CI. To install GoogleTest, consult the
32+
[GoogleTest Build
2933
Instructions](https://github.com/google/googletest/blob/master/googletest/README.md#generic-build-instructions).
30-
- [Google Benchmark](https://github.com/google/benchmark) framework to build and run
31-
benchmark tests. Refer to [third_party_release](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/third_party_release#L4)
32-
for version of Benchmark used in CI. To install Benchmark,
33-
consult the [GoogleBenchmark Build Instructions](https://github.com/google/benchmark#installation).
34+
- [Google Benchmark](https://github.com/google/benchmark) framework to build and
35+
run benchmark tests. Refer to
36+
[third_party_release](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/third_party_release#L4)
37+
for version of Benchmark used in CI. To install Benchmark, consult the
38+
[GoogleBenchmark Build
39+
Instructions](https://github.com/google/benchmark#installation).
3440
- Apart from above core requirements, the Exporters and Propagators have their
3541
build dependencies which are not covered here. E.g, Otlp Exporter needs
3642
grpc/protobuf library, Zipkin exporter needs nlohmann-json and libcurl, ETW
@@ -75,9 +81,9 @@ You can link OpenTelemetry C++ SDK with libraries provided in [dependencies.md](
7581
configuration, the code is compiled without `-fpic` option, so it is not
7682
suitable for inclusion in shared libraries. To enable the code for
7783
inclusion in shared libraries, this variable is used.
78-
- `-DBUILD_SHARED_LIBS=ON` : To build shared libraries for the targets. Please
79-
refer to note [below](#building-shared-libs-for-windows) for Windows DLL
80-
support
84+
- `-DBUILD_SHARED_LIBS=ON` : To build shared libraries for the targets.
85+
Please refer to note [below](#building-shared-libs-for-windows) for
86+
Windows DLL support
8187
- `-DWITH_OTLP=ON` : To enable building Otlp exporter.
8288
- `-DWITH_PROMETHEUS=ON` : To enable building prometheus exporter.
8389

@@ -145,23 +151,25 @@ target_link_libraries(foo PRIVATE ${OPENTELEMETRY_CPP_LIBRARIES})
145151
## Build instructions using Bazel
146152

147153
NOTE: Experimental, and not supported for all the components. Make sure the
148-
[GoogleTest](https://github.com/google/googletest) installation may fail if there is a different version of googletest already installed in system-defined path.
154+
[GoogleTest](https://github.com/google/googletest) installation may fail if
155+
there is a different version of googletest already installed in system-defined
156+
path.
149157

150158
### Prerequisites for Bazel
151159

152-
- A supported platform (e.g. Windows, macOS or Linux).
153-
Refer to [Platforms Supported](./README.md#supported-development-platforms)
154-
for more information.
155-
- A compatible C++ compiler supporting at least C++11.
156-
Major compilers are supported.
157-
Refer to [Supported Compilers](./README.md#supported-c-versions) for more information.
158-
- [Git](https://git-scm.com/) for fetching opentelemetry-cpp source code from repository.
159-
To install Git, consult the [Set up Git](https://help.github.com/articles/set-up-git/)
160-
guide on GitHub.
161-
- [Bazel](https://www.bazel.build/) for building opentelemetry-cpp API,
162-
SDK with their unittests. We use 3.7.2 in our build system.
160+
- A supported platform (e.g. Windows, macOS or Linux). Refer to [Platforms
161+
Supported](./README.md#supported-development-platforms) for more information.
162+
- A compatible C++ compiler supporting at least C++11. Major compilers are
163+
supported. Refer to [Supported Compilers](./README.md#supported-c-versions) for
164+
more information.
165+
- [Git](https://git-scm.com/) for fetching opentelemetry-cpp source code from
166+
repository. To install Git, consult the [Set up
167+
Git](https://help.github.com/articles/set-up-git/) guide on GitHub.
168+
- [Bazel](https://www.bazel.build/) for building opentelemetry-cpp API, SDK with
169+
their unittests. We use 3.7.2 in our build system.
163170

164-
To install Bazel, consult the [Installing Bazel](https://docs.bazel.build/versions/3.7.0/install.html) guide.
171+
To install Bazel, consult the [Installing
172+
Bazel](https://docs.bazel.build/versions/3.7.0/install.html) guide.
165173

166174
### Building as standalone Bazel Project
167175

@@ -178,7 +186,8 @@ To install Bazel, consult the [Installing Bazel](https://docs.bazel.build/versio
178186
$
179187
```
180188

181-
2. Navigate to the repository cloned above, download the dependencies and build the source code:
189+
2. Navigate to the repository cloned above, download the dependencies and build
190+
the source code:
182191

183192
```console
184193
$ cd opentelemtry-cpp
@@ -252,23 +261,26 @@ cc_library(
252261

253262
## Building shared libs for Windows
254263

255-
Windows DLL build is not supported. There are some constraints on how C++ DLLs work on
256-
Windows, specifically we can't safely allocate memory in one DLL and free it in another.
257-
For now, OpenTelemetry C++ targets need to be statically linked into the Windows applications.
264+
Windows DLL build is not supported. There are some constraints on how C++ DLLs
265+
work on Windows, specifically we can't safely allocate memory in one DLL and
266+
free it in another. For now, OpenTelemetry C++ targets need to be statically
267+
linked into the Windows applications.
258268

259269
## Using Package Managers
260270

261-
If you are using [Conan](https://www.conan.io/) to manage your dependencies,
262-
add [`opentelemetry-cpp/x.y.z`](https://conan.io/center/opentelemetry-cpp) to
263-
your `conanfile`'s requires, where `x.y.z` is the release version you want to use.
271+
If you are using [Conan](https://www.conan.io/) to manage your dependencies, add
272+
[`opentelemetry-cpp/x.y.z`](https://conan.io/center/opentelemetry-cpp) to your
273+
`conanfile`'s requires, where `x.y.z` is the release version you want to use.
264274
Please file issues [here](https://github.com/conan-io/conan-center-index/issues)
265275
if you experience problems with the packages.
266276

267277
If you are using [vcpkg](https://github.com/Microsoft/vcpkg/) on your project
268-
for external dependencies, then you can install the
269-
[opentelemetry-cpp package](https://github.com/microsoft/vcpkg/tree/master/ports/opentelemetry-cpp)
270-
with `vcpkg install opentelemetry-cpp` and follow the then displayed descriptions.
271-
Please see the vcpkg project for any issues regarding the packaging.
272-
273-
Please note, these packages are not officially provided and maintained by OpenTelemetry C++ project,
274-
and are just listed here to consolidate all such efforts for ease of developers.
278+
for external dependencies, then you can install the [opentelemetry-cpp
279+
package](https://github.com/microsoft/vcpkg/tree/master/ports/opentelemetry-cpp)
280+
with `vcpkg install opentelemetry-cpp` and follow the then displayed
281+
descriptions. Please see the vcpkg project for any issues regarding the
282+
packaging.
283+
284+
Please note, these packages are not officially provided and maintained by
285+
OpenTelemetry C++ project, and are just listed here to consolidate all such
286+
efforts for ease of developers.

‎README.md‎

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,16 @@ The C++ [OpenTelemetry](https://opentelemetry.io/) client.
1616
| Metrics | Development [1] | N/A |
1717
| Logs | Experimental [2] | N/A |
1818

19-
* [1]: The development of the metrics API and SDK based on new stable specification is ongoing. The timelines would be available in release milestone. The earlier implementation (based on old specification) can be included in build by setting `ENABLE_METRICS_PREVIEW` preprocessor macro, and is included under `*/_metrics/*` directory. This would be eventually removed once the ongoing implemetation is stable.
20-
* [2]: The current Log Signal Implementation is Experimental, and will change as the current OpenTelemetry Log specification matures. The current implementation can be included in build by setting `ENABLE_LOGS_PREVIEW` preprocessor macro.
19+
* [1]: The development of the metrics API and SDK based on new stable
20+
specification is ongoing. The timelines would be available in release
21+
milestone. The earlier implementation (based on old specification) can be
22+
included in build by setting `ENABLE_METRICS_PREVIEW` preprocessor macro,
23+
and is included under `*/_metrics/*` directory. This would be eventually
24+
removed once the ongoing implemetation is stable.
25+
* [2]: The current Log Signal Implementation is Experimental, and will change as
26+
the current OpenTelemetry Log specification matures. The current
27+
implementation can be included in build by setting `ENABLE_LOGS_PREVIEW`
28+
preprocessor macro.
2129

2230
## OpenTelemetry Specification Compatibility Matrix
2331

@@ -26,7 +34,8 @@ The C++ [OpenTelemetry](https://opentelemetry.io/) client.
2634
| 1.0.0 | 1.0.0-rc4 | N/A [1] |
2735
| 1.0.0 | 1.0.0 | N/A |
2836

29-
* [1]: We don't have releases for opentelemetry-cpp contrib repo. This may change in future.
37+
* [1]: We don't have releases for opentelemetry-cpp contrib repo. This may
38+
change in future.
3039

3140
## Supported C++ Versions
3241

@@ -66,15 +75,18 @@ having C++ compiler with [supported C++ standards](#supported-c-versions).
6675

6776
## Dependencies
6877

69-
Please refer to [Dependencies.md](docs/dependencies.md) for OSS Dependencies and license requirements.
78+
Please refer to [Dependencies.md](docs/dependencies.md) for OSS Dependencies and
79+
license requirements.
7080

7181
## Installation
7282

7383
Please refer to [INSTALL.md](./INSTALL.md).
7484

7585
## Getting Started
7686

77-
As an application owner or the library author, you can find the getting started guide and reference documentation on [opentelemetry-cpp.readthedocs.io](https://opentelemetry-cpp.readthedocs.io/en/latest/)
87+
As an application owner or the library author, you can find the getting started
88+
guide and reference documentation on
89+
[opentelemetry-cpp.readthedocs.io](https://opentelemetry-cpp.readthedocs.io/en/latest/)
7890

7991
The `examples/simple` directory contains a minimal program demonstrating how to
8092
instrument a small library using a simple `processor` and console `exporter`,

‎Versioning.md‎

Lines changed: 21 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -19,20 +19,20 @@ buy may not work in applications using `opentelemetry 2.0.0`.
1919

2020
Refer to the [ABI Policy](./docs/abi-policy.md) for more details. To summarise:
2121

22-
* The API is header only, and uses ABI compliant interfaces. However, ABI stability
23-
is not guaranteed for SDK.
24-
* In case of ABI breaking changes, a new `inline namespace` version will
25-
be introduced, and the existing linked applications can continue using the older version
26-
unless they relink with newer version.
22+
* The API is header only, and uses ABI compliant interfaces. However, ABI
23+
stability is not guaranteed for SDK.
24+
* In case of ABI breaking changes, a new `inline namespace` version will be
25+
introduced, and the existing linked applications can continue using the older
26+
version unless they relink with newer version.
2727

2828
## Release Policy
2929

3030
* Release versions will follow [SemVer 2.0](https://semver.org/).
3131
* Only a single source package containing the API, SDK, and exporters which are
3232
required by the specification would be released. All these components are
33-
always versioned and released together. For example, any changes in one of the exporter
34-
would result in version update of the entire source package even though there is
35-
no changes in API, SDK and other exporters.
33+
always versioned and released together. For example, any changes in one of the
34+
exporter would result in version update of the entire source package even
35+
though there is no changes in API, SDK and other exporters.
3636
* Experimental releases: New (unstable) telemetry signals and features will be
3737
introduced behind feature flag protected by a preprocessor macro.
3838

@@ -65,16 +65,19 @@ Refer to the [ABI Policy](./docs/abi-policy.md) for more details. To summarise:
6565
allowed to break existing stable interfaces. Feature flags will be removed
6666
once we have a stable implementation for the signal.
6767

68-
* As an exception, small experimental features in otherwise stable signals/components
69-
mayn't necessarily be released under feature flag. These would be flagged as experimental
70-
by adding a `NOTE` in it's header file - either at the beginning of file, or as the comment for
71-
the experimental API methods. Also, if the complete header is experimental, it would be prefixed
72-
as `experimental_`. As an example, the semantic conventions for
73-
trace signal is experimental at the time of the writing and is within `experimental_semantic_conventions.h`
74-
75-
* Code under the "*::detail" namespace implements internal details,
76-
and is NOT part of public interface. Also, any API not documented in the [public
77-
documentation](https://opentelemetry-cpp.readthedocs.io/en/latest/) is NOT part of the public interface.
68+
* As an exception, small experimental features in otherwise stable
69+
signals/components mayn't necessarily be released under feature flag. These
70+
would be flagged as experimental by adding a `NOTE` in it's header file -
71+
either at the beginning of file, or as the comment for the experimental API
72+
methods. Also, if the complete header is experimental, it would be prefixed as
73+
`experimental_`. As an example, the semantic conventions for trace signal is
74+
experimental at the time of the writing and is within
75+
`experimental_semantic_conventions.h`
76+
77+
* Code under the "*::detail" namespace implements internal details, and is NOT
78+
part of public interface. Also, any API not documented in the [public
79+
documentation](https://opentelemetry-cpp.readthedocs.io/en/latest/) is NOT
80+
part of the public interface.
7881

7982
* GitHub releases will be made for all released versions.
8083

‎docs/building-with-stdlib.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -162,7 +162,9 @@ gcc-7 | C++17 | requires `gsl::span` for `std::span` im
162162
gcc-9+ | C++20 |
163163

164164
If SDK is compiled without standard library classes, then `nostd::variant`
165-
implementation internally uses a private snapshot of [Abseil Variant](https://github.com/abseil/abseil-cpp/blob/master/absl/types/variant.h) .
165+
implementation internally uses a private snapshot of [Abseil
166+
Variant](https://github.com/abseil/abseil-cpp/blob/master/absl/types/variant.h)
167+
.
166168

167169
Other modern C++ language features used by OpenTelemetry, e.g.
168170
`std::string_view` and `std::variant` are available in C++17 standard library.

‎docs/building-with-vs2019.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -136,7 +136,8 @@ instructions that detail how to [run build build tools in a docker container](ht
136136
build tooling. This script installs all build tools and builds all 3rd party
137137
dependencies from source using [vcpkg package manager](https://vcpkg.io/en/index.html).
138138
- Launch Visual Studio 2019 IDE.
139-
- Use `Open a local folder` option to open the folder where you cloned the source code.
139+
- Use `Open a local folder` option to open the folder where you cloned the
140+
source code.
140141
- Right-click on `CMakeLists.txt` and choose `Generate Cache for opentelemetry-cpp`.
141142
- In the top bar menu - select `Build -> Build All` to build SDK, Exporters and Tests.
142143
- You can use [Google Test Adapter](https://marketplace.visualstudio.com/items?itemName=ChristianSoltenborn.GoogleTestAdapter)

‎docs/cpp-metrics-api-design.md‎

Lines changed: 1 addition & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -139,7 +139,6 @@ private:
139139
};
140140
```
141141

142-
<!-- markdownlint-disable MD013 -->
143142
```cpp
144143
# meter_provider.h
145144
class MeterProvider
@@ -170,7 +169,7 @@ function.
170169
This interface consists of a set of **instrument constructors**, and a
171170
**facility for capturing batches of measurements.**
172171

173-
```cpp
172+
``` cpp
174173
# meter.h
175174
class Meter {
176175
public:
@@ -258,7 +257,6 @@ private:
258257
InstrumentationInfo instrumentationInfo_;
259258
}
260259
```
261-
<!-- markdownlint-enable MD013 -->
262260
263261
### Meter API Class Design Considerations
264262
@@ -354,7 +352,6 @@ call: `instrument.Add(x, labels)`.
354352
MUST support `RecordBatch` calling (where a single set of labels is applied to
355353
several metric instruments).
356354
357-
<!-- markdownlint-disable MD013 -->
358355
```cpp
359356
# metric.h
360357
@@ -516,15 +513,13 @@ private:
516513
void (*callback_)(ObserverResult<T>);
517514
};
518515
```
519-
<!-- markdownlint-enable MD013 -->
520516
521517
The Counter below is an example of one Metric instrument. It is important to
522518
note that in the Counter’s add function, it binds the labels to the instrument
523519
before calling add, then unbinds. Therefore all interactions with the
524520
aggregator take place through bound instruments and by extension, the
525521
BaseBoundInstrument Class.
526522
527-
<!-- markdownlint-disable MD013 -->
528523
```cpp
529524
template <class T>
530525
class BoundCounter: public BoundSynchronousInstrument{ //override bind?
@@ -599,7 +594,6 @@ class BoundUpDownSumObserver: public AsynchronousInstrument;
599594
class ValueObserver: public AsynchronousInstrument;
600595
class BoundValueObserver: public AsynchronousInstrument;
601596
```
602-
<!-- markdownlint-enable MD013 -->
603597

604598
### Metric Class Design Considerations
605599

‎docs/cpp-metrics-sdk-design.md‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -133,7 +133,6 @@ error.**
133133

134134
**Implementation:**
135135

136-
<!-- markdownlint-disable MD013 -->
137136
```cpp
138137
# meter.h / meter.cc
139138
class Meter : public API::Meter {
@@ -271,9 +270,7 @@ private:
271270
InstrumentationInfo instrumentationInfo_;
272271
};
273272
```
274-
<!-- markdownlint-enable MD013 -->
275273
276-
<!-- markdownlint-disable MD013 -->
277274
```cpp
278275
# record.h
279276
/*
@@ -316,7 +313,6 @@ private:
316313
nostd::variant<Aggregator<short>, Aggregator<int>, Aggregator<float>, Aggregator<Double>> aggregator_;
317314
};
318315
```
319-
<!-- markdownlint-enable MD013 -->
320316

321317
Metric instruments created from this Meter class will be stored in a map (or
322318
another, similar container [needs to be nostd]) called “metrics.” This is

‎docs/cpp-ostream-exporter-design.md‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -101,7 +101,6 @@ want to make the shutdown timeout configurable.
101101
In the OStreamExporter there is no cleanup to be done, so there is no need to
102102
use the timeout within the `Shutdown` function as it will never be blocking.
103103

104-
<!-- markdownlint-disable MD013 -->
105104
```cpp
106105
class StreamSpanExporter final : public sdktrace::SpanExporter
107106
{
@@ -162,7 +161,6 @@ public:
162161
}
163162
};
164163
```
165-
<!-- markdownlint-enable MD013 -->
166164

167165
## MetricsExporter
168166

0 commit comments

Comments
 (0)