From 9b0146c7d74cd97d6d741b3459ab0c6cbc90c906 Mon Sep 17 00:00:00 2001 From: kw7oe Date: Sat, 21 Aug 2021 17:13:36 +0800 Subject: [PATCH 1/6] Generate opentelemetry docs with ExDoc --- docs.config | 4 ++++ docs.sh | 18 ++++++++++++++++++ rebar.config | 6 ++++-- 3 files changed, 26 insertions(+), 2 deletions(-) create mode 100644 docs.config create mode 100755 docs.sh diff --git a/docs.config b/docs.config new file mode 100644 index 00000000..97370f21 --- /dev/null +++ b/docs.config @@ -0,0 +1,4 @@ +{source_url, <<"https://github.com/open-telemetry/opentelemetry-erlang">>}. +{extras, [<<"README.md">>, <<"LICENSE">>, <<"VERSIONING">>]}. +{main, <<"readme">>}. +{proglang, erlang}. diff --git a/docs.sh b/docs.sh new file mode 100755 index 00000000..b10f4b0e --- /dev/null +++ b/docs.sh @@ -0,0 +1,18 @@ +#!/bin/bash +set -e + +# Setup: +# +# # 1. install OTP 24+ +# # 2. install ExDoc: +# $ mix escript.install github elixir-lang/ex_doc + +rebar3 compile +rebar3 as docs edoc +version=1.0.0-rc.2 + +ex_doc "opentelemetry" $version "_build/default/lib/opentelemetry/ebin" \ + --source-ref v${version} \ + --config docs.config $@ \ + --output "apps/opentelemetry/doc" + diff --git a/rebar.config b/rebar.config index 3fadd6f6..c948b7c7 100644 --- a/rebar.config +++ b/rebar.config @@ -19,9 +19,11 @@ {docs, [{deps, [edown]}, {edoc_opts, - [{doclet, edown_doclet}, + [ + {doclet, edoc_doclet_chunks}, + {layout, edoc_layout_chunks}, {preprocess, true}, - {dir, "edoc"}, + {dir, "_build/default/lib/opentelemetry/doc"}, {subpackages, true}]}]}, {bench, [{deps, [benchee]}, From 0ee49262c65f61bb516af87a74a47d7e4e684a99 Mon Sep 17 00:00:00 2001 From: kw7oe Date: Sat, 21 Aug 2021 17:18:31 +0800 Subject: [PATCH 2/6] Modify VERSIONING to be Markdown file to looks better in ExDoc --- VERSIONING => VERSIONING.md | 0 docs.config | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename VERSIONING => VERSIONING.md (100%) diff --git a/VERSIONING b/VERSIONING.md similarity index 100% rename from VERSIONING rename to VERSIONING.md diff --git a/docs.config b/docs.config index 97370f21..a6caa66c 100644 --- a/docs.config +++ b/docs.config @@ -1,4 +1,4 @@ {source_url, <<"https://github.com/open-telemetry/opentelemetry-erlang">>}. -{extras, [<<"README.md">>, <<"LICENSE">>, <<"VERSIONING">>]}. +{extras, [<<"README.md">>, <<"LICENSE">>, <<"VERSIONING.md">>]}. {main, <<"readme">>}. {proglang, erlang}. From 297c832ad3154b950e719ff0a304aa6873ec46ff Mon Sep 17 00:00:00 2001 From: kw7oe Date: Sat, 21 Aug 2021 17:28:01 +0800 Subject: [PATCH 3/6] Generate opentelemetry_exporter docs with ExDoc --- apps/opentelemetry_exporter/docs.config | 5 +++++ apps/opentelemetry_exporter/rebar.config | 10 ++++++++++ docs.sh | 4 ++++ 3 files changed, 19 insertions(+) create mode 100644 apps/opentelemetry_exporter/docs.config diff --git a/apps/opentelemetry_exporter/docs.config b/apps/opentelemetry_exporter/docs.config new file mode 100644 index 00000000..49b31ca6 --- /dev/null +++ b/apps/opentelemetry_exporter/docs.config @@ -0,0 +1,5 @@ +{source_url, <<"https://github.com/open-telemetry/opentelemetry-erlang">>}. +{extras, [<<"apps/opentelemetry_exporter/README.md">>, +<<"apps/opentelemetry_exporter/LICENSE">>]}. +{main, <<"readme">>}. +{proglang, erlang}. diff --git a/apps/opentelemetry_exporter/rebar.config b/apps/opentelemetry_exporter/rebar.config index 2ee03895..f2d52d44 100644 --- a/apps/opentelemetry_exporter/rebar.config +++ b/apps/opentelemetry_exporter/rebar.config @@ -7,3 +7,13 @@ {gpb_opts, [{module_name_prefix, "opentelemetry_exporter_"}, {module_name_suffix, "_pb"}, {i, "apps/opentelemetry_exporter/opentelemetry-proto/"}]}]}. + +{profiles, + [{docs, [{deps, [edown]}, + {edoc_opts, + [ + {doclet, edoc_doclet_chunks}, + {layout, edoc_layout_chunks}, + {preprocess, true}, + {dir, "_build/default/lib/opentelemetry_exporter/doc"}, + {subpackages, true}]}]}]}. diff --git a/docs.sh b/docs.sh index b10f4b0e..5412b9b5 100755 --- a/docs.sh +++ b/docs.sh @@ -16,3 +16,7 @@ ex_doc "opentelemetry" $version "_build/default/lib/opentelemetry/ebin" \ --config docs.config $@ \ --output "apps/opentelemetry/doc" +ex_doc "opentelemetry_exporter" $version "_build/default/lib/opentelemetry_exporter/ebin" \ + --source-ref v${version} \ + --config apps/opentelemetry_exporter/docs.config $@ \ + --output "apps/opentelemetry_exporter/doc" From 8f03d3347d5ee2191224434cbab4a9464ca00c4e Mon Sep 17 00:00:00 2001 From: kw7oe Date: Sat, 21 Aug 2021 18:07:36 +0800 Subject: [PATCH 4/6] Add docs and fix docs formatting --- .../src/opentelemetry_exporter.erl | 34 +++++++++++++------ 1 file changed, 23 insertions(+), 11 deletions(-) diff --git a/apps/opentelemetry_exporter/src/opentelemetry_exporter.erl b/apps/opentelemetry_exporter/src/opentelemetry_exporter.erl index 3aa73bdd..520bb812 100644 --- a/apps/opentelemetry_exporter/src/opentelemetry_exporter.erl +++ b/apps/opentelemetry_exporter/src/opentelemetry_exporter.erl @@ -19,21 +19,30 @@ %% %% `opentelemetry_exporter' application enevironment options are: %% -%% * `otlp_endpoint': The URL to send traces and metrics to, for traces the -%% path `v1/traces' is appended to the path in the URL. -%% * `otlp_traces_endpoint': URL to send only traces to. This takes precedence -%% for exporting traces and the path of the URL is kept as is, no suffix is -%% appended. -%% * `otlp_headers': Additional headers to add to export requests. -%% * `otlp_traces_headers': Additional headers to add to only trace export requests. +%%
    +%%
  • +%% `otlp_endpoint': The URL to send traces and metrics to, for traces the +%% path `v1/traces' is appended to the path in the URL. +%%
    • +%%
  • `otlp_traces_endpoint': URL to send only traces to. This takes precedence +%% for exporting traces and the path of the URL is kept as is, no suffix is +%% appended. +%%
    • +%%
  • `otlp_headers': Additional headers to add to export requests.
    • +%%
  • +%% `otlp_traces_headers': Additional headers to add to only trace export %% requests. +%%
    • +%%
%% %% There also corresponding OS environment variables can also set those %% configuration values: %% -%% * `OTEL_EXPORTER_OTLP_ENDPOINT' -%% * `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT' -%% * `OTEL_EXPORTER_OTLP_HEADERS' -%% * `OTEL_EXPORTER_OTLP_TRACES_HEADERS' +%%
    +%%
  • `OTEL_EXPORTER_OTLP_ENDPOINT'
    • +%%
  • `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT'
    • +%%
  • `OTEL_EXPORTER_OTLP_HEADERS'
    • +%%
  • `OTEL_EXPORTER_OTLP_TRACES_HEADERS'
    • +%%
