From 72945041202a996dc86a3020d7b980c366d394b1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gabryel=20N=C3=B3brega?= Date: Mon, 24 Mar 2025 19:00:34 +0000 Subject: [PATCH] feat(docs): update Makefile commands and enhance README with usage instructions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Gabryel Nóbrega --- Makefile | 19 ++++--- README.md | 10 +++- .../version-1.0.0/howtos/docusaurus.md | 2 +- .../version-1.0.X/howtos/docusaurus.md | 2 +- .../check_sidebars.py | 0 .../create_docusaurus_website.sh | 49 +++++++++++++------ 6 files changed, 59 insertions(+), 23 deletions(-) rename check_sidebars.py => scripts/check_sidebars.py (100%) mode change 100755 => 100644 rename {docusaurus => scripts}/create_docusaurus_website.sh (52%) mode change 100755 => 100644 diff --git a/Makefile b/Makefile index 5776172..5210a3c 100644 --- a/Makefile +++ b/Makefile @@ -1,7 +1,15 @@ -.PHONY: dev precommit precommit_fix help +.PHONY: dev build start precommit precommit_fix sidebar_check help -dev: ## Start local docs server with live reload - make -C docusaurus dev +ENV ?= development + +start: ## Start Docusaurus site (default: ENV=development) + ENV=$(ENV) bash scripts/create_docusaurus_website.sh + +dev: ## Alias to start in development mode + ENV=development bash scripts/create_docusaurus_website.sh + +build: ## Alias to start in production mode + ENV=production bash scripts/create_docusaurus_website.sh precommit: ## Run docs precommit checks make -C readmes precommit @@ -9,9 +17,8 @@ precommit: ## Run docs precommit checks precommit_fix: ## Try to fix existing precommit issues make -C readmes precommit_fix -sidebar_check: ## Check if all pages are implemented with sidebars for 1.7.0, 1.8.0, and latest - python3 check_sidebars.py +sidebar_check: ## Check if all pages are implemented with sidebars + python3 scripts/check_sidebars.py -# Ref: https://marmelab.com/blog/2016/02/29/auto-documented-makefile.html help: ## Show documented commands @grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-25s\033[0m %s\n", $$1, $$2}' diff --git a/README.md b/README.md index 82cacc5..8a0fb0e 100644 --- a/README.md +++ b/README.md @@ -7,4 +7,12 @@ A standalone home for work on documentation for Magma, in order to make check-in This document provides pointers for those looking to make documentation changes for the Magma project - [Documentation Overview](https://github.com/magma/magma/wiki/Contributing-Documentation) for general documentation information -- `make help` for specific commands +- Makefile usage: + ```bash + make dev # starts Docusaurus with live reload (dev mode) + make build # starts Docusaurus in production mode + make start ENV=production # also possible + make precommit # runs precommit checks + make sidebar_check # checks if all docs have a sidebar entry + make help # shows all available commands + ``` diff --git a/docusaurus/versioned_docs/version-1.0.0/howtos/docusaurus.md b/docusaurus/versioned_docs/version-1.0.0/howtos/docusaurus.md index 4838c53..a39ca95 100644 --- a/docusaurus/versioned_docs/version-1.0.0/howtos/docusaurus.md +++ b/docusaurus/versioned_docs/version-1.0.0/howtos/docusaurus.md @@ -8,7 +8,7 @@ original_id: docusaurus ### Generating the Documentation Website 1. Ensure [docker](https://docs.docker.com/install/) is installed -2. From `magma/docs`, run `./docusaurus/create_docusaurus_website.sh` +2. Run `./scripts/create_docusaurus_website.sh` 3. Navigate to http://127.0.0.1:3000/magma/ to view a local version of the site ### Directory Structure diff --git a/docusaurus/versioned_docs/version-1.0.X/howtos/docusaurus.md b/docusaurus/versioned_docs/version-1.0.X/howtos/docusaurus.md index 04eed77..82ab59c 100644 --- a/docusaurus/versioned_docs/version-1.0.X/howtos/docusaurus.md +++ b/docusaurus/versioned_docs/version-1.0.X/howtos/docusaurus.md @@ -8,7 +8,7 @@ original_id: docusaurus ### Generating the Documentation Website 1. Ensure [docker](https://docs.docker.com/install/) is installed -2. From `magma/docs`, run `./docusaurus/create_docusaurus_website.sh` +2. Run `./scripts/create_docusaurus_website.sh` 3. Navigate to http://127.0.0.1:3000/magma/ to view a local version of the site ### Directory Structure diff --git a/check_sidebars.py b/scripts/check_sidebars.py old mode 100755 new mode 100644 similarity index 100% rename from check_sidebars.py rename to scripts/check_sidebars.py diff --git a/docusaurus/create_docusaurus_website.sh b/scripts/create_docusaurus_website.sh old mode 100755 new mode 100644 similarity index 52% rename from docusaurus/create_docusaurus_website.sh rename to scripts/create_docusaurus_website.sh index 7b983e8..9b5789e --- a/docusaurus/create_docusaurus_website.sh +++ b/scripts/create_docusaurus_website.sh @@ -13,9 +13,15 @@ set -e +# ============================== +# Choose environment: development | production +# Default is "development" +ENV=${ENV:-development} +# ============================== + function exit_timeout() { echo '' - docker compose logs docusaurus + docker compose logs $SERVICE echo '' echo "Timed out after ${1}s waiting for Docusaurus container to build. See logs above for more info." echo "Possible remedies:" @@ -23,7 +29,7 @@ function exit_timeout() { exit 1 } -# spin until localhost:3000 returns HTTP code 200. +# spin until localhost:3000 returns HTTP code 200 (only for dev) function spin() { maxsec=300 spin='-\|/' @@ -38,16 +44,31 @@ function spin() { printf "\r \n" } +# Select service name and port based on environment +if [[ "$ENV" == "production" ]]; then + SERVICE="docusaurus-prod" + PORT=8080 + URL="http://localhost:$PORT/" +else + SERVICE="docusaurus-dev" + PORT=3000 + URL="http://localhost:$PORT/docs/basics/introduction" +fi + +# Run +echo "==> Starting Docusaurus in '$ENV' mode..." + docker compose down -docker build -t magma_docusaurus . -docker compose --compatibility up -d - -echo '' -echo 'NOTE: README changes will live-reload. Sidebar changes require re-running this script.' -echo '' -echo 'Waiting for Docusaurus site to come up...' -echo 'If you want to follow the build logs, run docker compose logs -f docusaurus' -spin -echo 'Navigate to http://localhost:3000/ to see the docs.' - -xdg-open 'http://localhost:3000/docs/next/basics/introduction.html' || true +docker compose --compatibility up -d $SERVICE + +if [[ "$ENV" == "development" ]]; then + echo '' + echo 'NOTE: README changes will live-reload. Sidebar changes require re-running this script.' + echo '' + echo 'Waiting for Docusaurus site to come up...' + echo "If you want to follow the build logs: docker compose logs -f $SERVICE" + spin +fi + +echo "==> Docusaurus is running at: $URL" +# xdg-open "$URL" || true