Generate docs with ExDoc

apps/opentelemetry/src/opentelemetry.app.src

@@ -25,6 +25,7 @@
                         ]}]},
   {modules, []},
 
+  {doc, "doc"},
   {licenses, ["Apache-2.0"]},
   {links, [{"GitHub", "https://github.com/open-telemetry/opentelemetry-erlang"}]}
  ]}.

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}.

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}]}]}]}.

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"}]}
  ]}.

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.
+%% <ul>
+%%   <li>
+%%     `otlp_endpoint': The URL to send traces and metrics to, for traces the
+%%     path `v1/traces' is appended to the path in the URL.
+%%   </li>
+%%   <li>`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.
+%%   </li>
+%%   <li>`otlp_headers': Additional headers to add to export requests.</li>
+%%   <li>
+%%     `otlp_traces_headers': Additional headers to add to only trace export %% requests.
+%%   </li>
+%% </ul>
 %%
 %% 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'
+%% <ul>
+%%   <li>`OTEL_EXPORTER_OTLP_ENDPOINT'</li>
+%%   <li>`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT'</li>
+%%   <li>`OTEL_EXPORTER_OTLP_HEADERS'</li>
+%%   <li>`OTEL_EXPORTER_OTLP_TRACES_HEADERS'</li>
+%% </ul>
 %%
 %% @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}) ->

docs.config

@@ -0,0 +1,4 @@
+{source_url, <<"https://github.com/open-telemetry/opentelemetry-erlang">>}.
+{extras, [<<"README.md">>, <<"LICENSE">>, <<"VERSIONING.md">>]}.
+{main, <<"readme">>}.
+{proglang, erlang}.

docs.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+set -e
+
+# Setup:
+#
+#     # 1. install OTP 24+
+#     # 2. install ExDoc:
+#     $ mix escript.install github elixir-lang/ex_doc
+
+rebar3 compile
+rebar3 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"
+
+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"

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]},