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 different scenarios. This approach helps you keep your project organized by centralizing the commands needed 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 support 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 component references in your specification. You can then reference this JSON file in a page to render a REST API documentation page.

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

Build offline docs #

If you support 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’s tarred and zipped for easy distribution.

Your developer colleagues can add this make target to their build process to ensure that they deliver the documentation 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 $@ 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)

Object Model Layout

Article Summarization