Як створити файл самодокументування

Мій новий улюблений спосіб повністю використати Makefile? Створення персоналізованих псевдонімів команд робочого циклу для кожного сховища проектів, які ви можете зареєструвати.

Чи може Makefile покращити ваші DevOps і зробити розробників щасливими? Як би було приголомшливо, якби новий розробник, що працює над вашим проектом, не розпочав копіювання та вставку команд з вашого README? Що робити, якщо замість:

pip3 install pipenv pipenv shell --python 3.8 pipenv install --dev npm install pre-commit install --install-hooks # look up how to install Framework X... # copy and paste from README... npm run serve

... ви можете просто набрати:

make start

... а потім почати працювати?

Внесення змін

Я використовую makeкожен день, щоб вивести з роботи загальні розробки, такі як оновлення програм, встановлення залежностей та тестування.

Щоб зробити все це за допомогою Makefile (GNU make), ми використовуємо правила та рецепти Makefile. Подібні паралелі існують і при виготовленні смаку POSIX, як цільові правила. Ось чудова стаття про файли Makefi, сумісні з POSIX.

Ось кілька прикладів речей, які ми можемо makeспростити (вибачте):

update: ## Do apt upgrade and autoremove sudo apt update && sudo apt upgrade -y sudo apt autoremove -y env: pip3 install pipenv pipenv shell --python 3.8 install: ## Install or update dependencies pipenv install --dev npm install pre-commit install --install-hooks serve: ## Run the local development server hugo serve --enableGitInfo --disableFastRender --environment development initial: update env install serve ## Install tools and start development server 

Тепер у нас є кілька псевдонімів командного рядка, які ви можете перевірити. Чудова ідея! Якщо вам цікаво, що з цим дивним ##синтаксисом коментарів, він стає кращим.

Самодокументуючий Makefile

Псевдоніми - це чудово, якщо ви пам’ятаєте, які вони всі і чим займаються, не постійно друкуючи cat Makefile. Звичайно, вам потрібна helpкоманда:

.PHONY: help help: ## Show this help @egrep -h '\s##\s' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}' 

За допомогою невеликої магії командного рядка ця egrepкоманда бере вихідні дані MAKEFILE_LIST, сортує їх і використовує awkдля пошуку рядків, які відповідають ##шаблону. Потім друкується корисна відформатована версія коментарів.

Ми розмістимо його у верхній частині файлу, щоб це було цільовим значенням за замовчуванням. Тепер, щоб побачити всі наші зручні ярлики та те, що вони роблять, ми просто запускаємо make, або make help:

help Show this help initial Install tools and start development server install Install or update dependencies serve Run the local development server update Do apt upgrade and autoremove 

Тепер у нас є власний персональний інструмент CLI для конкретного проекту!

Можливостей для вдосконалення потоку DevOps за допомогою самодокументування файлу Makefile майже безмежно. Ви можете використовувати його, щоб спростити будь-який робочий процес і створити дуже задоволених розробників.