docs(makefile): add autodocumenting to makefile (#239)

josix · web-flow · commit cdc256223c40 · 2022-02-13T01:32:52.000+08:00
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -18,4 +18,4 @@ jobs:
         run: sudo apt-get install gettext
 
       - name: Validate
-        run: VERSION=${{ github.event.pull_request.base.ref }} MODE=dummy make
+        run: VERSION=${{ github.event.pull_request.base.ref }} MODE=dummy make all
diff --git a/.github/workflows/deploy-gh-page.yml b/.github/workflows/deploy-gh-page.yml
@@ -15,7 +15,7 @@ jobs:
         run: sudo apt-get install gettext
 
       - name: Build
-        run: make
+        run: make all
 
       - name: Deploy to gh page
         uses: JamesIves/github-pages-deploy-action@3.7.1
diff --git a/Makefile b/Makefile
@@ -2,7 +2,7 @@
 #
 # Here is what you can do:
 #
-# - make  # Automatically build an html local version
+# - make all # Automatically build an html local version
 # - make todo  # To list remaining tasks
 # - make merge  # To merge pot from upstream
 # - make fuzzy  # To find fuzzy strings
@@ -15,6 +15,27 @@
 #
 # Credits: Python Documentation French Translation Team (https://github.com/python/python-docs-fr)
 
+.DEFAULT_GOAL := help # Sets default action to be help
+
+define PRINT_HELP_PYSCRIPT # start of Python section
+import re, sys
+
+output = []
+# Loop through the lines in this file
+for line in sys.stdin:
+    # if the line has a command and a comment start with
+    #   two pound signs, add it to the output
+    match = re.match(r'^([a-zA-Z_-]+):.*?## (.*)$$', line)
+    if match:
+        target, help = match.groups()
+        output.append("%-10s %s" % (target, help))
+# Sort the output in alphanumeric order
+output.sort()
+# Print the help result
+print('\n'.join(output))
+endef
+export PRINT_HELP_PYSCRIPT # End of python section
+
 CPYTHON_CLONE := ../cpython/
 SPHINX_CONF := $(CPYTHON_CLONE)/Doc/conf.py
 LANGUAGE := zh_TW
@@ -25,16 +46,17 @@ MODE := autobuild-dev-html
 BRANCH := $(or $(VERSION), $(shell git describe --contains --all HEAD))
 JOBS := 4
 
-
 .PHONY: all
-all: $(VENV)/bin/sphinx-build $(VENV)/bin/blurb clone
+all: $(VENV)/bin/sphinx-build $(VENV)/bin/blurb clone ## Automatically build an html local version
 	mkdir -p $(LC_MESSAGES)
 	for dirname in $$(find . -name '*.po' | xargs -n1 dirname | sort -u | grep -v '^\.$$'); do mkdir -p $(LC_MESSAGES)/$$dirname; done
 	for file in *.po */*.po; do ln -f $$file $(LC_MESSAGES)/$$file; done
 	. $(VENV)/bin/activate; $(MAKE) -C $(CPYTHON_CLONE)/Doc/ SPHINXOPTS='-j$(JOBS) -D locale_dirs=locales -D language=$(LANGUAGE) -D gettext_compact=0' $(MODE)
 
+help:
+	@python3 -c "$$PRINT_HELP_PYSCRIPT" < $(MAKEFILE_LIST)
 
-clone:
+clone: ## Clone latest cpython repository to `../cpython/` if it doesn't exist
 	git clone --depth 1 --no-single-branch https://github.com/python/cpython.git $(CPYTHON_CLONE)  || echo "cpython exists"
 	cd $(CPYTHON_CLONE) && git checkout $(BRANCH)
 
@@ -53,24 +75,24 @@ $(VENV)/bin/blurb: $(VENV)/bin/activate
 
 
 .PHONY: upgrade_venv
-upgrade_venv: $(VENV)/bin/activate
+upgrade_venv: $(VENV)/bin/activate ## Upgrade the venv that compiles the doc
 	. $(VENV)/bin/activate; python3 -m pip install --upgrade sphinx python-docs-theme blurb
 
 
 .PHONY: progress
-progress:
+progress: ## Compute current progression
 	@python3 -c 'import sys; print("{:.1%}".format(int(sys.argv[1]) / int(sys.argv[2])))'  \
 	$(shell msgcat *.po */*.po | msgattrib --translated | grep -c '^msgid') \
 	$(shell msgcat *.po */*.po | grep -c '^msgid')
 
 
 .PHONY: todo
-todo:
+todo: ## List remaining tasks
 	for file in *.po */*.po; do echo $$(msgattrib --untranslated $$file | grep ^msgid | sed 1d | wc -l ) $$file; done | grep -v ^0 | sort -gr
 
 
 .PHONY: merge
-merge: upgrade_venv
+merge: upgrade_venv ## To merge pot from upstream
 ifneq "$(shell cd $(CPYTHON_CLONE) 2>/dev/null && git describe --contains --all HEAD)" "$(BRANCH)"
 	$(error "You're merging from a different branch")
 endif
@@ -102,9 +124,9 @@ update_txconfig:
 
 
 .PHONY: fuzzy
-fuzzy:
+fuzzy: ## Find fuzzy strings
 	for file in *.po */*.po; do echo $$(msgattrib --only-fuzzy --no-obsolete "$$file" | grep -c '#, fuzzy') $$file; done | grep -v ^0 | sort -gr
 
 .PHONY: rm_cpython
-rm_cpython:
+rm_cpython: ## Remove cloned cpython repo
 	rm -rf $(CPYTHON_CLONE)
diff --git a/README.rst b/README.rst
@@ -132,7 +132,7 @@ the PSF for inclusion in the documentation.
 
 3. 存檔以後，執行以下列指令編譯輸出文件，以確保你的修改沒有 rST 的語法錯誤或警告 ::
 
-    make
+    make all
 
    如果你還沒有執行 `維護、預覽`_ 的 clone CPython 的動作，此指令會自動幫你 clone CPython，\
    並且會使用 Sphinx 幫你檢查 rST 語法錯誤，我們盡量保持沒有 warning \
