Skip to content

docs(makefile): add autodocumenting to makefile #239

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Feb 12, 2022
Merged

docs(makefile): add autodocumenting to makefile #239

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/ci.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion .github/workflows/deploy-gh-page.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
42 changes: 32 additions & 10 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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)

Expand All @@ -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
Expand Down Expand Up @@ -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)
2 changes: 1 addition & 1 deletion README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -132,7 +132,7 @@ the PSF for inclusion in the documentation.

3. 存檔以後，執行以下列指令編譯輸出文件，以確保你的修改沒有 rST 的語法錯誤或警告 ::

make
make all

如果你還沒有執行 `維護、預覽`_ 的 clone CPython 的動作，此指令會自動幫你 clone CPython，\
並且會使用 Sphinx 幫你檢查 rST 語法錯誤，我們盡量保持沒有 warning \
Expand Down