Mercurial > p > roundup > code

comparison website/www/Makefile @ 8271:8824c81cc431

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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 d6b447de4f59
children f5007c91ba18
comparison
equal deleted inserted replaced
8270:c70ffbc2a003 8271:8824c81cc431
1 TMP := _tmp 1 TMP := _tmp
2 HTML := html 2 HTML := html
3 3
4 .PHONY: help clean html linkcheck 4 .PHONY: help clean html linkcheck
5 5
6 # from https://www.thapaliya.com/en/writings/well-documented-makefiles/ via
7 # https://til.jakelazaroff.com/make/list-all-commands-in-a-makefile/
6 help: 8 help:
7 @echo "Please use \`make <target>' where <target> is one of" 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)
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 10
20 docs: 11 ##@ Main Command
21 ln -s ../../doc ./docs
22 ln -s ../../COPYING.txt
23
24 # after upgrade to sphinx 1.8.5, search.html is missing load of searchtools. 12 # after upgrade to sphinx 1.8.5, search.html is missing load of searchtools.
25 # fix that in postprocess 13 # fix that in postprocess
26 # also sed index.html to properly format meta og:... entries. 14 # also sed index.html to properly format meta og:... entries.
27 html: docs 15 html: doc_links ## make standalone HTML files
28 rm -rf html 16 rm -rf html
29 mkdir -p $(TMP)/doctrees $(HTML) 17 mkdir -p $(TMP)/doctrees $(HTML)
30 sphinx-build -n -W -b html -d $(TMP)/doctrees . $(HTML) 18 sphinx-build -n -W -b html -d $(TMP)/doctrees . $(HTML)
31 # install searchtools.js into search page. 19 # install searchtools.js into search page.
32 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 20 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 21 # sphinx inserts \: for : in meta tags. Get rid of the \ in
34 # opengraph tags 22 # opengraph tags
35 sed -i -e '/<meta/s/og\\:/og:/' \ 23 sed -i -e '/<meta/s/og\\:/og:/' \
36 -e '/<meta/s/name="og:/property="og:/' html/index.html 24 -e '/<meta/s/name="og:/property="og:/' html/index.html
37 cp robots.txt html/robots.txt 25 cp robots.txt html/robots.txt
38 mkdir html/signatures && cp signatures/*.asc html/signatures 26 mkdir html/signatures && cp signatures/*.asc html/signatures
39 cp --no-clobber -r docs/html_extra/. html/docs/. 27 cp --no-clobber -r docs/html_extra/. html/docs/.
42 l=$$(find html -name '*.orig' -o -name '*~' | tee /dev/tty | wc -l);\ 30 l=$$(find html -name '*.orig' -o -name '*~' | tee /dev/tty | wc -l);\
43 if [ $$l -ne 0 ]; then echo "Garbage files found" && false; fi 31 if [ $$l -ne 0 ]; then echo "Garbage files found" && false; fi
44 if [ -e templates.zip ]; then cp templates.zip \ 32 if [ -e templates.zip ]; then cp templates.zip \
45 html/CVE-2024-39124-templates.zip; fi 33 html/CVE-2024-39124-templates.zip; fi
46 34
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
48 mkdir -p $(TMP)/linkcheck $(TMP)/doctrees 40 mkdir -p $(TMP)/linkcheck $(TMP)/doctrees
49 sphinx-build -b linkcheck -d $(TMP)/doctrees . $(TMP)/linkcheck 41 sphinx-build -b linkcheck -d $(TMP)/doctrees . $(TMP)/linkcheck
50 @echo 42 @echo
51 @echo "Link check complete; look for any errors in the above output " \ 43 @echo "Link check complete; look for any errors in the above output " \
52 "or in .build/linkcheck/output.txt." 44 "or in .build/linkcheck/output.txt."
53 45
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
55 rm -f templates.zip 49 rm -f templates.zip
56 (cd ../../share/roundup; hg status -A templates | \ 50 (cd ../../share/roundup; hg status -A templates | \
57 sed -ne '/^[AMC]/s/^..//p' | sort | zip -@ - ) > templates.zip 51 sed -ne '/^[AMC]/s/^..//p' | sort | zip -@ - ) > templates.zip
58 52
59 sourceforge_dev_sync: 53 ##@ Sync/Distribution commands
54 sourceforge_dev_sync: ## sync html directory to sourceforce /dev_docs subdir
60 # --no-times makes _images/* and other files sync over every time 55 # --no-times makes _images/* and other files sync over every time
61 # so docs_backup-... is complete with all files and can be served 56 # so docs_backup-... is complete with all files and can be served
62 # as the docs tree. Without --no-times _static, _images and other 57 # as the docs tree. Without --no-times _static, _images and other
63 # directories are missing from the backup directory. 58 # directories are missing from the backup directory.
64 # Exclude docs_backup so it won't be deleted from sourceforge 59 # Exclude docs_backup so it won't be deleted from sourceforge
65 # since: 60 # since:
66 # --delete-exclude 61 # --delete-exclude
67 # IS NOT (and must not be) SET 62 # IS NOT (and must not be) SET
68 read -p "sync to dev_docs y/N? " resp; echo "$$resp" | grep -i "^y" 63 read -p "sync to dev_docs y/N? " resp; echo "$$resp" | grep -i "^y"
69 rsync -av --no-times --delete --exclude 'docs_backup*' \ 64 rsync -av --no-times --delete --exclude 'docs_backup*' \
70 --backup --backup-dir docs_backup-`date --iso-8601=seconds` \ 65 --backup --backup-dir docs_backup-`date --iso-8601=seconds` \
71 html/. \ 66 html/. \
72 web.sourceforge.net:/home/project-web/roundup/htdocs/dev_docs/. 67 web.sourceforge.net:/home/project-web/roundup/htdocs/dev_docs/.
73 68
74 sourceforge_prod_sync: 69 sourceforge_prod_sync: ## sync html directory to sourceforce production website
75 read -p "sync to production y/N? " resp; echo "$$resp" | grep -i "^y" 70 read -p "sync to production y/N? " resp; echo "$$resp" | grep -i "^y"
76 rsync -av --no-times --delete --exclude 'docs_backup*' \ 71 rsync -av --no-times --delete --exclude 'docs_backup*' \
77 --backup --backup-dir docs_backup-`date --iso-8601=seconds` \ 72 --backup --backup-dir docs_backup-`date --iso-8601=seconds` \
78 html/. \ 73 html/. \
79 web.sourceforge.net:/home/project-web/roundup/htdocs/. 74 web.sourceforge.net:/home/project-web/roundup/htdocs/.
80 75
81 sourceforge_home_sync: 76 sourceforge_home_sync: ## sync html directory to sourceforge:~/roundup_docs
77
82 read -p "sync to home y/N? " resp; echo "$$resp" | grep -i "^y" 78 read -p "sync to home y/N? " resp; echo "$$resp" | grep -i "^y"
83 rsync -av --no-times --delete --exclude 'docs_backup*' \ 79 rsync -av --no-times --delete --exclude 'docs_backup*' \
84 --backup --backup-dir docs_backup-`date --iso-8601=seconds` \ 80 --backup --backup-dir docs_backup-`date --iso-8601=seconds` \
85 html/. \ 81 html/. \
86 web.sourceforge.net:roundup_docs/. 82 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
Roundup Issue Tracker: http://roundup-tracker.org/