From b83cf04d4a60c5a107970c0bbf339923613df071 Mon Sep 17 00:00:00 2001 From: Nikhil Ramakrishnan Date: Sat, 4 Aug 2018 16:31:44 +0530 Subject: [PATCH] Document `refdoc' usage. * docs/reference/README: Add information and instructions to use targets `make refdoc' and the new `make refdoc-venv'. Also add troubleshooting tips. --- docs/reference/README | 34 ++++++++++++++++++++++++++++++++-- 1 file changed, 32 insertions(+), 2 deletions(-) diff --git a/docs/reference/README b/docs/reference/README index 51b04d6f1..3ffcfc080 100644 --- a/docs/reference/README +++ b/docs/reference/README @@ -1,5 +1,35 @@ -After saying `make refdoc' this directory contains the FreeType API -reference. You need python to make this target. +After saying `make refdoc' or `make refdoc-venv' the `site/' directory +contains the FreeType API reference. You need python and pip to make this +target. + +There are two ways to generate the documentation: + +1. Using `make refdoc': + + - Ensure `python' and `pip' are available. + - Install pip package `docwriter' with `pip install --user docwriter'. + - Make target with `make refdoc'. + - This target can be run offline once required packages are installed. + +2. Using `make refdoc-venv' (requires internet access): + + - Ensure `python', `pip' and python package `virtualenv' are available. + - Make target with `make refdoc-venv'. + - This may or may not require internet access every time depending on + pip and system caching. This also works with Jam: Just type `jam refdoc' in the main directory. +Some troubleshooting tips: + +* Regularly run `pip install --upgrade docwriter' to check for updates which +may include bug fixes. + +* Ensure that `docwriter' is installed in the same python target that +`make refdoc' uses (python3/python2/python). + +* `pip' and `python' may point to different versions of Python. Check using +`python --version' and `pip --version'. + +* If none of this works, send a mail to `freetype-devel@nongnu.org' or file +an issue at `https://github.com/freetype/docwriter/issues'.