%% %% @end %%%------------------------------------------------------------------------- @@ -66,6 +75,7 @@ grpc_metadata :: map() | undefined, endpoints :: [uri_string:uri_map()]}). +%% @doc Initialize the exporter based on the provided configuration. init(Opts0) -> Opts1 = merge_with_environment(Opts0), Endpoints = endpoints(maps:get(endpoints, Opts1, ?DEFAULT_ENDPOINTS)), @@ -99,6 +109,7 @@ init(Opts0) -> protocol=http_json}} end. +%% @doc Export OTLP protocol telemery data to the configured endpoints. export(_Tab, _Resource, #state{protocol=http_json}) -> {error, unimplemented}; export(Tab, Resource, #state{protocol=http_protobuf, @@ -143,6 +154,7 @@ export(Tab, Resource, #state{protocol=grpc, error end. +%% @doc Shutdown the exporter. shutdown(#state{channel_pid=undefined}) -> ok; shutdown(#state{channel_pid=Pid}) -> From 07645e4fb908da80cc187c4da8a8390d4854d31b Mon Sep 17 00:00:00 2001 From: kw7oe Date: Sat, 21 Aug 2021 18:26:02 +0800 Subject: [PATCH 5/6] Configure otel and otel exporter .app.src for publishing docs to Hex.pm --- apps/opentelemetry/src/opentelemetry.app.src | 1 + apps/opentelemetry_exporter/src/opentelemetry_exporter.app.src | 1 + 2 files changed, 2 insertions(+) diff --git a/apps/opentelemetry/src/opentelemetry.app.src b/apps/opentelemetry/src/opentelemetry.app.src index ff16c097..ec77b4db 100644 --- a/apps/opentelemetry/src/opentelemetry.app.src +++ b/apps/opentelemetry/src/opentelemetry.app.src @@ -26,6 +26,7 @@ ]}]}, {modules, []}, + {doc, "doc"}, {licenses, ["Apache-2.0"]}, {links, [{"GitHub", "https://github.com/open-telemetry/opentelemetry-erlang"}]} ]}. diff --git a/apps/opentelemetry_exporter/src/opentelemetry_exporter.app.src b/apps/opentelemetry_exporter/src/opentelemetry_exporter.app.src index 1ce43ad7..8acf26e3 100644 --- a/apps/opentelemetry_exporter/src/opentelemetry_exporter.app.src +++ b/apps/opentelemetry_exporter/src/opentelemetry_exporter.app.src @@ -13,6 +13,7 @@ {env,[]}, {modules, []}, + {doc, "doc"}, {licenses, ["Apache-2.0"]}, {links, [{"GitHub", "https://github.com/open-telemetry/opentelemetry-erlang"}]} ]}. From d6d7a9e34dd809139224361f0161394007685ab8 Mon Sep 17 00:00:00 2001 From: Kai Date: Sun, 22 Aug 2021 11:30:55 +0800 Subject: [PATCH 6/6] Remove 'as docs' in docs.sh as suggested Co-authored-by: Tristan Sloughter --- docs.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs.sh b/docs.sh index 5412b9b5..83609502 100755 --- a/docs.sh +++ b/docs.sh @@ -8,7 +8,7 @@ set -e # $ mix escript.install github elixir-lang/ex_doc rebar3 compile -rebar3 as docs edoc +rebar3 edoc version=1.0.0-rc.2 ex_doc "opentelemetry" $version "_build/default/lib/opentelemetry/ebin" \