Update contributing and local setup instructions

CONTRIBUTING.md

@@ -1,5 +1,29 @@
-# CONTRIBUTING
+# Contributing
 
-CONTRIBUTING
+To report issues, request updates, or suggest changes, use the **Edit in
+GitHub** link located in the upper right on every Amperity documentation page
+to open that page in the Amperity documentation repository on GitHub.
 
+From that page you may:
 
+1. Report an issue
+1. Request an update
+1. Suggest changes
+
+
+## Style guide
+
+The style guide is published on the docs site itself:
+
+* [Style](https://docs.amperity.com/contributing/style.html)
+
+as well as some other guides linked from that page.
+
+
+## Preview changes locally
+
+This repo uses a Makefile for local development commands.
+
+Clone this repo, then run `make help` to see the available commands.
+
+To preview a change locally, run `make serve`.

Makefile

@@ -1,8 +1,7 @@
 BUILDDIR = build
-BUILD_COMMAND = python3.9 -m sphinx -b html --jobs auto -W
-BUILD_HELP_COMMAND = python3.9 -m sphinx -b text --jobs auto -W
+BUILD_COMMAND = .venv/bin/python -m sphinx -b html --jobs auto -W
 
-all: base user operator api reference guides amp360 ampiq contributing tooltips modals legacy
+all: deps base user operator api reference guides amp360 ampiq contributing tooltips modals legacy
 
 static:
 	cp -vr downloads $(BUILDDIR)/
@@ -58,15 +57,19 @@ legacy: static ## Build only the "/legacy" section
 clean: ## Flush the entire build directory
 	# Cleaning out build directory...
 	@rm -rf $(BUILDDIR)
+	# Cleaning out .venv directory...
+	@rm -rf .venv
 
-serve: ## Start up a server on http://locahost:8080
-	serve -dir build
-	open http://localhost:8080
+deps: ## Create a Python virtualenv and install dependencies.
+	python3 -m venv .venv
+	.venv/bin/pip install --quiet -r requirements.txt
 
-dependencies: ## Install all the required dependencies. You must have Homebrew installed first
-	brew install python
-	pip3 install -r requirements.txt
-	brew install serve
+render:
+	$(BUILD_COMMAND)
+
+serve: all ## Build and serve the docs from a local HTTP server.
+	# Serving docs on http://localhost:8080 ...
+	.venv/bin/python -m http.server --directory build --bind localhost 8080
 
 help:
 	@grep -E '^[a-zA-Z0-9_-]+:.*?## .*$$' $(MAKEFILE_LIST) \

README.md

@@ -9,14 +9,6 @@ If you'd like to help improve the documentation you can:
 1. Request an update
 1. Suggest changes
 
-## Quick start
+## Contributing
 
-To build the documentation locally you'll need to install Sphinx, which is the static site generator used to build Amperity documentation. Local development requires Sphinx, a minimum version of Python, and a small collection of Python libraries, Sphinx extensions, and a makefile.
-
-To report issues, request updates, or suggest changes without using local development, use the Edit in GitHub link located in the upper right on every Amperity documentation page to open that page in the Amperity documentation repository on GitHub.
-
-From that page you may:
-
-1. Report an issue
-1. Request an update
-1. Suggest changes
+Please see [CONTRIBUTING.md](./CONTRIBUTING.md).

requirements.txt

@@ -4,6 +4,8 @@ shibuya==2025.4.25
 sphinx_design==0.6.1
 sphinx-togglebutton==0.3.2
 sphinx_sitemap==2.6.0
+sphinx-copybutton==0.5.2
+sphinxcontrib-mermaid==1.2.3
 sphinxcontrib-video==0.4.1
 sphinxcontrib-youtube==1.4.1
 sphinx-new-tab-link==0.8.0