Metadata-Version: 2.1
Name: docwriter
Version: 1.3.3
Summary: API reference documentation generator for FreeType.
Home-page: https://gitlab.freedesktop.org/freetype/docwriter
Author: Nikhil Ramakrishnan
Author-email: freetype-devel@nongnu.org
License: FreeType License
Keywords: freetype docwriter
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Topic :: Documentation
Classifier: Topic :: Text Processing
Requires-Python: >=3.5
Description-Content-Type: text/markdown
Requires-Dist: mistune <3.0,>=0.8.4
Requires-Dist: mkdocs >=1.4.3
Requires-Dist: mkdocs-material >=8.2.6
Requires-Dist: PyYAML >=5.4.1

[![pipeline status](https://gitlab.freedesktop.org/freetype/docwriter/badges/master/pipeline.svg)](https://gitlab.freedesktop.org/freetype/docwriter/-/commits/master)
[![PyPI version](https://badge.fury.io/py/docwriter.svg)](https://pypi.org/project/docwriter/)

# 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
1.  Ensure `docwriter` is installed using `pip`.

2.  Clone the freetype repository from
    [here](https://gitlab.freedesktop.org/freetype/freetype.git).

3.  The FreeType build system can be used to generate the docs:

    ```bash
    sh autogen.sh
    ./configure
    make refdoc
    ```

4. 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 on
   `virtualenv` usage can be found
   [here](https://gitlab.freedesktop.org/freetype/freetype/-/blob/master/docs/README).

## Development Usage
1.  Clone this repository.
2.  Clone the freetype repository from
    [here](https://gitlab.freedesktop.org/freetype/freetype.git).
3.  Run `pip install -r requirements.txt` in your environment (`virtualenv` recommended).
4.  Copy the `include/` directory from `freetype` to `docwriter`.
5.  Run in the `docwriter` directory:

    ```bash
    python -m docwriter                      \
            --prefix=ft2                     \
            --title=FreeType-2.13.1          \
            --site=reference                 \
            --output=./docs                  \
            ./include/freetype/*.h           \
            ./include/freetype/config/*.h    \
            ./include/freetype/cache/*.h
    ```
6.  The markdown files are generated in `docs/markdown/`. Static site can be built by running
    `mkdocs build` in `docs/`. Read more about Mkdocs
    [here](https://www.mkdocs.org/getting-started/#building-the-site).

## Usage Information

```
docwriter [-h] [-t T] -o DIR [-p PRE] [-s DIR] [-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'
  -s DIR, --site DIR    set 'site_dir' in mkdocs.yml [default=site]
  -q, --quiet           run quietly, show only errors
  -v, --verbose         increase output verbosity
```

## Running Tests

To test on all supported Python versions:

1.  Make sure `tox` is installed:
    ```bash
    pip install tox
    ```

2.  Ensure that all Python versions that you need to run the tests on are installed.

3.  Run tests:
    ```bash
    tox
    ```

To run specifc tests, use the `-e` argument. For example,

```bash
tox -e py37,py38
```

will run tests only on Python 3.7 and 3.8 (assuming they are installed). See [tox.ini](tox.ini) for
all available environments.

More information on running specific tox environments can be found
[here](https://tox.readthedocs.io/en/latest/example/general.html#selecting-one-or-more-environments-to-run-tests-against).

### Regression Tests

Regression tests require internet access, `git`, and other FreeType [build
dependencies](https://gitlab.freedesktop.org/freetype/freetype/-/blob/master/README.git), and are
time-consuming. These tests are largely meant to run on Gitlab CI, but can also be run locally:

```bash
tox -e regression
```

## License

This library is licensed under the [FreeType License](https://www.freetype.org/license.html).

## 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.


