From 7c22d2d93d9e1498d4afa7b5c4ac5fe36d7a4429 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C3=A9ter=20G=C3=B6m=C3=B6ri?= Date: Sun, 13 Oct 2019 22:47:54 -0500 Subject: [PATCH] Update docs - include xprof_core docs (use OTP 24 edoc + latest ExDoc) - publish to hexdocs --- .github/workflows/ci.yml | 41 ++++++++++++++++++++++++++---- Makefile | 22 +++++++++++++--- apps/xprof/src/xprof.app.src | 1 + apps/xprof_core/src/xprof_core.erl | 37 +++++++++++++++++++-------- doc/docs.exs | 5 ++-- doc/src/querysyntax.md | 4 +-- rebar.config | 8 +++++- 7 files changed, 94 insertions(+), 24 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 835841b2..7276ad83 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -20,7 +20,7 @@ jobs: - otp_version: 23 elixir_version: 1.10.3 new_rebar: true - # hdr_histogram up to 0.4.0 fails to compile with OTP 23 + # hdr_histogram up to 0.4.0 fails to compile with OTP 23+ erl_hist: true - otp_version: 22 @@ -30,7 +30,6 @@ jobs: new_rebar: true send_coverage: true run_dialyzer: true - build_docs: true - otp_version: 20 @@ -70,15 +69,47 @@ jobs: run: make dialyzer timeout-minutes: 8 - - if: matrix.build_docs - run: make doc - - if: matrix.send_coverage && success() run: ./rebar3 as test coveralls send env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} continue-on-error: true + test_docs: + name: Test generating documentation + runs-on: ubuntu-latest + + strategy: + matrix: + include: + - elixir: 1.12.x + otp_version: 24 + new_rebar: true + # hdr_histogram up to 0.4.0 fails to compile with OTP 23+ + erl_hist: true + + steps: + - uses: actions/checkout@v2 + + - uses: erlef/setup-beam@v1 + with: + otp-version: ${{matrix.otp_version}} + elixir-version: ${{matrix.elixir}} + + - if: matrix.new_rebar + run: curl -O -L https://github.com/erlang/rebar3/releases/download/3.15.2/rebar3 && chmod +x ./rebar3 + + - if: matrix.erl_hist + run: echo "XPROF_ERL_HIST=true" >> $GITHUB_ENV + + - name: Cache hex packages + uses: actions/cache@v2 + with: + path: $HOME/.cache/rebar3 + key: 24-rebar3-cache + + - run: make gen_ex_doc + test_jiffy: name: Test different json lib (OTP ${{ matrix.otp_version }}) runs-on: ubuntu-latest diff --git a/Makefile b/Makefile index f2a73df4..7029f01c 100644 --- a/Makefile +++ b/Makefile @@ -1,6 +1,8 @@ JS_PRIV=apps/xprof_gui/priv BIN_DIR:=node_modules/.bin VERSION:=$(shell grep vsn apps/xprof/src/xprof.app.src | cut -d '"' -f 2) +DOC_EBIN_DIR=./_build/docs/lib/xprof_core/ebin/ +DOC_CHUNKS_DIR=./_build/docs/lib/xprof_core/doc/chunks # this will update cowboy version based on rebar.config overwriting the lock file ifdef COWBOY_VERSION @@ -50,6 +52,7 @@ test_jiffy: doc: ./rebar3 edoc +# ex_doc requires Elixir ~> 1.10 ~/.mix/escripts/ex_doc: mix escript.install hex ex_doc --force @@ -58,8 +61,18 @@ doc: -e 's|doc/assets/|assets/|' \ -e '1 s|\[!\[.*||' README.md > ./doc/src/readme.md -gen_ex_doc: ~/.mix/escripts/ex_doc ./doc/docs.exs ./doc/src/readme.md ./doc/src/querysyntax.md - ~/.mix/escripts/ex_doc XProf $(VERSION) "doc/ebin" -c ./doc/docs.exs +# This step requires a relatively new rebar3 (somewhere between 3.5.2 and 3.13.0) +# Older versions set source in compile module_info to `_build/docs/lib/xprof_core/src/xprof_core.erl` +# instead of `apps/xprof_core/src/xprof_core.erl` +# which results in wrong links in ex_doc to github source code +$(DOC_CHUNKS_DIR)/xprof_core.chunk: ./apps/xprof_core/src/xprof_core.erl + $(MAYBE_UPDATE_COWBOY) + $(MAYBE_UNLOCK_HIST) + rebar3 as docs edoc + ls $(DOC_CHUNKS_DIR)/* | grep -v xprof_core.chunk | xargs rm + +gen_ex_doc: ~/.mix/escripts/ex_doc ./doc/docs.exs ./doc/src/readme.md $(DOC_CHUNKS_DIR)/xprof_core.chunk + ~/.mix/escripts/ex_doc XProf $(VERSION) $(DOC_EBIN_DIR) -c ./doc/docs.exs dialyzer: $(MAYBE_UPDATE_COWBOY) @@ -69,4 +82,7 @@ dialyzer: publish: ./rebar3 as publish hex publish --deps_from_config -.PHONY: compile dev dev_back_end dev_front_end npm bootstrap_front_end test_front_end build_prod_front_end test doc gen_ex_doc dialyzer publish +publish_docs: gen_ex_doc + ./rebar3 as publish hex docs + +.PHONY: compile dev dev_back_end dev_front_end npm bootstrap_front_end test_front_end build_prod_front_end test doc gen_ex_doc dialyzer publish publish_docs diff --git a/apps/xprof/src/xprof.app.src b/apps/xprof/src/xprof.app.src index 0b5b5c4f..ee0e06a0 100644 --- a/apps/xprof/src/xprof.app.src +++ b/apps/xprof/src/xprof.app.src @@ -11,6 +11,7 @@ ,{env,[]} ,{modules, []} ,{files, ["rebar.config", "src/"]} + ,{doc, "doc"} ,{licenses, ["BSD-3-Clause"]} ,{maintainers, ["Marcin Kasprowicz", "Marcin Kolodziej", "Michal Niec", "Pawel Pikula", diff --git a/apps/xprof_core/src/xprof_core.erl b/apps/xprof_core/src/xprof_core.erl index 39064619..4d2a4409 100644 --- a/apps/xprof_core/src/xprof_core.erl +++ b/apps/xprof_core/src/xprof_core.erl @@ -101,6 +101,7 @@ expand_query(Query) -> end. %% @doc Get loaded modules and functions (MFAs) that match the query string. +%% %% Used for autocomplete suggestions on the GUI. -spec get_matching_mfas_pp(binary()) -> [MFA :: binary()]. get_matching_mfas_pp(Query) -> @@ -116,7 +117,9 @@ monitor_pp(Query) -> monitor_pp(Query, []). %% @doc Start monitoring based on the specified query string with additional -%% parameters. Additional parameters have precedence overthe same keys in the +%% parameters. +%% +%% Additional parameters have precedence overthe same keys in the %% query. -spec monitor_pp(binary(), [{binary(), binary()}]) -> ok | {error, Reason :: already_traced | string()}. @@ -145,7 +148,9 @@ get_all_monitored() -> xprof_core_tracer:all_monitored(). %% @doc Return metrics gathered for the given function since the given -%% timestamp. Each item contains a timestamp and the corresponding histogram +%% timestamp. +%% +%% Each item contains a timestamp and the corresponding histogram %% metrics values. -spec get_data(xprof_core:mfa_id(), timestamp()) -> [Item] | {error, not_found} when Item :: [{time, timestamp()} | {HistKey, number()}], @@ -155,6 +160,8 @@ get_all_monitored() -> get_data(MFA, TimeStamp) -> xprof_core_trace_handler:data(MFA, TimeStamp). +%% @doc Return metrics gathered for the given function formatted +%% according to the active syntax mode. get_data_pp(MFA, TimeStamp) -> case xprof_core_trace_handler:data(MFA, TimeStamp) of {error, _} = Error -> @@ -177,7 +184,7 @@ get_called_funs(MFA) -> xprof_core_vm_info:get_called_funs(MFA). %% @doc Return list of called functions formatted according to the -%% active syntax mode +%% active syntax mode. -spec get_called_funs_pp(xprof_core:mfa_id()) -> [MFA :: binary()]. get_called_funs_pp(MFA) -> ModeCb = xprof_core_lib:get_mode_cb(), @@ -188,14 +195,16 @@ get_called_funs_pp(MFA) -> %% Global trace status %% -%% @doc Turn on tracing for one or all processes. Additionally tracing can be -%% paused and resumed for the same process specification (one or all) that was -%% given earlier. +%% @doc Turn on tracing for one or all processes. +%% +%% Additionally tracing can be paused and resumed for the same process +%% specification (one or all) that was given earlier. -spec trace(pid() | all | pause | resume) -> ok. trace(PidOrSpec) -> xprof_core_tracer:trace(PidOrSpec). %% @doc Return current tracing state. +%% %% (The `initialized' status is basically the same as `paused', additionally %% meaning that no tracing was started yet since xprof was started) -spec get_trace_status() -> {pid() | all, Status :: initialized | running | paused | overflow}. @@ -239,6 +248,7 @@ get_captured_data_pp(MFA, Offset) -> Error end. +%% @private args_res2proplist({Index, Pid, CallTime, Args, Res}, ModeCb) -> [{id, Index}, {pid, ModeCb:fmt_term(Pid)}, @@ -246,6 +256,7 @@ args_res2proplist({Index, Pid, CallTime, Args, Res}, ModeCb) -> {args, ModeCb:fmt_term(Args)}, {res, format_result(Res, ModeCb)}]. +%% @private format_result({return_from, Term}, ModeCb) -> ModeCb:fmt_term(Term); format_result({exception_from, {Class, Reason}}, ModeCb) -> @@ -284,20 +295,22 @@ rr(Mod) -> xprof_core_records:load_records(Mod). %% @doc Remove all record definitions. -%% (similar to shell command ```rf('_')''') +%% (similar to shell command `` rf('_') '') -spec rf() -> ok. rf() -> xprof_core_records:forget_records(). -%% @doc Remove selected record definitions. RecNames is a record name or a -%% list of record names. To remove all record definitions, use '_'. +%% @doc Remove selected record definitions. +%% +%% The argument can be a record name or a list of record names. To +%% remove all record definitions, use `` '_' ''. %% (similar to shell command `rf/1') -spec rf(atom() | [atom()]) -> ok. rf(RecNameOrNames) -> xprof_core_records:forget_records(RecNameOrNames). %% @doc Return all stored record definitions. -%% (Similar to shell command `rl()') +%% (Similar to shell command `rl/0') -spec rl() -> [tuple()]. rl() -> xprof_core_records:get_record_defs(). @@ -311,7 +324,9 @@ rl() -> set_mode(Mode) -> xprof_core_lib:set_mode(Mode). -%% @doc Get syntax mode, if not set explicitely it will be autodetected. +%% @doc Get syntax mode. +%% +%% If not set explicitely it will be autodetected. -spec get_mode() -> xprof_core:mode(). get_mode() -> xprof_core_lib:get_mode(). diff --git a/doc/docs.exs b/doc/docs.exs index 4c6fb91b..62e4fc39 100644 --- a/doc/docs.exs +++ b/doc/docs.exs @@ -5,9 +5,10 @@ "doc/src/commands.md": [] ], api_reference: false, - output: "doc/html/", + output: "apps/xprof/doc", assets: "doc/assets", - logo: "./apps/xprof_gui/priv/build/xprof_icon.png", + logo: "apps/xprof_gui/priv/build/xprof_icon.png", + proglang: "erlang", source_url: "https://github.com/Appliscale/xprof", homepage_url: "http://xprof.appliscale.io", ] diff --git a/doc/src/querysyntax.md b/doc/src/querysyntax.md index 2d33b4e0..951d5674 100644 --- a/doc/src/querysyntax.md +++ b/doc/src/querysyntax.md @@ -26,7 +26,7 @@ give a function definition instead of arity. This gives the user the full power of match specifications and can be used both to selectively measure duration of function calls that match complicated filters and to capture only part of the arguments. The function has the same -limitations as `dbg:fun2ms/1`. (See [Match Specifications in +limitations as [`dbg:fun2ms/1`](`:dbg.fun2ms/1`). (See [Match Specifications in Erlang](http://erlang.org/doc/apps/erts/match_spec.html) and [ms\_transform](http://erlang.org/doc/man/ms_transform.html)). @@ -113,7 +113,7 @@ simple query or an XProf-flavoured match-spec fun. The Erlang syntax is similar to a record, ```erlang -#cmd param1: {"val", 1}, mfa: mod:fun(_) +#cmd param1 = {"val", 1}, mfa = mod:fun(_) ``` while the Elixir syntax is similar to a struct, both without the curly brackets. diff --git a/rebar.config b/rebar.config index 99328b5e..57a509a1 100644 --- a/rebar.config +++ b/rebar.config @@ -20,8 +20,14 @@ {dev, [{deps, [ {sync, "0.1.3"} ]} ]}, + {docs, + [{minimum_otp_vsn, "24.0"}, %% edoc can generate doc chunks since OTP 24 + {edoc_opts, [{doclet, edoc_doclet_chunks}, + {layout, edoc_layout_chunks}, + {dir, "_build/docs/lib/xprof_core/doc"}]} + ]}, {publish, - [{plugins, [ {rebar3_hex, {git, "https://github.com/gomoripeti/rebar3_hex.git", {tag, "deps-3"}}} ]} + [{plugins, [ {rebar3_hex, {git, "https://github.com/gomoripeti/rebar3_hex.git", {tag, "deps-4"}}} ]} ]} ]}.