From 1576c9795ffda735b27ce7ae9bab392c61bf2598 Mon Sep 17 00:00:00 2001 From: Frank McGeough Date: Mon, 10 Jun 2024 15:31:33 -0400 Subject: [PATCH 1/6] Provide basics to generate doc with ex_doc --- .gitignore | 1 + Makefile | 4 ++++ rebar.config | 18 ++++++++++++++++++ 3 files changed, 23 insertions(+) diff --git a/.gitignore b/.gitignore index fee065d..3a6e9fa 100644 --- a/.gitignore +++ b/.gitignore @@ -16,3 +16,4 @@ rebar.lock *.log *.iml .idea/* +.DS_Store diff --git a/Makefile b/Makefile index 357abd8..1383e12 100644 --- a/Makefile +++ b/Makefile @@ -52,6 +52,10 @@ edoc: profile=edown edoc: @$(rebar_cmd) edoc +.PHONY: ex_doc +ex_doc: + @$(rebar_cmd) ex_doc + .PHONY: dialyze dialyze: compile @$(rebar_cmd) dialyzer diff --git a/rebar.config b/rebar.config index 9813fce..b6a1870 100644 --- a/rebar.config +++ b/rebar.config @@ -27,3 +27,21 @@ {xref_checks, [undefined_function_calls, undefined_functions, locals_not_used, deprecated_function_calls, deprecated_functions]}. + +{project_plugins, [rebar3_hex, rebar3_ex_doc]}. + +{hex, [ + {doc, #{provider => ex_doc}} +]}. + +{ex_doc, [ + {extras, [ + {"README.md", #{title => "Overview"}}, + {"changelog.md", #{title => "ChangeLog"}}, + {"LICENSE", #{title => "License"}}, + {"NOTICE", #{title => "Notice"}} + ]}, + {main, "README.md"}, + {source_url, "https://github.com/kafka4beam/kafka_protocol"}, + {api_reference, true} +]}. From bad5b3cc8f66f3d85a520189cef28eee3e14a373 Mon Sep 17 00:00:00 2001 From: Frank McGeough Date: Mon, 10 Jun 2024 15:38:12 -0400 Subject: [PATCH 2/6] Resolve issue with backticks and ex_doc --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index af8413f..49aaec2 100644 --- a/README.md +++ b/README.md @@ -50,7 +50,7 @@ To test with an existing kafka cluster set below environment variables: - `KPRO_TEST_KAFKA_TOPIC_NAME`: Topic name for message produce/fetch test. - `KPRO_TEST_KAFKA_TOPIC_LAT_NAME`: Topic name for message produce/fetch test with `message.timestamp.type=LogAppendTime` set. - `KPRO_TEST_KAFKA_SASL_USER_PASS_FILE`: A text file having two lines for username and password. -- `KPRO_TEST_SSL_TRUE`: Set to 'TRUE' or 'true' or '1' to use `ssl => true' in connection config (if kafka ca is trusted already) +- `KPRO_TEST_SSL_TRUE`: Set to `TRUE` or `true` or '1' to use `ssl => true` in connection config (if kafka ca is trusted already) - `KPRO_TEST_SSL_CA_CERT_FILE`: Ca cert file - `KPRO_TEST_SSL_KEY_FILE`: Client private key file - `KPRO_TEST_SSL_CERT_FILE`: Client cert file From 28254bc80937029023e5e51fdbb29dcb92e94be4 Mon Sep 17 00:00:00 2001 From: Frank McGeough Date: Thu, 13 Jun 2024 09:08:51 -0400 Subject: [PATCH 3/6] Fix typo in doc --- src/kpro.erl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/kpro.erl b/src/kpro.erl index 70bea9e..a9c34a5 100644 --- a/src/kpro.erl +++ b/src/kpro.erl @@ -360,7 +360,7 @@ connect(Endpoint, ConnConfig) -> connect_any(Endpoints, ConnConfig) -> kpro_brokers:connect_any(Endpoints, ConnConfig). -%% @doc Sotp connection process. +%% @doc Stop connection process. -spec close_connection(connection()) -> ok. close_connection(Connection) -> kpro_connection:stop(Connection). From 5d8b6d84a5ea51872b70ca433a304e2c34a39657 Mon Sep 17 00:00:00 2001 From: Frank McGeough Date: Thu, 13 Jun 2024 09:21:09 -0400 Subject: [PATCH 4/6] Modified to align with how brod uses ex_doc. api_reference is false and changelog appears first in left nav --- rebar.config | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rebar.config b/rebar.config index b6a1870..f093792 100644 --- a/rebar.config +++ b/rebar.config @@ -36,12 +36,12 @@ {ex_doc, [ {extras, [ - {"README.md", #{title => "Overview"}}, {"changelog.md", #{title => "ChangeLog"}}, + {"README.md", #{title => "Overview"}}, {"LICENSE", #{title => "License"}}, {"NOTICE", #{title => "Notice"}} ]}, {main, "README.md"}, {source_url, "https://github.com/kafka4beam/kafka_protocol"}, - {api_reference, true} + {api_reference, false} ]}. From 170a6a907ad7d1bac95c128e3c6a529ece56533f Mon Sep 17 00:00:00 2001 From: Frank McGeough Date: Thu, 13 Jun 2024 09:23:17 -0400 Subject: [PATCH 5/6] Set homepage_url to hexdocs url --- rebar.config | 1 + 1 file changed, 1 insertion(+) diff --git a/rebar.config b/rebar.config index f093792..994bb84 100644 --- a/rebar.config +++ b/rebar.config @@ -42,6 +42,7 @@ {"NOTICE", #{title => "Notice"}} ]}, {main, "README.md"}, + {homepage_url, "https://hexdocs.pm/kafka_protocol"}, {source_url, "https://github.com/kafka4beam/kafka_protocol"}, {api_reference, false} ]}. From 1a5c411222a07be5042c210a5affaed96f832e07 Mon Sep 17 00:00:00 2001 From: Frank McGeough Date: Thu, 13 Jun 2024 09:31:43 -0400 Subject: [PATCH 6/6] Modify Github workflow to use ex_doc instead of edoc --- .github/workflows/ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 5b61798..fbba291 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -52,7 +52,7 @@ jobs: # Compile - name: Compile run: | - rebar3 do compile, dialyzer, edoc, xref + rebar3 do compile, dialyzer, ex_doc, xref # Tests - name: Run tests