From 49a9b343debd306d946003d648e9500fee3ceff6 Mon Sep 17 00:00:00 2001
From: classabbyamp <dev@placeviolette.net>
Date: Tue, 6 Feb 2024 13:49:17 -0800
Subject: [PATCH] docs/: always use venv on void

there are now several pip packages not packaged on void, so `make setup-void`
should install the packages not needed in the venv then create the venv.

also rewrite docs/README a little bit
---
 docs/Makefile  |  5 +++--
 docs/README.md | 27 ++++++++++++++-------------
 2 files changed, 17 insertions(+), 15 deletions(-)

diff --git a/docs/Makefile b/docs/Makefile
index 1c62708..d59df94 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -10,7 +10,7 @@ INSTALLOPTS   ?= -Su
 SOURCEDIR     = .
 BUILDDIR      = _build
 
-VOID_PKGS     = python3-rst2ansi python3-sphinx-tabs python3-sphinx_rtd_theme python3-recommonmark python3-sphinx-copybutton watchexec
+VOID_PKGS     = python3-rst2ansi watchexec
 
 # Use the virtual environment if it exists
 ifneq ("$(wildcard $(VENV)/bin/sphinx-build)","")
@@ -40,6 +40,7 @@ gen-man: man
 
 setup-void:
 	@$(SUDO) xbps-install $(INSTALLOPTS) $(VOID_PKGS)
+	@$(MAKE) $(MAKEFLAGS) setup
 
 setup: $(VENV)/req_done
 
@@ -52,7 +53,7 @@ watch:
 envclean:
 	@rm -rf $(VENV)
 
-clean-void:
+clean-void: envclean
 	@$(SUDO) xbps-remove -R $(VOID_PKGS)
 
 $(VENV)/success:
diff --git a/docs/README.md b/docs/README.md
index e4a324d..06dc3d8 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -8,30 +8,31 @@ The `Makefile` alongside this document provides several targets to prepare the S
 
 ### Prerequisites
 
-Python 3 and several Python 3 packages are needed:
+Python 3 and several Python 3 packages are needed (see `requirements.txt` for a complete list). These packages can be
+installed through your system package manager or via pip in a virtual environment with `make setup`.
 
-- rst2ansi
-- sphinx
-- sphinx-tabs
-- sphinx_rtd_theme
-- recommonmark
+Some make targets require further programs: `watchexec` for `make serve` and `rst2ansi` for `make gen-man`.
 
-On Void Linux, these can be installed with `make setup-void`. Otherwise, these packages can be installed through your
-system package manager or via pip in a virtual environment with `make setup`.
-
-If using the virtual environment method, you will then need to activate this environment with `source env/bin/activate`
-(may be different for some shells) before running a build command.
+On Void Linux, `make setup-void` will install these programs and set up the virtual environment.
 
 ### Generating Documentation
 
 Generally, the commands to build the documentation are `make html` (to build the web documentation) and `make man` (to
 build the manpages).
 
-Several special targets exist too. `make serve` can be used to build and locally serve the web documentation using
-Python's built-in webserver. `make gen-man` can be used to build the manpages and update them in `/docs/man/dist`.
+Several special targets exist too:
+
+- `make serve` can be used to build and locally serve the web documentation using Python's built-in webserver.
+- `make gen-man` can be used to build the manpages and update them in `/docs/man/dist`.
 
 See `make help` for a list of all possible targets.
 
+### Cleaning up
+
+- `make clean` will clean up the generated documentation.
+- `make envclean` will clean up the virtual environment.
+- `make clean-void` will clean up the virtual environment and remove any installed packages.
+
 ## Organisation
 
 - `conf.py`: the Sphinx configuration file