API reference documentation generator for FreeType.
Project description
FreeType Docwriter
Docwriter is an API documentation generator for the FreeType Library that extracts and builds Markdown docs from the FreeType header files.
Installation
Run pip install docwriter
(see (4) below for an automated virtualenv
usage). It requires Python >= 3.5 to run.
Steps to Generate Docs
-
Ensure
docwriter
is installed usingpip
. -
Clone the freetype2 repository from here.
-
The FreeType build system can be used to generate the docs:
sh autogen.sh ./configure make refdoc
-
Alternatively, step 1 and the make target can be replaced with
make refdoc-venv
. This installs all requirements automatically in a separate virtual environment. More information onvirtualenv
usage can be found here.
Development Usage
-
Clone this repository.
-
Clone the freetype2 repository from here.
-
Run
pip install -r requirements.txt
in your environment (virtualenv
recommended). -
Copy the
include/
directory fromfreetype2
todocwriter
. -
Run in the
docwriter
directory:python -m docwriter \ --prefix=ft2 \ --title=FreeType-2.9.1 \ --site=reference \ --output=./docs \ ./include/freetype/*.h \ ./include/freetype/config/*.h \ ./include/freetype/cache/*.h
-
The markdown files are generated in
docs/markdown/
. Static site can be built by runningmkdocs build
indocs/
. Read more about Mkdocs here.
Usage Information
docwriter [-h] [-t T] -o DIR [-p PRE] [-q | -v] files [files ...]
DocWriter Usage information
positional arguments:
files list of source files to parse, wildcards are allowed
optional arguments:
-h, --help show this help message and exit
-t T, --title T set project title, as in '-t "My Project"'
-o DIR, --output DIR set output directory, as in '-o mydir'
-p PRE, --prefix PRE set documentation prefix, as in '-p ft2'
-q, --quiet run quietly, show only errors
-v, --verbose increase output verbosity
Running Tests
There are two possible test scenarios:
- Running tests on both py27 and py36 (using tox - requires both python versions installed).
- Running tests on the currently installed Python version.
They are detailed below.
Test using Tox
To test on both py27 and py36:
-
Make sure
tox
is installed:pip install tox
-
Ensure both py27 and py36 are available.
-
Run tests:
tox
Test on single python version
To test on current python version using pytest:
-
Make sure
pytest
is installed:pip install pytest
-
Run tests:
cd tests/ python -m pytest
License
This library is licensed under the FreeType License.
History
This library was originally written by David Turner as docmaker
which collected and presented
documentation in HTML. It has since been modified multiple times, including a major refactor
to allow multiple output formats. The current docwriter
is the biggest rewrite, with lots of
changes and additions that allow it to be more flexible, readable, maintainable and usable.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.