From 7bc86c956b78bb64ac8e4f35880348666f95adf7 Mon Sep 17 00:00:00 2001 From: Kian Meng Ang Date: Sat, 25 Sep 2021 10:33:07 +0800 Subject: [PATCH] Misc doc generation changes (#40) * Misc doc generation changes Besides other changes, this commit ensures the generated HTML doc for HexDocs.pm will become the main source doc for this Elixir library which leverage on ExDoc features. List of changes: * Fix spdx license id * Use common source url * Generate only html format * Add changelog to html page * Update gitignore * Update formatter config * Update missing dates in changelog * Refactor project config * Add license section * Disable warnings * Badges and more badges! * Clean up more docs and unused deps * MIX_ENV=test in CI for faster compiles * Fix compiler warning in test Co-authored-by: Greg Mefford --- .circleci/config.yml | 14 +++----- .gitignore | 4 ++- CHANGELOG.md | 14 ++++---- README.md | 21 ++++++++---- mix.exs | 44 ++++++++++++------------- mix.lock | 5 --- test/support/datadog_test_api_server.ex | 11 +++++-- 7 files changed, 58 insertions(+), 55 deletions(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index 6a5762b..343e4dd 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -5,21 +5,15 @@ version: 2 jobs: build: docker: - # specify the version here - - image: circleci/elixir:1.11 - - # Specify service dependencies here if necessary - # CircleCI maintains a library of pre-built images - # documented at https://circleci.com/docs/2.0/circleci-images/ - # - image: circleci/postgres:9.4 - + - image: cimg/elixir:1.11 + environment: + MIX_ENV: test working_directory: ~/spandex_datadog steps: - checkout - - # specify any bash command here prefixed with `run: ` - run: mix local.hex --force - run: mix local.rebar --force + - run: mix format --check-formatted - run: mix deps.get - run: mix compile --warnings-as-errors - run: mix test diff --git a/.gitignore b/.gitignore index fbb410b..05e0323 100644 --- a/.gitignore +++ b/.gitignore @@ -7,7 +7,7 @@ # The directory Mix downloads your dependencies sources to. /deps/ -# Where 3rd-party dependencies like ExDoc output generated docs. +# Where third-party dependencies like ExDoc output generated docs. /doc/ # Ignore .fetch files in case you like to edit your project deps locally. @@ -22,3 +22,5 @@ erl_crash.dump # Ignore package tarball (built via "mix hex.build"). spandex_datadog-*.tar +# Temporary files for e.g. tests. +/tmp/ diff --git a/CHANGELOG.md b/CHANGELOG.md index 938884c..b0764e6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,4 +1,4 @@ -# Change Log +# Changelog All notable changes to this project will be documented in this file. See [Conventional Commits](Https://conventionalcommits.org) for commit guidelines. @@ -20,7 +20,7 @@ See [Conventional Commits](Https://conventionalcommits.org) for commit guideline -## [0.6.0](https://github.com/spandex-project/spandex_datadog/compare/0.5.0...0.6.0) (2020-4-23) +## [0.6.0](https://github.com/spandex-project/spandex_datadog/compare/0.5.0...0.6.0) (2020-04-23) @@ -47,7 +47,7 @@ See [Conventional Commits](Https://conventionalcommits.org) for commit guideline * Ensure tags are converted to strings (#16) -## [0.4.0](https://github.com/spandex-project/spandex_datadog/compare/0.3.1...0.4.0) (2019-2-1) +## [0.4.0](https://github.com/spandex-project/spandex_datadog/compare/0.3.1...0.4.0) (2019-02-01) @@ -56,13 +56,13 @@ See [Conventional Commits](Https://conventionalcommits.org) for commit guideline * support elixir 1.8 via msgpax bump -## [0.3.1](https://github.com/spandex-project/spandex_datadog/compare/0.3.1...0.3.1) (2018-10-19) +## [0.3.1](https://github.com/spandex-project/spandex_datadog/compare/0.3.0...0.3.1) (2018-10-19) Initial release using automated changelog management # Changelog prior to automated change log management -## [0.3.0] +## [0.3.0] (2018-09-16) [0.3.0]: https://github.com/spandex-project/spandex_datadog/compare/v0.3.0...v0.2.0 @@ -70,7 +70,7 @@ Initial release using automated changelog management - `SpandexDatadog.Adapter.inject_context/3` added to support the new version of the `Spandex.Adapter` behaviour. -## [0.2.0] +## [0.2.0] (2018-08-31) [0.2.0]: https://github.com/spandex-project/spandex_datadog/compare/v0.2.0...v0.1.0 @@ -94,7 +94,7 @@ Initial release using automated changelog management - `SpandexDatadog.ApiServer.send_spans/2` is deprecated in favor of `SpandexDatadog.ApiServer.send_trace/2`. -## [0.1.0] +## [0.1.0] (2018-08-23) ### Added - Initial release of the `spandex_datadog` library separately from the diff --git a/README.md b/README.md index 104af4e..93a84b2 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,16 @@ # SpandexDatadog -[![CircleCI](https://circleci.com/gh/spandex-project/spandex_datadog.svg?style=svg)](https://circleci.com/gh/spandex-project/spandex_datadog) -[![Inline docs](http://inch-ci.org/github/spandex-project/spandex_datadog.svg)](http://inch-ci.org/github/spandex-project/spandex_datadog) -[![Coverage Status](https://coveralls.io/repos/github/spandex-project/spandex_datadog/badge.svg)](https://coveralls.io/github/spandex-project/spandex_datadog) -[![Hex pm](http://img.shields.io/hexpm/v/spandex_datadog.svg?style=flat)](https://hex.pm/packages/spandex_datadog) -[![SourceLevel](https://sourcelevel.io/github/spandex-project/spandex_datadog.svg)](https://sourcelevel.io/github/spandex-project/spandex_datadog) +[![Package Version](https://img.shields.io/hexpm/v/spandex_datadog.svg)](https://hex.pm/packages/spandex_datadog) +[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/spandex_datadog/) +[![Downloads](https://img.shields.io/hexpm/dt/spandex_datadog.svg)](https://hex.pm/packages/spandex_datadog) +[![License](https://img.shields.io/hexpm/l/spandex_datadog.svg)](https://github.com/spandex-project/spandex_datadog/blob/master/LICENSE) +[![Last Updated](https://img.shields.io/github/last-commit/spandex-project/spandex_datadog.svg)](https://github.com/spandex-project/spandex_datadog/commits/master) -A datadog adapter for the `spandex` library. +A datadog adapter for the `:spandex` library. ## Installation -The package can be installed by adding `spandex_datadog` to your list of +The package can be installed by adding `:spandex_datadog` to your list of dependencies in `mix.exs`: ```elixir @@ -148,3 +148,10 @@ processed concurrently before trace calls become synchronous. This concept of backpressure is very important, and strategies for switching to synchronous operation are often surprisingly far more performant than purely asynchronous strategies (and much more predictable). + + +## Copyright and License + +Copyright (c) 2021 Zachary Daniel & Greg Mefford + +Released under the MIT License, which can be found in the repository in [`LICENSE`](https://github.com/spandex-project/spandex_datadog/blob/master/LICENSE). diff --git a/mix.exs b/mix.exs index e1fef22..73c5ad6 100644 --- a/mix.exs +++ b/mix.exs @@ -1,19 +1,20 @@ defmodule SpandexDatadog.MixProject do use Mix.Project + @source_url "https://github.com/spandex-project/spandex_datadog" @version "1.1.0" def project do [ app: :spandex_datadog, - description: description(), - version: @version, - elixir: "~> 1.6", - start_permanent: Mix.env() == :prod, deps: deps(), - elixirc_paths: elixirc_paths(Mix.env()), + description: "A datadog API adapter for spandex.", docs: docs(), - package: package() + elixir: "~> 1.6", + elixirc_paths: elixirc_paths(Mix.env()), + package: package(), + start_permanent: Mix.env() == :prod, + version: @version ] end @@ -26,39 +27,36 @@ defmodule SpandexDatadog.MixProject do defp package do [ name: :spandex_datadog, - maintainers: ["Zachary Daniel", "Greg Mefford"], - licenses: ["MIT License"], - links: %{"GitHub" => "https://github.com/spandex-project/spandex_datadog"} + maintainers: ["Greg Mefford"], + licenses: ["MIT"], + links: %{ + "Changelog" => "https://hexdocs.pm/spandex_datadog/changelog.html", + "GitHub" => @source_url, + "Sponsor" => "https://github.com/sponsors/GregMefford" + } ] end - defp description do - """ - A datadog API adapter for spandex. - """ - end - defp elixirc_paths(:test), do: ["lib", "test/support"] defp elixirc_paths(_), do: ["lib"] defp docs do [ + extras: ["CHANGELOG.md", "README.md"], main: "readme", - extras: [ - "README.md" - ] + formatters: ["html"], + skip_undefined_reference_warnings_on: ["CHANGELOG.md"] ] end defp deps do [ - {:ex_doc, ">= 0.0.0", only: :dev}, - {:git_ops, "~> 2.0", only: [:dev]}, - {:inch_ex, "~> 2.0", only: [:dev, :test]}, + {:msgpax, "~> 2.2.1"}, {:spandex, "~> 3.0"}, {:telemetry, "~> 0.4"}, - {:httpoison, "~> 0.13 or ~> 1.0", only: :test}, - {:msgpax, "~> 2.2.1"} + # Dev- and test-only deps + {:ex_doc, ">= 0.0.0", only: :dev, runtime: false}, + {:httpoison, "~> 0.13 or ~> 1.0", only: :test} ] end end diff --git a/mix.lock b/mix.lock index ee7edda..9b1a211 100644 --- a/mix.lock +++ b/mix.lock @@ -1,15 +1,10 @@ %{ - "bunt": {:hex, :bunt, "0.2.0", "951c6e801e8b1d2cbe58ebbd3e616a869061ddadcc4863d0a2182541acae9a38", [:mix], [], "hexpm", "7af5c7e09fe1d40f76c8e4f9dd2be7cebd83909f31fee7cd0e9eadc567da8353"}, "certifi": {:hex, :certifi, "2.5.3", "70bdd7e7188c804f3a30ee0e7c99655bc35d8ac41c23e12325f36ab449b70651", [:rebar3], [{:parse_trans, "~>3.3", [hex: :parse_trans, repo: "hexpm", optional: false]}], "hexpm", "ed516acb3929b101208a9d700062d520f3953da3b6b918d866106ffa980e1c10"}, "earmark_parser": {:hex, :earmark_parser, "1.4.12", "b245e875ec0a311a342320da0551da407d9d2b65d98f7a9597ae078615af3449", [:mix], [], "hexpm", "711e2cc4d64abb7d566d43f54b78f7dc129308a63bc103fbd88550d2174b3160"}, "ex_doc": {:hex, :ex_doc, "0.23.0", "a069bc9b0bf8efe323ecde8c0d62afc13d308b1fa3d228b65bca5cf8703a529d", [:mix], [{:earmark_parser, "~> 1.4.0", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_elixir, "~> 0.14", [hex: :makeup_elixir, repo: "hexpm", optional: false]}], "hexpm", "f5e2c4702468b2fd11b10d39416ddadd2fcdd173ba2a0285ebd92c39827a5a16"}, - "git_cli": {:hex, :git_cli, "0.3.0", "a5422f9b95c99483385b976f5d43f7e8233283a47cda13533d7c16131cb14df5", [:mix], [], "hexpm", "78cb952f4c86a41f4d3511f1d3ecb28edb268e3a7df278de2faa1bd4672eaf9b"}, - "git_ops": {:hex, :git_ops, "2.4.2", "291a4f105dfa3d34cffa56cf8faf0e8c2699b49d3316270aa4881e75c62b1832", [:mix], [{:git_cli, "~> 0.2", [hex: :git_cli, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.0", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "bd9051c49e17d0dc2e0ae9306292f9f5f671d402227f5dda12e69a702198dec4"}, "hackney": {:hex, :hackney, "1.17.0", "717ea195fd2f898d9fe9f1ce0afcc2621a41ecfe137fae57e7fe6e9484b9aa99", [:rebar3], [{:certifi, "~>2.5", [hex: :certifi, repo: "hexpm", optional: false]}, {:idna, "~>6.1.0", [hex: :idna, repo: "hexpm", optional: false]}, {:metrics, "~>1.0.0", [hex: :metrics, repo: "hexpm", optional: false]}, {:mimerl, "~>1.1", [hex: :mimerl, repo: "hexpm", optional: false]}, {:parse_trans, "~>3.3", [hex: :parse_trans, repo: "hexpm", optional: false]}, {:ssl_verify_fun, "~>1.1.0", [hex: :ssl_verify_fun, repo: "hexpm", optional: false]}, {:unicode_util_compat, "~>0.7.0", [hex: :unicode_util_compat, repo: "hexpm", optional: false]}], "hexpm", "64c22225f1ea8855f584720c0e5b3cd14095703af1c9fbc845ba042811dc671c"}, "httpoison": {:hex, :httpoison, "1.8.0", "6b85dea15820b7804ef607ff78406ab449dd78bed923a49c7160e1886e987a3d", [:mix], [{:hackney, "~> 1.17", [hex: :hackney, repo: "hexpm", optional: false]}], "hexpm", "28089eaa98cf90c66265b6b5ad87c59a3729bea2e74e9d08f9b51eb9729b3c3a"}, "idna": {:hex, :idna, "6.1.1", "8a63070e9f7d0c62eb9d9fcb360a7de382448200fbbd1b106cc96d3d8099df8d", [:rebar3], [{:unicode_util_compat, "~>0.7.0", [hex: :unicode_util_compat, repo: "hexpm", optional: false]}], "hexpm", "92376eb7894412ed19ac475e4a86f7b413c1b9fbb5bd16dccd57934157944cea"}, - "inch_ex": {:hex, :inch_ex, "2.0.0", "24268a9284a1751f2ceda569cd978e1fa394c977c45c331bb52a405de544f4de", [:mix], [{:bunt, "~> 0.2", [hex: :bunt, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: false]}], "hexpm", "96d0ec5ecac8cf63142d02f16b7ab7152cf0f0f1a185a80161b758383c9399a8"}, - "jason": {:hex, :jason, "1.2.2", "ba43e3f2709fd1aa1dce90aaabfd039d000469c05c56f0b8e31978e03fa39052", [:mix], [{:decimal, "~> 1.0 or ~> 2.0", [hex: :decimal, repo: "hexpm", optional: true]}], "hexpm", "18a228f5f0058ee183f29f9eae0805c6e59d61c3b006760668d8d18ff0d12179"}, "makeup": {:hex, :makeup, "1.0.5", "d5a830bc42c9800ce07dd97fa94669dfb93d3bf5fcf6ea7a0c67b2e0e4a7f26c", [:mix], [{:nimble_parsec, "~> 0.5 or ~> 1.0", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "cfa158c02d3f5c0c665d0af11512fed3fba0144cf1aadee0f2ce17747fba2ca9"}, "makeup_elixir": {:hex, :makeup_elixir, "0.15.0", "98312c9f0d3730fde4049985a1105da5155bfe5c11e47bdc7406d88e01e4219b", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.1", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "75ffa34ab1056b7e24844c90bfc62aaf6f3a37a15faa76b07bc5eba27e4a8b4a"}, "metrics": {:hex, :metrics, "1.0.1", "25f094dea2cda98213cecc3aeff09e940299d950904393b2a29d191c346a8486", [:rebar3], [], "hexpm", "69b09adddc4f74a40716ae54d140f93beb0fb8978d8636eaded0c31b6f099f16"}, diff --git a/test/support/datadog_test_api_server.ex b/test/support/datadog_test_api_server.ex index e00c19c..384e344 100644 --- a/test/support/datadog_test_api_server.ex +++ b/test/support/datadog_test_api_server.ex @@ -3,8 +3,15 @@ defmodule SpandexDatadog.Test.Support.TestApiServer do Simply sends the data that would have been sent to datadog to self() as a message so that the test can assert on payloads that would have been sent to datadog """ + + alias Spandex.Trace + alias SpandexDatadog.ApiServer + def send_trace(trace, _opts \\ []) do - formatted = SpandexDatadog.ApiServer.format(trace) - send(self(), {:sent_datadog_spans, formatted}) + send(self(), {:sent_datadog_spans, format(trace)}) + end + + defp format(%Trace{spans: spans, priority: priority, baggage: baggage}) do + Enum.map(spans, fn span -> ApiServer.format(span, priority, baggage) end) end end