|
#!/bin/bash |
|
# Copyright 2019 The Fuchsia Authors. All rights reserved. |
|
# Use of this source code is governed by a BSD-style license that can be |
|
# found in the LICENSE file. |
|
|
|
#### CATEGORY=Documentation |
|
#### PREBUILTS=${PREBUILT_JQ} ${PREBUILT_PYTHON3} |
|
### create markdown docs for fx subcommands |
|
|
|
## usage: fx helpdoc [OPTIONS] OUTPUT_PATH |
|
## |
|
## Create markdown documentation for fx and its subcommands, based on |
|
## the same metadata that is used to create the output of `fx help` |
|
## |
|
## --vendor create docs for subcommands in //vendor/*/scripts/devshell. |
|
## If specified, only vendor docs are documented. There's |
|
## no way to generate docs for vendor and non-vendor at the |
|
## same time. |
|
## --toc-prefix URL_PREFIX use URL_PREFIX instead of "/reference/tools/fx" |
|
## as an URL prefix in generated _toc.yaml files. |
|
## --escape-jinja escape jinja tags in fx help text to avoid |
|
## parsing errors in fuchsia.dev. |
|
## --no-deprecated do not create docs for deprecated subcommands |
|
## --no-contrib do not create docs for contrib scripts in //tools/devshell/contrib/* |
|
## --archive creates a compressed archive at OUTPUT_PATH. |
|
## If specified, output will be compressed |
|
## and OUTPUT_PATH must end with .tgz or .tar.gz. |
|
## This must be the last option specified before the OUTPUT_PATH |
|
## --depfile DEPFILENAME creates a depfile for helpdoc generation. Must be run with archive |
|
|
|
# The generated documentation is laid out with all commands in /cmd/<cmd>.md is to make the URL predictable and stable. Categories |
|
# are arbitrary texts and used to change often, it is undesirable that a category change invalidates the previous command help URL. |
|
# Since the table of contents for each category needs to be in a file named _toc.yaml, these files are generated in the per-category |
|
# directory along with a README.md, which links to the markdown in ../cmd. |
|
|
|
# shellcheck disable=SC1091 |
|
source "$(cd "$(dirname "${BASH_SOURCE[0]}")" >/dev/null 2>&1 && pwd)"/lib/vars.sh || exit $? |
|
# shellcheck disable=SC1091 |
|
source "$(cd "$(dirname "${BASH_SOURCE[0]}")" >/dev/null 2>&1 && pwd)"/lib/fx-cmd-locator.sh || exit $? |
|
|
|
categories=() |
|
|
|
function main { |
|
show_vendor=0 |
|
show_contrib=1 |
|
escape_jinja=0 |
|
show_deprecated=1 |
|
archive_output=0 |
|
archive_path= |
|
toc_prefix="/reference/tools/fx" |
|
create_depfile=0 |
|
while [[ $# -ne 0 ]]; do |
|
case $1 in |
|
--vendor) |
|
show_vendor=1 |
|
;; |
|
--toc-prefix) |
|
if [[ $# -lt 2 ]]; then |
|
fx-error "Invalid syntax" |
|
fx-command-help |
|
exit 1 |
|
fi |
|
shift |
|
toc_prefix="$1" |
|
;; |
|
--depfile) |
|
if [[ $# -lt 2 ]]; then |
|
fx-error "Invalid syntax" |
|
fx-command-help |
|
exit 1 |
|
fi |
|
shift |
|
depfile_prefix="$1" |
|
create_depfile=1 |
|
;; |
|
--no-deprecated) |
|
show_deprecated=0 |
|
;; |
|
--escape-jinja) |
|
escape_jinja=1 |
|
;; |
|
--no-contrib) |
|
show_contrib=0 |
|
;; |
|
--archive) |
|
archive_output=1 |
|
;; |
|
-h|--help) |
|
fx-command-help |
|
exit 0 |
|
;; |
|
-*) |
|
fx-error "Unknown argument $1" |
|
fx-command-help |
|
exit 1 |
|
;; |
|
*) |
|
break |
|
;; |
|
esac |
|
shift |
|
done |
|
|
|
if [[ $# -ne 1 ]]; then |
|
fx-error "No output path specified" |
|
fx-command-help |
|
return 1 |
|
fi |
|
|
|
base_out="$1" |
|
if [[ "${archive_output}" -eq 1 ]]; then |
|
if [[ $base_out != *.tgz ]] && [[ $base_out != *.tar.gz ]]; then |
|
fx-error "OUTPUT_PATH must end with .tgz or .tar.gz if the archive flag is specified: ${base_out}" |
|
fx-command-help |
|
exit 1 |
|
fi |
|
archive_path="$base_out" |
|
base_out="$(mktemp -d)" |
|
|
|
temp_dir="$base_out" |
|
base_out="${base_out}/helpdoc" |
|
mkdir "$base_out" |
|
trap 'cleanup' ERR INT TERM EXIT |
|
fi |
|
|
|
if [[ "${create_depfile}" -eq 1 ]]; then |
|
if [[ "${archive_output}" -eq 0 ]]; then |
|
fx-error "depfile currently not supported without archive_output" |
|
fx-command-help |
|
exit 1 |
|
fi |
|
# This creates the depfile without quoting the archive_path or any of |
|
# the dependencies labels/filenames. According to the MAKEFILE documentation |
|
# which defines the format of depfiles, it is not clear if quoting will correctly |
|
# deal with special characters, vs. using \ to escape them. |
|
initial_deps="${archive_path}: ../../scripts/fx ../../scripts/fx-help.awk |
|
${archive_path}: ../../tools/devshell/lib/fx-cmd-locator.sh ../../tools/devshell/lib/vars.sh |
|
${archive_path}: ../../tools/devshell/lib/fx-optional-features.sh ../../tools/devshell/lib/metrics.sh |
|
${archive_path}: ../../tools/devshell/lib/platform.sh " |
|
echo -n "$initial_deps" >> "${depfile_prefix}" |
|
for vendor_dir in "${FUCHSIA_DIR}"/vendor/*/scripts/devshell; do |
|
[[ -d "${vendor_dir}" ]] || continue |
|
for d in "${vendor_dir}"/*; do |
|
[[ -e "${d}" ]] || continue |
|
echo "vendor file ${d}" |
|
rel_path="$(realpath_relative_to_pwd "${d}")" |
|
printf %s "${rel_path} " >> "${depfile_prefix}" |
|
done |
|
done |
|
fi |
|
|
|
# Make the cmd subdirectory to hold the per-command generated markdown. |
|
mkdir -p "${base_out}/cmd" |
|
|
|
# initializes the main index.md |
|
{ |
|
echo "# fx - Fuchsia development commands" |
|
echo |
|
echo "\`fx\` is the entry-point for a set of subcommands that make many tasks related to Fuchsia development easier." |
|
echo |
|
echo "It contains a large number of subcommands. Run \`fx help\` to see all the available subcommands." |
|
echo "If you use bash or zsh as a shell, source \`scripts/fx-env.sh\` " |
|
echo "to get some auto-completion." |
|
echo |
|
echo "Also see the [global options and flags](fx.md) that affect all subcommands." |
|
echo |
|
echo "# fx subcommands" |
|
|
|
} > "${base_out}/index.md" |
|
|
|
{ |
|
echo "## fx command" |
|
echo |
|
echo "For help with specific subcommands, see [Overview page](index.md)." |
|
echo |
|
echo '```none' |
|
print-redacted-fx-help |
|
echo '```' |
|
echo |
|
echo "[fx source code](https://cs.opensource.google/fuchsia/fuchsia/+/main:scripts/fx)" |
|
} > "${base_out}/fx.md" |
|
|
|
if [[ "${show_vendor}" -eq 1 ]]; then |
|
for d in "${FUCHSIA_DIR}"/vendor/*/scripts/devshell; do |
|
if [[ -d "${d}" ]]; then |
|
vendor="${d%/scripts/devshell}" |
|
vendor="${vendor##*/}" |
|
{ |
|
echo |
|
echo "## ${vendor} subcommands" |
|
echo |
|
_md_main_table_header |
|
} >> "${base_out}/index.md" |
|
handle-directory "${d}" "vendor" |
|
fi |
|
done |
|
else |
|
{ |
|
echo |
|
echo "## Main subcommands" |
|
echo |
|
echo "Subcommands that are part of the [fx workflow](/docs/development/build/fx.md)." |
|
echo |
|
_md_main_table_header |
|
} >> "${base_out}/index.md" |
|
handle-directory "${FUCHSIA_DIR}/tools/devshell" "main" |
|
local d="${FUCHSIA_DIR}/tools/devshell/contrib" |
|
if [[ "${show_contrib}" -eq 1 && -d "${d}" ]]; then |
|
{ |
|
echo |
|
echo "## Contrib subcommands" |
|
echo |
|
echo "Subcommands that have been contributed by project members that have other levels of support, ownership, or both." |
|
echo "The [OWNERS file](https://cs.opensource.google/fuchsia/fuchsia/+/main:tools/devshell/contrib/OWNERS) in the" |
|
echo "contrib directory provides a pointer to the member that supports each script." |
|
echo |
|
_md_main_table_header |
|
} >> "${base_out}/index.md" |
|
handle-directory "${d}" "contrib" |
|
fi |
|
fi |
|
create-main-toc |
|
if [[ "${archive_output}" -eq 1 ]]; then |
|
tar -C "$temp_dir" -czvf "$archive_path" . |
|
fi |
|
|
|
} |
|
|
|
function realpath_relative_to_pwd { |
|
local path="$1" rp source target |
|
|
|
source="${PWD}" |
|
target="${path}" |
|
back= |
|
common_part="${source}" |
|
# shellcheck disable=SC2295 |
|
while [[ "${target#$common_part}" == "${target}" ]]; do |
|
common_part="$(dirname "${common_part}")" |
|
back="../${back}" |
|
done |
|
# shellcheck disable=SC2295 |
|
rp="${back}${target#$common_part/}" |
|
echo "${rp}" |
|
} |
|
|
|
function cleanup { |
|
if [[ -n "${_redacted_help_filter:-}" ]]; then |
|
rm -f "${_redacted_help_filter}" |
|
fi |
|
if [[ -d "$temp_dir" ]]; then |
|
rm -Rf "$temp_dir" |
|
fi |
|
} |
|
|
|
function _md_main_table_header { |
|
echo "Command | Category | Description" |
|
echo "------- | -------- | -----------" |
|
} |
|
|
|
function print-redacted-fx-help { |
|
local filter |
|
filter="$(mktemp)" |
|
_redacted_help_filter="${filter}" |
|
if [[ "${archive_output}" -eq 0 ]]; then |
|
trap '[[ -n "${_redacted_help_filter:-}" ]] && rm -f "${_redacted_help_filter}"' INT TERM EXIT |
|
fi |
|
cat > "${filter}" <<EOF |
|
NR==1 || NR==3, /^$/ { |
|
print |
|
} |
|
|
|
/^[^ ].*help flags.*:/,/^$/ { |
|
print |
|
} |
|
/^Global .*:/,/^$/ { |
|
print |
|
} |
|
EOF |
|
"${FUCHSIA_DIR}"/scripts/fx help --full | awk -f "${filter}" |
|
rm -f "${filter}" |
|
_redacted_help_filter="" |
|
} |
|
|
|
function handle-directory { |
|
local d="$1" |
|
local section="${2:-main}" |
|
local files=( "${d}"/* ) |
|
local -A reg_skip_names=() |
|
local -A reg_skip_scripts=() |
|
local -A reg_rows=() |
|
local -A legacy_files=() |
|
local -a all_names=() |
|
|
|
local reg_file |
|
if [[ -n "${vendor:-}" ]]; then |
|
reg_file="${FUCHSIA_DIR}/vendor/${vendor}/scripts/devshell/fx_host_tools.json" |
|
else |
|
reg_file="${FUCHSIA_DIR}/tools/devshell/fx_host_tools.json" |
|
fi |
|
if [[ -f "${reg_file}" ]]; then |
|
if [[ "${create_depfile}" -eq 1 && "${section}" != "contrib" ]]; then |
|
local rel_reg |
|
rel_reg="$(realpath_relative_to_pwd "${reg_file}")" |
|
printf %s "${rel_reg} " >> "${depfile_prefix}" |
|
fi |
|
|
|
local r_name r_cat r_contrib r_deprecated r_mode r_spec r_summary |
|
while IFS=$'\x1f' read -r r_name r_cat r_contrib r_deprecated r_mode r_spec r_summary; do |
|
[[ -n "${r_name}" ]] || continue |
|
reg_skip_names["${r_name}"]=1 |
|
if [[ "${r_mode}" == "script" ]]; then |
|
local clean_s="${r_spec#@//}" |
|
clean_s="${clean_s#//}" |
|
reg_skip_scripts["${FUCHSIA_DIR}/${clean_s}"]=1 |
|
fi |
|
if [[ "${section}" == "contrib" && "${r_contrib}" != "true" ]]; then |
|
continue |
|
fi |
|
if [[ "${section}" == "main" && "${r_contrib}" == "true" ]]; then |
|
continue |
|
fi |
|
if [[ "${section}" == "vendor" && "${show_contrib}" -eq 0 && "${r_contrib}" == "true" ]]; then |
|
continue |
|
fi |
|
reg_rows["${r_name}"]="${r_cat}"$'\x1f'"${r_contrib}"$'\x1f'"${r_deprecated}"$'\x1f'"${r_mode}"$'\x1f'"${r_spec}"$'\x1f'"${r_summary}" |
|
all_names+=( "${r_name}" ) |
|
done < <(_fx_cli_registry list --format=help-tsv --registry-file "${reg_file}" 2>/dev/null | awk -F '\t' '{ print $8 "\037" $2 "\037" $3 "\037" $4 "\037" $6 "\037" $7 "\037" $5 }' || true) |
|
fi |
|
|
|
local f rel_path base_cmd |
|
for f in "${files[@]}"; do |
|
if [[ "${create_depfile}" -eq 1 ]]; then |
|
rel_path="$(realpath_relative_to_pwd "${f}")" |
|
printf %s "${rel_path} " >> "${depfile_prefix}" |
|
fi |
|
|
|
if [[ -f "${f}" && ( -x "${f}" || "${f: -3}" == ".fx" ) ]]; then |
|
base_cmd="$(basename "${f}" ".fx")" |
|
if [[ -n "${reg_skip_names["${base_cmd}"]:-}" || -n "${reg_skip_scripts["${f}"]:-}" ]]; then |
|
continue |
|
fi |
|
if [[ -z "${legacy_files["${base_cmd}"]:-}" ]]; then |
|
legacy_files["${base_cmd}"]="${f}" |
|
all_names+=( "${base_cmd}" ) |
|
fi |
|
fi |
|
done |
|
|
|
local -a sorted_names=() |
|
if [[ ${#all_names[@]} -gt 0 ]]; then |
|
mapfile -t sorted_names < <(printf '%s\n' "${all_names[@]}" | LC_ALL=C sort -u) |
|
fi |
|
|
|
local cmd_name |
|
for cmd_name in "${sorted_names[@]}"; do |
|
[[ -n "${cmd_name}" ]] || continue |
|
if [[ -n "${reg_rows["${cmd_name}"]:-}" ]]; then |
|
_emit_registered_command_row "${cmd_name}" "${reg_rows["${cmd_name}"]}" |
|
elif [[ -n "${legacy_files["${cmd_name}"]:-}" ]]; then |
|
echo "Processing $(basename "${legacy_files["${cmd_name}"]}")" |
|
handle-command "${legacy_files["${cmd_name}"]}" |
|
fi |
|
done |
|
} |
|
|
|
|
|
function normalize { |
|
local str="$1" |
|
echo "${str}" | tr -s ', .' '_' | tr '[:upper:]' '[:lower:]' |
|
} |
|
|
|
function get_binary_metadata { |
|
local file="$1" |
|
local key="$2" |
|
awk -F ' *= *' -f - "${file}" <<EOF |
|
/^#### +${key} */ { |
|
print 1; |
|
} |
|
EOF |
|
} |
|
|
|
function get_metadata { |
|
local file="$1" |
|
local key="$2" |
|
awk -F ' *= *' -f - "${file}" <<EOF |
|
/^#### +${key} */ { |
|
print \$2; |
|
} |
|
EOF |
|
} |
|
|
|
function get_metadata_camelcase { |
|
local file="$1" |
|
local key="$2" |
|
awk -F ' *= *' -f - "${file}" <<EOF |
|
/^#### +${key} */ { |
|
print toupper(substr(\$2,1,1)) tolower(substr(\$2,2)); |
|
} |
|
EOF |
|
} |
|
|
|
function get_summary { |
|
local cmd_path="$1" |
|
sed -n '1,/^### /s/^### //p' < "${cmd_path}" | sed 's/_/\\_/g; s/*/\\*/g; s/|/\\|/g' |
|
} |
|
|
|
function create-main-toc { |
|
# initializes the global toc |
|
{ |
|
echo "toc:" |
|
echo "- title: Overview" |
|
echo " path: ${toc_prefix}/index.md" |
|
echo "- title: fx command" |
|
echo " path: ${toc_prefix}/fx.md" |
|
} > "${base_out}/_toc.yaml" |
|
|
|
# sort categories |
|
IFS=$'\n' sorted=($(sort -u <<< "${categories[*]}")) |
|
unset IFS |
|
|
|
for category in "${sorted[@]}"; do |
|
local norm_cat |
|
|
|
echo "Processing category ${category}" |
|
norm_cat="$(normalize "${category}")" |
|
# Make the category sub-dir to hold the toc. |
|
mkdir -p "${base_out}/${norm_cat}" |
|
# Appends the category to the global _toc.yaml |
|
{ |
|
echo "- title: \"${category} commands\"" |
|
echo " path: ${toc_prefix}/${norm_cat}/README.md" |
|
echo " section:" |
|
echo " - include: ${toc_prefix}/${norm_cat}/_toc.yaml" |
|
} >> "${base_out}/_toc.yaml" |
|
done |
|
} |
|
|
|
function get-category-title { |
|
local category="$1" |
|
if [[ -n "${vendor}" ]]; then |
|
echo "${category} fx subcommands for ${vendor}" |
|
else |
|
echo "${category} fx subcommands" |
|
fi |
|
} |
|
|
|
function maybe-add-category { |
|
local cat_base category norm_cat toc |
|
category="$1" |
|
norm_cat="$(normalize "${category}")" |
|
cat_base="${base_out}/${norm_cat}/README.md" |
|
toc="${base_out}/${norm_cat}/_toc.yaml" |
|
# Make the category sub-dir to hold the toc. |
|
mkdir -p "${base_out}/${norm_cat}" |
|
if [[ ! -f "${toc}" ]]; then |
|
# initializes the per-category _toc.yaml |
|
{ |
|
echo "toc:" |
|
} > "${toc}" |
|
|
|
# initializes the per-category index |
|
{ |
|
echo "# $(get-category-title "${category}")" |
|
echo |
|
echo "Command | Description" |
|
echo "------- | -----------" |
|
} > "${cat_base}" |
|
fi |
|
echo "${norm_cat}" |
|
} |
|
|
|
function escape-jinja { |
|
# the way fuchsia.dev processes jinja tags is complicated, so simple escaping |
|
# techniques like {% verbatim %} or {{ '{' }} don't work, and since the help |
|
# text for these commands are in a fenced block, regular html escaping also |
|
# doesn't work. The "hack" below mixes jinja escaping with html escaping in |
|
# order to avoid errors with the fuchsia.dev parser. |
|
sed "s/{%/{{ '{\​%' }}/g" |
|
} |
|
|
|
function _emit_command_doc { |
|
local cmd_name="$1" |
|
local category="$2" |
|
local deprecated="$3" |
|
local escaped_summary="$4" |
|
local rel_path="$5" |
|
local help_script_path="${6:-}" |
|
|
|
if [[ -z "${category}" ]]; then |
|
category="Other" |
|
fi |
|
|
|
local norm_cat |
|
norm_cat="$(maybe-add-category "${category}")" |
|
categories+=( "${category}" ) |
|
|
|
local deprecated_str="" |
|
if [[ "${deprecated}" == "1" || "${deprecated}" == "true" ]]; then |
|
if [[ "${show_deprecated}" -eq 0 ]]; then |
|
return |
|
fi |
|
deprecated_str="DEPRECATED! " |
|
fi |
|
|
|
local summary="${deprecated_str}${escaped_summary}" |
|
local cmd_url="cmd/${cmd_name}.md" |
|
local cat_url="${norm_cat}/README.md" |
|
local filename="${base_out}/${cmd_url}" |
|
|
|
{ |
|
if [[ -n "${vendor:-}" ]]; then |
|
echo "# ${deprecated_str}fx vendor ${vendor} ${cmd_name}" |
|
else |
|
echo "# ${deprecated_str}fx ${cmd_name}" |
|
fi |
|
echo "" |
|
echo "${summary}" |
|
echo |
|
echo '~~~~none' |
|
if [[ -n "${help_script_path}" && -f "${help_script_path}" ]]; then |
|
fx-print-command-help "${help_script_path}" | |
|
( [[ ${escape_jinja} -eq 0 ]] && cat || escape-jinja ) |
|
elif [[ -n "${vendor:-}" ]]; then |
|
echo "usage: fx vendor ${vendor} ${cmd_name} [--help]" |
|
else |
|
echo "usage: fx ${cmd_name} [--help]" |
|
fi |
|
echo |
|
echo '~~~~' |
|
if [[ -z "${vendor:-}" ]]; then |
|
echo |
|
echo "[${cmd_name} source code](https://cs.opensource.google/fuchsia/fuchsia/+/main:${rel_path})" |
|
fi |
|
} > "${filename}" |
|
|
|
{ |
|
echo "[${cmd_name}](../${cmd_url}) | ${summary}" |
|
} >> "${base_out}/${norm_cat}/README.md" |
|
|
|
{ |
|
echo "[${cmd_name}](${cmd_url}) | [${category}](${cat_url}) | ${summary}" |
|
} >> "${base_out}/index.md" |
|
|
|
{ |
|
echo "- title: \"${deprecated_str}${cmd_name}\"" |
|
echo " path: ${toc_prefix}/${cmd_url}" |
|
} >> "${base_out}/${norm_cat}/_toc.yaml" |
|
} |
|
|
|
function handle-command { |
|
local cmd_path="$1" |
|
local cmd_name category deprecated escaped_summary rel_path |
|
cmd_name="$(basename "${cmd_path}" ".fx")" |
|
category="$(get_metadata_camelcase "${cmd_path}" "CATEGORY")" |
|
deprecated="$(get_binary_metadata "${cmd_path}" "DEPRECATED")" |
|
escaped_summary="$(get_summary "${cmd_path}")" |
|
rel_path="${cmd_path#"${FUCHSIA_DIR}"/}" |
|
_emit_command_doc "${cmd_name}" "${category}" "${deprecated}" "${escaped_summary}" "${rel_path}" "${cmd_path}" |
|
} |
|
|
|
function _emit_registered_command_row { |
|
local -r cmd_name="$1" |
|
local -r row="$2" |
|
local raw_cat contrib deprecated mode spec raw_summary |
|
IFS=$'\x1f' read -r raw_cat contrib deprecated mode spec raw_summary <<< "${row}" |
|
|
|
local category="Other" |
|
if [[ -n "${raw_cat}" ]]; then |
|
local cat_lower="${raw_cat,,}" |
|
category="${cat_lower^}" |
|
fi |
|
|
|
local escaped_summary="${raw_summary}" |
|
escaped_summary="${escaped_summary//_/\\_}" |
|
escaped_summary="${escaped_summary//\*/\\*}" |
|
escaped_summary="${escaped_summary//|/\\|}" |
|
|
|
local rel_path help_script_path="" |
|
if [[ "${mode}" == "script" ]]; then |
|
local clean_script="${spec#@//}" |
|
rel_path="${clean_script#//}" |
|
local script_abs="${FUCHSIA_DIR}/${rel_path}" |
|
if [[ "${create_depfile}" -eq 1 && -f "${script_abs}" ]]; then |
|
local rel_script_dep |
|
rel_script_dep="$(realpath_relative_to_pwd "${script_abs}")" |
|
printf %s "${rel_script_dep} " >> "${depfile_prefix}" |
|
fi |
|
if [[ -f "${script_abs}" ]] && grep -q '^## ' "${script_abs}"; then |
|
help_script_path="${script_abs}" |
|
fi |
|
else |
|
local clean_target="${spec#@//}" |
|
clean_target="${clean_target#//}" |
|
local pkg_dir="${clean_target%%:*}" |
|
rel_path="${pkg_dir}/BUILD.bazel" |
|
fi |
|
|
|
_emit_command_doc "${cmd_name}" "${category}" "${deprecated}" "${escaped_summary}" "${rel_path}" "${help_script_path}" |
|
} |
|
|
|
main "$@" |