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
This commit is contained in:
parent
96c4d5e6e4
commit
49a9b343de
|
@ -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:
|
||||
|
|
|
@ -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
|
||||
|
|
Loading…
Reference in New Issue