#!/bin/bash
# dev/docs/index - package source reference index support

set -e

lib_load 'dev/docs/color'


######
# Source File Index

# docs_gen_html_index() - Generates documentation index file
docs_gen_html_index(){
	run_mkdir "$package_docs_refdir"

	local tmp=$(cmd_tempfile)
	docs_gen_index_html > "$tmp"

	local index="$package_docs_refdir/index.html"
	run mv "$tmp" "$index"
}

docs_gen_index_html() {
	html_doc docs_gen_index_head docs_gen_index_body
}

docs_gen_index_head() {
	html_stylesheet "$(docs_css_filename)"
}

docs_gen_index_body() {
	docs_gen_index_header
	for_each docs_gen_index_section src libs conf
	docs_gen_index_footer
}

docs_gen_index_header() {
	html_anchor_func "top" \
		html_h1 "$(html_code "$PKG") Programming Reference"

	html_p "The source files have been sorted into three sections:"
	html_ul	\
		"$(html_li_func html_url '#src' "Tool Scripts")" \
		"$(html_li_func html_url '#libs' "Library Scripts")" \
		"$(html_li_func html_url '#conf' "Configuration Files")"

	local allurl=$(html_url 'all.deps.pdf' 'View the dependency graph')
	html_div "$allurl for all Tool and Library Scripts."

	html_h2 "Script File Reference"

	html_p "For each file, links are provided to the following pages:"
	html_ul \
		$(html_li "Extracted Reference Documentation" \
		$(html_ul \
			$(html_li "reStructuredText ($(html_code rst))") \
			$(html_li "Stylized Source Code ($(html_code raw))"))) \
		$(html_li "Dependency Graphs ($(html_code pdf svg dot))")
}

docs_gen_index_footer() {
	docs_gen_footer
}


######
# File Sections

docs_gen_index_section() {
	local dir=$1

	local -a files=()
	docs_file_list files "$dir"

	docs_gen_index_section_header "$dir"
	for_each docs_gen_index_group '' "${GROUP_ORDER[@]}"
}

docs_gen_index_section_header() {
	local dir=$1

	local section url rturl
	case "$dir" in
	(conf)
		section="Configuration Files"
		;;
	(src)
		section="Tool Scripts"
		url="tools.deps.pdf"
		;;
	(libs)
		section="Library Scripts"
		url="libraries.deps.pdf"
		;;
	esac

	html_h2_func doc_gen_index_section_title

	[ "$url" ] || return 0
	local hurl=$(html_url "$url" "dependency graph")
	local -l lsec=$section
	html_div "View the $hurl for all $lsec."
}

doc_gen_index_section_title() {
	html_anchor "$dir" "$section"
	echo -n ' ('
	html_code_func html_url "#top" "top"
	echo -n ')'
}


######
# Script Groups

# is_docs_gen_index_group_extension() - Determines whether the
# current group consists of top-level exensions.
# Returns: Success if ``$group_name`` is `null`.
is_docs_gen_index_group_extension() { [ -z "$group_name" ]; }

# docs_gen_index_group() - Generates documentation for a given
# script group ($1).  If the group name is empty, then generates
# documentation for top-level extension scripts.
# $1 - Name of script group.
docs_gen_index_group() {
	has_args 1 "$@"
	local group_name=$1
	if is_docs_gen_index_group_extension; then
		docs_gen_index_extension
	else
		docs_gen_index_subgroup
	fi
}

# docs_gen_index_extension() - Generates documentation for top-level
# runtime and extension libraries.
docs_gen_index_extension() {
	local tmp
	tmp=$(cmd_tempfile)
	docs_gen_index_group_files >"$tmp"
	[ -s "$tmp" ] || return 0

	html_h3 "Extensions"
	html_ul_file "$tmp"
}

# docs_gen_index_subgroup() - Generates documentation for a single
# script group.
docs_gen_index_subgroup() {
	local tmp
	tmp=$(cmd_tempfile)
	docs_gen_index_group_files >"$tmp"
	if [ -s "$tmp" ]; then
		local name=$(html_code "$group_name")
		local desc=${GROUP_NAMES[$group_name]}
		html_h3 "$desc ($name)"
		html_ul_file "$tmp"
	fi
}

# docs_gen_index_group_files() - Generates the index file the files in
# a single group.
docs_gen_index_group_files() {
	for_each docs_gen_index_group_file "${files[@]}"
}

# docs_gen_index_group_file() - Generates an index entry for a single
# file in a script group.
docs_gen_index_group_file() {
	local file=$1
	local name=${file#*/}
	if is_docs_gen_index_group_extension; then
		[ "${name/\//}" = "$name" ] || return 0
	else
		str_startswith "$name" "$group_name/" || return 0
	fi
	docs_gen_index_file "$file"
}


######
# File Entries

docs_gen_index_file() {
	html_li_func docs_gen_index_entry "$1"
}

docs_gen_index_entry() {
	local file=$1

	local base=${file%.in}
	local name=${base#*/}

	html_code_func html_url "$base.html" "$name"
	echo -n ' ('
	html_code_func html_url "$base.rst" 'rst'
	echo -n ' '
	html_code_func html_url "$base.raw.html" 'raw'
	echo ')'
	if [ -s "$package_docs_refdir/$base.deps.dot" ]; then
		echo -n ' ('
		html_code_func html_url "$base.deps.pdf" 'pdf'
		echo -n ' '
		html_code_func html_url "$base.deps.svg" 'svg'
		echo -n ' '
		html_code_func html_url "$base.deps.dot" 'dot'
		echo ')'
	fi
}

######
# Symbol index

# TODO: implement symbol index, giving a <file:line> pair for each appearance
#	html_p "This page provide links to the programming interfaces and
#		commands provided by the <code>$PKG</code> package."