Mercurial > p > roundup > code

annotate doc/Makefile @ 8459:db435e272f26

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
fix: update updating.txt doc for user_src_input bug I originally thought it was not worth documenting because the error case had no impact. But deployed copies of the trackers can be updated to reduce differences between deployed and distributed files.
author John Rouillard <rouilj@ieee.org>
date Fri, 26 Sep 2025 16:08:30 -0400
parents c3bf229d3d4b
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
8271
8824c81cc431 doc: add make help to all Makefiles and fix 2 Makefiles
John Rouillard <rouilj@ieee.org>
parents: 8116
diff changeset
1 ##@ Default target
8824c81cc431 doc: add make help to all Makefiles and fix 2 Makefiles
John Rouillard <rouilj@ieee.org>
parents: 8116
diff changeset
2 all: man_html tracker_config.txt admin_help.html ## make all docs under share
7920
6aa0525187cd doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
diff changeset
3 cd ..; ./setup.py build_doc
6aa0525187cd doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
diff changeset
4
8271
8824c81cc431 doc: add make help to all Makefiles and fix 2 Makefiles
John Rouillard <rouilj@ieee.org>
parents: 8116
diff changeset
5 ##@ build doc parts
8274
c3bf229d3d4b doc: update tracker_config.txt
John Rouillard <rouilj@ieee.org>
parents: 8271
diff changeset
6 tracker_config.txt: ../roundup/configuration.py format_config.awk ## generate a current config file
8271
8824c81cc431 doc: add make help to all Makefiles and fix 2 Makefiles
John Rouillard <rouilj@ieee.org>
parents: 8116
diff changeset
7
7920
6aa0525187cd doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
diff changeset
8 python3 ../roundup/scripts/roundup_admin.py \
6aa0525187cd doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
diff changeset
9 genconfig _temp_config.txt
6aa0525187cd doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
diff changeset
10
8036
8b5f8b950f58 docs: add section anchors to config.ini in references.txt; change format
John Rouillard <rouilj@ieee.org>
parents: 7920
diff changeset
11 awk -f format_config.awk _temp_config.txt | \
8b5f8b950f58 docs: add section anchors to config.ini in references.txt; change format
John Rouillard <rouilj@ieee.org>
parents: 7920
diff changeset
12 cat -s > tracker_config.txt
7920
6aa0525187cd doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
diff changeset
13 rm -f _temp_config.txt
6aa0525187cd doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
diff changeset
14
6aa0525187cd doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
diff changeset
15 ## generate html versions of man pages for inclusion in documentation
6aa0525187cd doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
diff changeset
16 # find all man pages and generate output file paths.
6aa0525187cd doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
diff changeset
17 MAN_ROFF=$(wildcard ../share/man/man1/*.1)
6aa0525187cd doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
diff changeset
18 MAN_HTML=$(patsubst ../share/man/man1/%.1,html_extra/man_pages/%.1.html,$(MAN_ROFF))
6aa0525187cd doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
diff changeset
19
8271
8824c81cc431 doc: add make help to all Makefiles and fix 2 Makefiles
John Rouillard <rouilj@ieee.org>
parents: 8116
diff changeset
20 man_html: $(MAN_HTML) ## generate html versions of man pages for docs
7920
6aa0525187cd doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
diff changeset
21
6aa0525187cd doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
diff changeset
22 html_extra/man_pages/%.1.html: ../share/man/man1/%.1
6aa0525187cd doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
diff changeset
23 man --html=cat $< > $@
8075
08fcbdfe670b docs: set max width for man page paragraphs to 65ch
John Rouillard <rouilj@ieee.org>
parents: 8036
diff changeset
24 # set max width for paragraphs
08fcbdfe670b docs: set max width for man page paragraphs to 65ch
John Rouillard <rouilj@ieee.org>
parents: 8036
diff changeset
25 sed -i '/<style/,/<\/style/s/\(p\s* { \)margin/\1max-width: 65ch; margin/' $@
8116
d4fbfc6a7662 docs: add canonical link for all generated man pages
John Rouillard <rouilj@ieee.org>
parents: 8096
diff changeset
26 # add link rel=cannonical $@(F) takes
d4fbfc6a7662 docs: add canonical link for all generated man pages
John Rouillard <rouilj@ieee.org>
parents: 8096
diff changeset
27 # target $@ (html_extra/man_pages/x.1.html)
d4fbfc6a7662 docs: add canonical link for all generated man pages
John Rouillard <rouilj@ieee.org>
parents: 8096
diff changeset
28 # and returns file part (x.1.html)
d4fbfc6a7662 docs: add canonical link for all generated man pages
John Rouillard <rouilj@ieee.org>
parents: 8096
diff changeset
29 sed -i '/<head>/,/<\/head>/s#^<style#<link rel="canonical" href="https://www.roundup-tracker.org/docs/man_pages/$(@F)">\n<style#' $@
7920
6aa0525187cd doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
diff changeset
30 #man2html $< > $@
6aa0525187cd doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
diff changeset
31
8271
8824c81cc431 doc: add make help to all Makefiles and fix 2 Makefiles
John Rouillard <rouilj@ieee.org>
parents: 8116
diff changeset
32 admin_help.html: ../roundup/admin.py ## generate html version of roundup-admin help (WIP)
8824c81cc431 doc: add make help to all Makefiles and fix 2 Makefiles
John Rouillard <rouilj@ieee.org>
parents: 8116
diff changeset
33 python3 ../roundup/scripts/roundup_admin.py htmlhelp > admin_help.html
8096
ea1f377c87d6 docs: add roundup-admin interactive help output to admin_guide.txt
John Rouillard <rouilj@ieee.org>
parents: 8075
diff changeset
34
8271
8824c81cc431 doc: add make help to all Makefiles and fix 2 Makefiles
John Rouillard <rouilj@ieee.org>
parents: 8116
diff changeset
35 ##@ Utilties
8824c81cc431 doc: add make help to all Makefiles and fix 2 Makefiles
John Rouillard <rouilj@ieee.org>
parents: 8116
diff changeset
36
8824c81cc431 doc: add make help to all Makefiles and fix 2 Makefiles
John Rouillard <rouilj@ieee.org>
parents: 8116
diff changeset
37 clean: ## clean all generated docs
7920
6aa0525187cd doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
diff changeset
38 rm -f _temp_config.txt tracker_config.txt \
8096
ea1f377c87d6 docs: add roundup-admin interactive help output to admin_guide.txt
John Rouillard <rouilj@ieee.org>
parents: 8075
diff changeset
39 html_extra/man_pages/*.1.html \
ea1f377c87d6 docs: add roundup-admin interactive help output to admin_guide.txt
John Rouillard <rouilj@ieee.org>
parents: 8075
diff changeset
40 admin_help.py
8271
8824c81cc431 doc: add make help to all Makefiles and fix 2 Makefiles
John Rouillard <rouilj@ieee.org>
parents: 8116
diff changeset
41
8824c81cc431 doc: add make help to all Makefiles and fix 2 Makefiles
John Rouillard <rouilj@ieee.org>
parents: 8116
diff changeset
42 # from https://www.thapaliya.com/en/writings/well-documented-makefiles/ via
8824c81cc431 doc: add make help to all Makefiles and fix 2 Makefiles
John Rouillard <rouilj@ieee.org>
parents: 8116
diff changeset
43 # https://til.jakelazaroff.com/make/list-all-commands-in-a-makefile/
8824c81cc431 doc: add make help to all Makefiles and fix 2 Makefiles
John Rouillard <rouilj@ieee.org>
parents: 8116
diff changeset
44 help: ## this output
8824c81cc431 doc: add make help to all Makefiles and fix 2 Makefiles
John Rouillard <rouilj@ieee.org>
parents: 8116
diff changeset
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)
Roundup Issue Tracker: http://roundup-tracker.org/