From 3f2487d1b11ac134b434417b930c9c48aa4e50e0 Mon Sep 17 00:00:00 2001 From: Lukas Larsson Date: Wed, 19 Jun 2024 14:00:19 +0200 Subject: [PATCH 1/5] Fix ex_doc warnings --- lib/tftp/src/tftp.erl | 2 +- make/ex_doc.exs | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/tftp/src/tftp.erl b/lib/tftp/src/tftp.erl index dc2fbf1d53e5..8378b00186f9 100644 --- a/lib/tftp/src/tftp.erl +++ b/lib/tftp/src/tftp.erl @@ -49,7 +49,7 @@ This is a complete implementation of the following IETF standards: The only feature that not is implemented in this release is the "netascii" transfer mode. -The [start/](`start/3`)function starts a daemon process which, listens +The [start](`start/1`) function starts a daemon process which, listens for UDP packets on a port. When it receives a request for read or write it spawns a temporary server process which handles the actual transfer of the file. On the client side the diff --git a/make/ex_doc.exs b/make/ex_doc.exs index 606ccac3a6ea..4561df526d32 100644 --- a/make/ex_doc.exs +++ b/make/ex_doc.exs @@ -151,7 +151,7 @@ current_datetime = System.os_time() |> DateTime.from_unix!(:native) config = [ proglang: :erlang, source_url_pattern: source_url_pattern, - assets: Path.join(cwd, "/assets"), + assets: %{ Path.join(cwd, "/assets") => "assets" }, logo: Path.join(:code.root_dir(), "system/doc/assets/erlang-logo.png"), before_closing_head_tag: fn _ -> "" end, before_closing_footer_tag: fn _ -> From 8d18ce9bc375b54c7a11948ed0a67f614bf0db22 Mon Sep 17 00:00:00 2001 From: Lukas Larsson Date: Wed, 19 Jun 2024 14:01:27 +0200 Subject: [PATCH 2/5] otp: Add support for warnings as errors for ex_doc We check the output of ex_doc to see if there are any warnings emitted and if there are then we exit the build. --- erts/configure | 1 - erts/configure.ac | 1 - lib/common_test/doc/Makefile | 1 + make/doc.mk | 8 +++++--- make/ex_doc_wrapper | 32 ++++++++++++++++++++++++++++---- 5 files changed, 34 insertions(+), 9 deletions(-) diff --git a/erts/configure b/erts/configure index 4a89d597e7d0..13fd9f3410df 100755 --- a/erts/configure +++ b/erts/configure @@ -7331,7 +7331,6 @@ fi done if test -z "$EX_DOC"; then - EX_DOC="$ERL_TOP/make/ex_doc_wrapper" { printf "%s\n" "$as_me:${as_lineno-$LINENO}: WARNING: No 'ex_doc' command found: it will (optionally) be downloaded when building the HTML documentation " >&5 printf "%s\n" "$as_me: WARNING: No 'ex_doc' command found: it will (optionally) be downloaded when building the HTML documentation " >&2;} fi diff --git a/erts/configure.ac b/erts/configure.ac index 9185e62a1796..20e2660bab59 100644 --- a/erts/configure.ac +++ b/erts/configure.ac @@ -474,7 +474,6 @@ fi AC_CHECK_PROGS(EX_DOC, ex_doc) if test -z "$EX_DOC"; then - EX_DOC="$ERL_TOP/make/ex_doc_wrapper" AC_MSG_WARN([No 'ex_doc' command found: it will (optionally) be downloaded when building the HTML documentation ]) fi diff --git a/lib/common_test/doc/Makefile b/lib/common_test/doc/Makefile index 66722a56f7c5..236b312853af 100644 --- a/lib/common_test/doc/Makefile +++ b/lib/common_test/doc/Makefile @@ -26,6 +26,7 @@ include $(ERL_TOP)/make/$(TARGET)/otp.mk include ../vsn.mk VSN=$(COMMON_TEST_VSN) APPLICATION=common_test +EX_DOC_WARNINGS_AS_ERRORS=false # ---------------------------------------------------- # Release Target diff --git a/make/doc.mk b/make/doc.mk index 8425938ca99e..f0dcfb5b8e39 100644 --- a/make/doc.mk +++ b/make/doc.mk @@ -52,15 +52,17 @@ else DOC_TARGETS?=html endif +EX_DOC_WARNINGS_AS_ERRORS?=true + docs: $(DOC_TARGETS) chunks: HTML_DEPS?=$(wildcard $(APP_EBIN_DIR)/*.beam) $(wildcard *.md) $(wildcard */*.md) $(wildcard assets/*) -$(HTMLDIR)/index.html: $(HTML_DEPS) docs.exs - $(gen_verbose)ERL_FLAGS="-pz $(ERL_TOP)/erts/ebin" \ - $(EX_DOC) $(EX_DOC_FORMATS) --homepage-url "$(INDEX_DIR)/index.html" "$(APPLICATION)" $(VSN) $(APP_EBIN_DIR) -o "$(HTMLDIR)" -c $(ERL_TOP)/make/ex_doc.exs +$(HTMLDIR)/index.html: $(HTML_DEPS) docs.exs $(ERL_TOP)/make/ex_doc.exs + $(gen_verbose)EX_DOC_WARNINGS_AS_ERRORS=$(EX_DOC_WARNINGS_AS_ERRORS) ERL_FLAGS="-pz $(ERL_TOP)/erts/ebin" \ + $(ERL_TOP)/make/ex_doc_wrapper $(EX_DOC_FORMATS) --homepage-url "$(INDEX_DIR)/index.html" "$(APPLICATION)" $(VSN) $(APP_EBIN_DIR) -o "$(HTMLDIR)" -c $(ERL_TOP)/make/ex_doc.exs html: $(HTMLDIR)/index.html diff --git a/make/ex_doc_wrapper b/make/ex_doc_wrapper index f82c219e1544..23f6229013fa 100755 --- a/make/ex_doc_wrapper +++ b/make/ex_doc_wrapper @@ -4,9 +4,9 @@ ARGS=("$@") set -eo pipefail {0} -if command -v ex_doc &> /dev/null; then - exec ex_doc "${ARGS[@]}" -else +EX_DOC=$(command -v ex_doc || true) + +if [ -z "${EX_DOC}" ]; then echo -n "Could not find ex_doc! " read -p "Do you want to download latest ex_doc from github? (y/n)? " -n 1 -r echo @@ -15,7 +15,7 @@ else if $ERL_TOP/otp_build download_ex_doc; then read -p "Press any key to continue..." -n 1 -r echo "continuing" - exec ex_doc "${ARGS[@]}" + EX_DOC=$(command -v ex_doc || true) else exit 1 fi @@ -23,3 +23,27 @@ else exit 1 fi fi + +## The below bash magic captures the output of stderr into OUTPUT while still printing +## everything we get to stdout and stderr. This is done by: + +## 1. duplicating the stdout (1) and stderr (2) streams to fd 3 and 4 respectively. +exec 3>&1 4>&2 + +## Running the command where we redirect stderr to fd 1 and stdout to fd 3. +## We then use tee on the stderr (which is now fd 1) to print that to fd 4 +OUTPUT="$( { "${EX_DOC}" "${ARGS[@]}"; } 2>&1 1>&3 | tee /dev/fd/4 )" + +## Close fd 3 and 4 +exec 3>&- 4>&- + +if [ "${EX_DOC_WARNINGS_AS_ERRORS}" != "false" ]; then + if echo "${OUTPUT}" | grep "warning:" 1>/dev/null; then + echo "ex_doc emitted warnings" + ## Touch the config file in order to re-trigger make + if [ -f "docs.exs" ]; then + touch "docs.exs" + fi + exit 1; + fi +fi From 3c3d26bd198c68f9ae23ab0a78d188055321ffb1 Mon Sep 17 00:00:00 2001 From: Lukas Larsson Date: Wed, 19 Jun 2024 14:06:47 +0200 Subject: [PATCH 3/5] Use escript to launch ex_doc for nix to work --- erts/configure | 5 +++++ erts/configure.ac | 3 +++ make/{ex_doc_wrapper => ex_doc_wrapper.in} | 2 +- 3 files changed, 9 insertions(+), 1 deletion(-) rename make/{ex_doc_wrapper => ex_doc_wrapper.in} (93%) diff --git a/erts/configure b/erts/configure index 13fd9f3410df..b0bc1111d503 100755 --- a/erts/configure +++ b/erts/configure @@ -26902,6 +26902,9 @@ ac_config_files="$ac_config_files emulator/$host/Makefile:emulator/Makefile.in e ac_config_files="$ac_config_files ../make/make_emakefile:../make/make_emakefile.in" +ac_config_files="$ac_config_files ../make/ex_doc_wrapper:../make/ex_doc_wrapper.in" + + ac_config_files="$ac_config_files ../lib/os_mon/c_src/$host/Makefile:../lib/os_mon/c_src/Makefile.in ../lib/runtime_tools/c_src/$host/Makefile:../lib/runtime_tools/c_src/Makefile.in" @@ -27615,6 +27618,7 @@ do "lib_src/$host/Makefile") CONFIG_FILES="$CONFIG_FILES lib_src/$host/Makefile:lib_src/Makefile.in" ;; "../make/$host/otp.mk") CONFIG_FILES="$CONFIG_FILES ../make/$host/otp.mk:../make/otp.mk.in" ;; "../make/make_emakefile") CONFIG_FILES="$CONFIG_FILES ../make/make_emakefile:../make/make_emakefile.in" ;; + "../make/ex_doc_wrapper") CONFIG_FILES="$CONFIG_FILES ../make/ex_doc_wrapper:../make/ex_doc_wrapper.in" ;; "../lib/os_mon/c_src/$host/Makefile") CONFIG_FILES="$CONFIG_FILES ../lib/os_mon/c_src/$host/Makefile:../lib/os_mon/c_src/Makefile.in" ;; "../lib/runtime_tools/c_src/$host/Makefile") CONFIG_FILES="$CONFIG_FILES ../lib/runtime_tools/c_src/$host/Makefile:../lib/runtime_tools/c_src/Makefile.in" ;; "../make/install_dir_data.sh") CONFIG_FILES="$CONFIG_FILES ../make/install_dir_data.sh:../make/install_dir_data.sh.in" ;; @@ -28171,6 +28175,7 @@ printf "%s\n" "$as_me: $ac_file is unchanged" >&6;} case $ac_file$ac_mode in "../make/make_emakefile":F) chmod +x ../make/make_emakefile ;; + "../make/ex_doc_wrapper":F) chmod +x ../make/ex_doc_wrapper ;; "../make/install_dir_data.sh":F) chmod +x ../make/install_dir_data.sh ;; esac diff --git a/erts/configure.ac b/erts/configure.ac index 20e2660bab59..ddf6317c262e 100644 --- a/erts/configure.ac +++ b/erts/configure.ac @@ -3676,6 +3676,9 @@ AC_CONFIG_FILES([ AC_CONFIG_FILES([../make/make_emakefile:../make/make_emakefile.in], [chmod +x ../make/make_emakefile]) +AC_CONFIG_FILES([../make/ex_doc_wrapper:../make/ex_doc_wrapper.in], + [chmod +x ../make/ex_doc_wrapper]) + dnl dnl The ones below should be moved to their respective lib dnl diff --git a/make/ex_doc_wrapper b/make/ex_doc_wrapper.in similarity index 93% rename from make/ex_doc_wrapper rename to make/ex_doc_wrapper.in index 23f6229013fa..c2eed4917dcc 100755 --- a/make/ex_doc_wrapper +++ b/make/ex_doc_wrapper.in @@ -32,7 +32,7 @@ exec 3>&1 4>&2 ## Running the command where we redirect stderr to fd 1 and stdout to fd 3. ## We then use tee on the stderr (which is now fd 1) to print that to fd 4 -OUTPUT="$( { "${EX_DOC}" "${ARGS[@]}"; } 2>&1 1>&3 | tee /dev/fd/4 )" +OUTPUT="$( { escript@EXEEXT@ "${EX_DOC}" "${ARGS[@]}"; } 2>&1 1>&3 | tee /dev/fd/4 )" ## Close fd 3 and 4 exec 3>&- 4>&- From 0a5025eb50c6911b310c6c7d3ad8a0ebcc4cc962 Mon Sep 17 00:00:00 2001 From: Lukas Larsson Date: Thu, 20 Jun 2024 10:26:06 +0200 Subject: [PATCH 4/5] Read ex_doc from environment if set --- make/ex_doc_wrapper.in | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/make/ex_doc_wrapper.in b/make/ex_doc_wrapper.in index c2eed4917dcc..8f9b06df31b3 100755 --- a/make/ex_doc_wrapper.in +++ b/make/ex_doc_wrapper.in @@ -4,7 +4,10 @@ ARGS=("$@") set -eo pipefail {0} -EX_DOC=$(command -v ex_doc || true) +## If EX_DOC is not set to a file, we search the PATH for it using command -v +if [ ! -f "${EX_DOC}" ]; then + EX_DOC=$(command -v ex_doc || true) +fi if [ -z "${EX_DOC}" ]; then echo -n "Could not find ex_doc! " From 75913d77764482d0531c087bc21d83de4a25704e Mon Sep 17 00:00:00 2001 From: Lukas Larsson Date: Wed, 19 Jun 2024 14:18:39 +0200 Subject: [PATCH 5/5] Update gitignore --- .gitignore | 2 +- system/doc/top/.gitignore | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index a9d88a7bf9ee..0329c75ef567 100644 --- a/.gitignore +++ b/.gitignore @@ -142,7 +142,7 @@ JAVADOC-GENERATED /doc /make/output.mk -/make/emd2exml +/make/ex_doc_wrapper /make/make_emakefile /make/install_dir_data.sh diff --git a/system/doc/top/.gitignore b/system/doc/top/.gitignore index 461d1a1dd2ca..85edf9eb6316 100644 --- a/system/doc/top/.gitignore +++ b/system/doc/top/.gitignore @@ -7,3 +7,4 @@ testing documentation system man_index.md +README.md