Skip to content

Commit 47f7c4e

Browse files
rouiljrouilj
committed
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.
1 parent 98dbe9f commit 47f7c4e

File tree

3 files changed

+100
-81
lines changed

3 files changed

+100
-81
lines changed

‎doc/Makefile‎

Lines changed: 16 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
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
23
cd ..; ./setup.py build_doc
34

4-
tracker_config.txt: ../roundup/configuration.py
5-
# generate a current config file
5+
##@ build doc parts
6+
tracker_config.txt: ../roundup/configuration.py ## generate a current config file
7+
68
python3 ../roundup/scripts/roundup_admin.py \
79
genconfig _temp_config.txt
810

@@ -15,7 +17,7 @@ tracker_config.txt: ../roundup/configuration.py
1517
MAN_ROFF=$(wildcard ../share/man/man1/*.1)
1618
MAN_HTML=$(patsubst ../share/man/man1/%.1,html_extra/man_pages/%.1.html,$(MAN_ROFF))
1719

18-
man_html: $(MAN_HTML)
20+
man_html: $(MAN_HTML) ## generate html versions of man pages for docs
1921

2022
html_extra/man_pages/%.1.html: ../share/man/man1/%.1
2123
man --html=cat $< > $@
@@ -27,10 +29,17 @@ html_extra/man_pages/%.1.html: ../share/man/man1/%.1
2729
sed -i '/<head>/,/<\/head>/s#^<style#<link rel="canonical" href="https://www.roundup-tracker.org/docs/man_pages/$(@F)">\n<style#' $@
2830
#man2html $< > $@
2931

30-
admin_help.html: ../roundup/admin.py
31-
python3 ../roundup/scripts/roundup_admin.py htmlhelp > admin_help.py
32+
admin_help.html: ../roundup/admin.py ## generate html version of roundup-admin help (WIP)
33+
python3 ../roundup/scripts/roundup_admin.py htmlhelp > admin_help.html
34+
35+
##@ Utilties
3236

33-
clean:
37+
clean: ## clean all generated docs
3438
rm -f _temp_config.txt tracker_config.txt \
3539
html_extra/man_pages/*.1.html \
3640
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)

‎locale/Makefile‎

Lines changed: 52 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -13,56 +13,69 @@ TEMPLATE=roundup.pot
1313
PACKAGES=$(shell find ../roundup ../share/roundup/templates -name '*.py' \
1414
| sed -e 's,/[^/]*$$,,' | sort | uniq)
1515
SOURCES=$(PACKAGES:=/*.py)
16+
TEMPLATES=$(wildcard ../share/roundup/templates/*/html/*.html)
1617
PO_FILES=$(wildcard *.po)
1718
MO_FILES=$(PO_FILES:.po=.mo)
1819
RUN_PYTHON=PYTHONPATH=.. $(PYTHON) -O
1920

20-
all: dist
21-
22-
help:
23-
@echo "$(MAKE) - build MO files. Run this before sdist"
24-
@echo "$(MAKE) dist - same as above"
25-
@echo "$(MAKE) template - update message template from sources"
26-
@echo "$(MAKE) merge - merge template into *.po files"
27-
@echo "$(MAKE) diff - see template differences in vi"
28-
@echo "$(MAKE) potest - check .po files for errors"
29-
@echo "$(MAKE) pytest - create locale files to run pytest"
30-
@echo "$(MAKE) locale.po - update message file from template"
31-
@echo "$(MAKE) locale.mo - compile individual message file"
32-
@echo "$(MAKE) help - this text"
33-
@echo ""
34-
@echo "Running make dist is the same as: make template merge dist"
21+
##@ default target
22+
all: dist ## build MO files. Run this before sdist"
3523

3624
# This will rebuild all MO files without updating their corresponding PO
3725
# files first. Run before creating Roundup distribution (hence the name).
3826
# PO files should be updated by their translators only, automatic update
3927
# adds unwanted fuzzy labels.
40-
dist: $(MO_FILES)
28+
dist: $(MO_FILES) ## same as all target
4129

42-
template: roundup.pot
30+
##@ Update files
31+
template: roundup.pot ## extract messages from source into template
4332

44-
pytest local_install:
45-
for file in $(PO_FILES); do \
46-
${MSGFMT} -o `basename $$file .po`.mo $$file; \
47-
done
48-
for file in $(MO_FILES); do \
49-
lang=`basename $$file .mo`; \
50-
mkdir -p locale/$$lang/LC_MESSAGES; \
51-
cp $$file locale/$$lang/LC_MESSAGES/roundup.mo; \
52-
done
33+
merge: $(PO_FILES) ## merge template updates into *.po files
34+
35+
# do the template file update
36+
roundup.pot: $(SOURCES) $(TEMPLATES)
37+
${XPOT} -n -o $(TEMPLATE) $(SOURCES) 2>&1 | sed -e "/: Unexpected in Python source: #64 \`@'/d"
38+
39+
${RUN_PYTHON} ../roundup/cgi/TAL/talgettext.py -u $(TEMPLATE) \
40+
../share/roundup/templates/classic/html/*.html \
41+
../share/roundup/templates/devel/html/*.html \
42+
../share/roundup/templates/minimal/html/*.html \
43+
../share/roundup/templates/responsive/html/*.html
44+
VERSION="`${RUN_PYTHON} -c 'from roundup import __version__; \
45+
print(__version__)';`"; \
46+
${XGETTEXT} -j -w 80 -F \
47+
--add-comments=".Hint " \
48+
--package-name=Roundup \
49+
--package-version=$$VERSION \
50+
[email protected] \
51+
--copyright-holder="See Roundup README.txt" \
52+
-o $(TEMPLATE) $(SOURCES)
5353

54-
# helps to check template file before check in
55-
diff:
54+
## QA commands
55+
diff: ## see template file (roundup.pot) differences
5656
hg cat roundup.pot | diff -u -I '^\#: \.\./roundup.*$$' \
5757
-I '^#:\s*:[0-9]*.*$$' \
5858
- roundup.pot || exit 0
59-
merge: $(PO_FILES)
6059

61-
potest:
60+
potest: ## check .po files for errors
6261
sh -c 'for file in $(PO_FILES); do \
6362
${MSGFMT} -cv --statistics $$file; \
6463
done' 2>&1 | sort -k 2,2n
6564

65+
66+
##@ Testing
67+
pytest: local_install ## create locale files to run pytest
68+
local_install:
69+
for file in $(PO_FILES); do \
70+
${MSGFMT} -o `basename $$file .po`.mo $$file; \
71+
done
72+
for file in $(MO_FILES); do \
73+
lang=`basename $$file .mo`; \
74+
mkdir -p locale/$$lang/LC_MESSAGES; \
75+
cp $$file locale/$$lang/LC_MESSAGES/roundup.mo; \
76+
done
77+
78+
### template rules
6679
%.po: $(TEMPLATE)
6780
@echo "Rebuild $@"
6881
@${MSGMERGE} -U --suffix=.bak $@ $<
@@ -75,21 +88,13 @@ potest:
7588
%.mo: %.po
7689
${MSGFMT} -o $@ $<
7790

78-
roundup.pot: $(SOURCES) $(TEMPLATES)
79-
${XPOT} -n -o $(TEMPLATE) $(SOURCES) 2>&1 | sed -e "/: Unexpected in Python source: #64 \`@'/d"
80-
81-
${RUN_PYTHON} ../roundup/cgi/TAL/talgettext.py -u $(TEMPLATE) \
82-
../share/roundup/templates/classic/html/*.html \
83-
../share/roundup/templates/devel/html/*.html \
84-
../share/roundup/templates/minimal/html/*.html \
85-
../share/roundup/templates/responsive/html/*.html
86-
VERSION="`${RUN_PYTHON} -c 'from roundup import __version__; \
87-
print(__version__)';`"; \
88-
${XGETTEXT} -j -w 80 -F \
89-
--add-comments=".Hint " \
90-
--package-name=Roundup \
91-
--package-version=$$VERSION \
92-
[email protected] \
93-
--copyright-holder="See Roundup README.txt" \
94-
-o $(TEMPLATE) $(SOURCES)
91+
# from https://www.thapaliya.com/en/writings/well-documented-makefiles/ via
92+
# https://til.jakelazaroff.com/make/list-all-commands-in-a-makefile/
93+
help: ## this text
94+
@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)
9595

96+
@echo ""
97+
@printf " \033[36m%-15s\033[0m %s\n" "<locale>.po" "update message file from template"
98+
@printf " \033[36m%-15s\033[0m %s\n" "<locale>.mo" "compile individual message file"
99+
@echo ""
100+
@echo "Running 'make' is the same as: make template merge dist"

‎website/www/Makefile‎

Lines changed: 32 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -3,35 +3,23 @@ HTML := html
33

44
.PHONY: help clean html linkcheck
55

6+
# from https://www.thapaliya.com/en/writings/well-documented-makefiles/ via
7+
# https://til.jakelazaroff.com/make/list-all-commands-in-a-makefile/
68
help:
7-
@echo "Please use \`make <target>' where <target> is one of"
8-
@echo " html to make standalone HTML files"
9-
@echo " linkcheck to check all external links for integrity"
10-
@echo " sourceforge_prod_sync sync html directory to sourceforce"
11-
@echo " production website"
12-
@echo " sourceforge_dev_sync sync html directory to sourceforce"
13-
@echo " /dev_docs subdirectory"
14-
@echo " sourceforge_home_sync sync html directory to"
15-
@echo " sourceforge:~/roundup_docs"
16-
@echo " clean remove all produced files"
17-
clean:
18-
-rm -rf $(TMP) $(HTML) docs COPYING.txt templates.zip
19-
20-
docs:
21-
ln -s ../../doc ./docs
22-
ln -s ../../COPYING.txt
9+
@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)
2310

11+
##@ Main Command
2412
# after upgrade to sphinx 1.8.5, search.html is missing load of searchtools.
2513
# fix that in postprocess
2614
# also sed index.html to properly format meta og:... entries.
27-
html: docs
15+
html: doc_links ## make standalone HTML files
2816
rm -rf html
2917
mkdir -p $(TMP)/doctrees $(HTML)
3018
sphinx-build -n -W -b html -d $(TMP)/doctrees . $(HTML)
31-
# install searchtools.js into search page.
19+
# install searchtools.js into search page.
3220
grep 'searchtools.js' html/search.html || sed -i -e '/language_data.js/s#</script>#</script>\n <script type="text/javascript" src="_static/searchtools.js"></script>#' html/search.html
33-
# sphinx inserts \: for : in meta tags. Get rid of the \ in
34-
# opengraph tags
21+
# sphinx inserts \: for : in meta tags. Get rid of the \ in
22+
# opengraph tags
3523
sed -i -e '/<meta/s/og\\:/og:/' \
3624
-e '/<meta/s/name="og:/property="og:/' html/index.html
3725
cp robots.txt html/robots.txt
@@ -44,25 +32,32 @@ html: docs
4432
if [ -e templates.zip ]; then cp templates.zip \
4533
html/CVE-2024-39124-templates.zip; fi
4634

47-
linkcheck:
35+
##@ Utilities
36+
clean: ## remove all produced files
37+
-rm -rf $(TMP) $(HTML) docs COPYING.txt templates.zip
38+
39+
linkcheck: ## check external links for existence
4840
mkdir -p $(TMP)/linkcheck $(TMP)/doctrees
4941
sphinx-build -b linkcheck -d $(TMP)/doctrees . $(TMP)/linkcheck
5042
@echo
5143
@echo "Link check complete; look for any errors in the above output " \
5244
"or in .build/linkcheck/output.txt."
5345

54-
templates.zip:
46+
# use to distribute template changes (e.g. for security issues)
47+
# separate from releases
48+
templates.zip: ## package share/roundup/templates into zip file
5549
rm -f templates.zip
5650
(cd ../../share/roundup; hg status -A templates | \
5751
sed -ne '/^[AMC]/s/^..//p' | sort | zip -@ - ) > templates.zip
5852

59-
sourceforge_dev_sync:
53+
##@ Sync/Distribution commands
54+
sourceforge_dev_sync: ## sync html directory to sourceforce /dev_docs subdir
6055
# --no-times makes _images/* and other files sync over every time
6156
# so docs_backup-... is complete with all files and can be served
6257
# as the docs tree. Without --no-times _static, _images and other
6358
# directories are missing from the backup directory.
64-
# Exclude docs_backup so it won't be deleted from sourceforge
65-
# since:
59+
# Exclude docs_backup so it won't be deleted from sourceforge
60+
# since:
6661
# --delete-exclude
6762
# IS NOT (and must not be) SET
6863
read -p "sync to dev_docs y/N? " resp; echo "$$resp" | grep -i "^y"
@@ -71,16 +66,26 @@ sourceforge_dev_sync:
7166
html/. \
7267
web.sourceforge.net:/home/project-web/roundup/htdocs/dev_docs/.
7368

74-
sourceforge_prod_sync:
69+
sourceforge_prod_sync: ## sync html directory to sourceforce production website
7570
read -p "sync to production y/N? " resp; echo "$$resp" | grep -i "^y"
7671
rsync -av --no-times --delete --exclude 'docs_backup*' \
7772
--backup --backup-dir docs_backup-`date --iso-8601=seconds` \
7873
html/. \
7974
web.sourceforge.net:/home/project-web/roundup/htdocs/.
8075

81-
sourceforge_home_sync:
76+
sourceforge_home_sync: ## sync html directory to sourceforge:~/roundup_docs
77+
8278
read -p "sync to home y/N? " resp; echo "$$resp" | grep -i "^y"
8379
rsync -av --no-times --delete --exclude 'docs_backup*' \
8480
--backup --backup-dir docs_backup-`date --iso-8601=seconds` \
8581
html/. \
8682
web.sourceforge.net:roundup_docs/.
83+
84+
##@ Setup
85+
doc_links: docs COPYING.txt ## recreate links to docs not in this tree
86+
87+
docs:
88+
ln -s ../../doc ./docs
89+
90+
COPYING.txt:
91+
ln -s ../../COPYING.txt COPYING.txt

0 commit comments

Comments
 (0)