Makefile

Makefiles are a great way to automate repetitive tasks. This theme comes with a Makefile that has a few commands to help you build documentation or reference assets for various scenarios. It is a great way to keep your project organized and to help you remember the commands you need to run to build your project — especially if you begin to rely on scripts to generate parts of your documentation.

How it Works #

To execute a make command, you need to open a terminal and navigate to the root of your project. From there, you can run the following commands:

make <command>

Use Cases #

Generate REST API Docs #

If you are supporting a project that has a REST API documented using an OpenAPI 3.0 specification, you can use the Makefile to generate documentation native to this theme.

To generate the REST API documentation, you can run the following commands:

make api-gen <INPUT.YAML> <OUTPUT.JSON>: This command generates the REST API documentation

This command runs your OpenAPI 3.0 specification through the tools/spec-preprocessor.py script to generate a JSON file that resolves all of the component references in your specification. This JSON file can then be referenced in a page to be rendered as a REST API documentation page.

---
title: Example API (TESTING)
layout: api
reference: "<NAME_OF_FILE>" # /data
---

Build Offline Docs #

If you are supporting a project that customers may need to access offline in an air-gapped environment, you can build your documentation into a file:// protocol-compatible format that is tarred and zipped for easy distribution.

Your developer colleagues can utilize this make target by adding it into their build process to ensure that the documentation is delivered with the product.

To build the offline documentation, you can run the following commands:

make offline: This command builds the offline documentation as a .tar.gz file
make offline-drafts: This command builds the offline documentation with drafts as a .tar.gz file

Source Code #

# Makefile to start the Hugo server with specific product versions

%: 
	@echo "Starting Hugo server for HPE $@ Docs"
	hugo server --environment $@

# Default action if no product is specified
docs all:
	@echo "Starting Hugo server for all docs"
	@hugo server

# Target for generating the OpenAPI spec for the API reference

api-gen:
	python tools/spec-preprocessor.py $(INPUT) $(OUTPUT)

api-gen-test:
	python tools/spec-preprocessor.py data/basicApi.yaml data/basicApi-output.json 

# Target for building the site for offline use with drafts
offline-drafts:
	@echo "Building Hugo site for offline use with drafts"
	@hugo -D --environment development --config config/hugo-offline.yaml --minify
	@tar -czvf offline-docs.tar.gz ./public
	@echo "Site packaged into offline-docs.tar.gz (including drafts)"

# Target for building the site for offline use without drafts

offline:
	@echo "Building Hugo site for offline use"
	@hugo --environment development --config config/hugo-offline.yaml --minify
	@tar -czvf offline-docs.tar.gz ./public
	@echo "Site packaged into offline-docs.tar.gz"

# Target for updating the release frontmatter for a given product vdir; also updates the supported release table csv
## # Usage: make update-frontmatter P=<product_name> VDIR=<version_dir> V=<new_version_number>
v-bump:
	@python tools/update-prod-release-frontmatter.py $(P) $(VDIR) $(V)
	@python tools/update-supported-release-table.py $(P) $(V)

Article Summarization