Mercurial > p > roundup > code
diff doc/Makefile @ 8271:8824c81cc431
doc: add make help to all Makefiles and fix 2 Makefiles
Use automatic help generator for help target that extracts help text
from makefile comments.
Reordered a number of targets to use grouping mechanism in help
generator.
A couple of multiple target rules had to be split because:
target1 target2: ... ## help comment
doesn't work with the help generator.
In locale Makefile, the TEMPLATES variable was not set so changes to
the html files in the templates would not trigger regeneration of the
roundup.pot template.
In doc Makefile, made admin_help.html generate the file rather than
putting it into admin_help.py. Verified that the file shows up at end
of admin_guide.html.
In www makefile, fixed docs link generation.
| author | John Rouillard <rouilj@ieee.org> |
|---|---|
| date | Sun, 12 Jan 2025 18:22:40 -0500 |
| parents | d4fbfc6a7662 |
| children | c3bf229d3d4b |
line wrap: on
line diff
--- a/doc/Makefile Sun Jan 12 14:14:09 2025 -0500 +++ b/doc/Makefile Sun Jan 12 18:22:40 2025 -0500 @@ -1,8 +1,10 @@ -all: man_html tracker_config.txt admin_help.html +##@ Default target +all: man_html tracker_config.txt admin_help.html ## make all docs under share cd ..; ./setup.py build_doc -tracker_config.txt: ../roundup/configuration.py - # generate a current config file +##@ build doc parts +tracker_config.txt: ../roundup/configuration.py ## generate a current config file + python3 ../roundup/scripts/roundup_admin.py \ genconfig _temp_config.txt @@ -15,7 +17,7 @@ MAN_ROFF=$(wildcard ../share/man/man1/*.1) MAN_HTML=$(patsubst ../share/man/man1/%.1,html_extra/man_pages/%.1.html,$(MAN_ROFF)) -man_html: $(MAN_HTML) +man_html: $(MAN_HTML) ## generate html versions of man pages for docs html_extra/man_pages/%.1.html: ../share/man/man1/%.1 man --html=cat $< > $@ @@ -27,10 +29,17 @@ sed -i '/<head>/,/<\/head>/s#^<style#<link rel="canonical" href="https://www.roundup-tracker.org/docs/man_pages/$(@F)">\n<style#' $@ #man2html $< > $@ -admin_help.html: ../roundup/admin.py - python3 ../roundup/scripts/roundup_admin.py htmlhelp > admin_help.py +admin_help.html: ../roundup/admin.py ## generate html version of roundup-admin help (WIP) + python3 ../roundup/scripts/roundup_admin.py htmlhelp > admin_help.html -clean: +##@ Utilties + +clean: ## clean all generated docs rm -f _temp_config.txt tracker_config.txt \ html_extra/man_pages/*.1.html \ admin_help.py + +# from https://www.thapaliya.com/en/writings/well-documented-makefiles/ via +# https://til.jakelazaroff.com/make/list-all-commands-in-a-makefile/ +help: ## this output + @awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n make \033[36m<target>\033[0m\n"} /^[.a-zA-Z_-]+:.*?##/ { printf " \033[36m%-15s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)