Mercurial > p > roundup > code
comparison 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 |
comparison
equal
deleted
inserted
replaced
| 8270:c70ffbc2a003 | 8271:8824c81cc431 |
|---|---|
| 1 all: man_html tracker_config.txt admin_help.html | 1 ##@ Default target |
| 2 all: man_html tracker_config.txt admin_help.html ## make all docs under share | |
| 2 cd ..; ./setup.py build_doc | 3 cd ..; ./setup.py build_doc |
| 3 | 4 |
| 4 tracker_config.txt: ../roundup/configuration.py | 5 ##@ build doc parts |
| 5 # generate a current config file | 6 tracker_config.txt: ../roundup/configuration.py ## generate a current config file |
| 7 | |
| 6 python3 ../roundup/scripts/roundup_admin.py \ | 8 python3 ../roundup/scripts/roundup_admin.py \ |
| 7 genconfig _temp_config.txt | 9 genconfig _temp_config.txt |
| 8 | 10 |
| 9 awk -f format_config.awk _temp_config.txt | \ | 11 awk -f format_config.awk _temp_config.txt | \ |
| 10 cat -s > tracker_config.txt | 12 cat -s > tracker_config.txt |
| 13 ## generate html versions of man pages for inclusion in documentation | 15 ## generate html versions of man pages for inclusion in documentation |
| 14 # find all man pages and generate output file paths. | 16 # find all man pages and generate output file paths. |
| 15 MAN_ROFF=$(wildcard ../share/man/man1/*.1) | 17 MAN_ROFF=$(wildcard ../share/man/man1/*.1) |
| 16 MAN_HTML=$(patsubst ../share/man/man1/%.1,html_extra/man_pages/%.1.html,$(MAN_ROFF)) | 18 MAN_HTML=$(patsubst ../share/man/man1/%.1,html_extra/man_pages/%.1.html,$(MAN_ROFF)) |
| 17 | 19 |
| 18 man_html: $(MAN_HTML) | 20 man_html: $(MAN_HTML) ## generate html versions of man pages for docs |
| 19 | 21 |
| 20 html_extra/man_pages/%.1.html: ../share/man/man1/%.1 | 22 html_extra/man_pages/%.1.html: ../share/man/man1/%.1 |
| 21 man --html=cat $< > $@ | 23 man --html=cat $< > $@ |
| 22 # set max width for paragraphs | 24 # set max width for paragraphs |
| 23 sed -i '/<style/,/<\/style/s/\(p\s* { \)margin/\1max-width: 65ch; margin/' $@ | 25 sed -i '/<style/,/<\/style/s/\(p\s* { \)margin/\1max-width: 65ch; margin/' $@ |
| 25 # target $@ (html_extra/man_pages/x.1.html) | 27 # target $@ (html_extra/man_pages/x.1.html) |
| 26 # and returns file part (x.1.html) | 28 # and returns file part (x.1.html) |
| 27 sed -i '/<head>/,/<\/head>/s#^<style#<link rel="canonical" href="https://www.roundup-tracker.org/docs/man_pages/$(@F)">\n<style#' $@ | 29 sed -i '/<head>/,/<\/head>/s#^<style#<link rel="canonical" href="https://www.roundup-tracker.org/docs/man_pages/$(@F)">\n<style#' $@ |
| 28 #man2html $< > $@ | 30 #man2html $< > $@ |
| 29 | 31 |
| 30 admin_help.html: ../roundup/admin.py | 32 admin_help.html: ../roundup/admin.py ## generate html version of roundup-admin help (WIP) |
| 31 python3 ../roundup/scripts/roundup_admin.py htmlhelp > admin_help.py | 33 python3 ../roundup/scripts/roundup_admin.py htmlhelp > admin_help.html |
| 32 | 34 |
| 33 clean: | 35 ##@ Utilties |
| 36 | |
| 37 clean: ## clean all generated docs | |
| 34 rm -f _temp_config.txt tracker_config.txt \ | 38 rm -f _temp_config.txt tracker_config.txt \ |
| 35 html_extra/man_pages/*.1.html \ | 39 html_extra/man_pages/*.1.html \ |
| 36 admin_help.py | 40 admin_help.py |
| 41 | |
| 42 # from https://www.thapaliya.com/en/writings/well-documented-makefiles/ via | |
| 43 # https://til.jakelazaroff.com/make/list-all-commands-in-a-makefile/ | |
| 44 help: ## this output | |
| 45 @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) |