[](https://gitlab.freedesktop.org/freetype/docwriter/-/commits/master)
[](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.
Raw data
{
"_id": null,
"home_page": "https://gitlab.freedesktop.org/freetype/docwriter",
"name": "docwriter",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.5",
"maintainer_email": "",
"keywords": "freetype docwriter",
"author": "Nikhil Ramakrishnan",
"author_email": "freetype-devel@nongnu.org",
"download_url": "https://files.pythonhosted.org/packages/2a/11/3c776a43e12bea7f0aaae47b0fbabff1641b534a7b212742e34b13446750/docwriter-1.3.3.tar.gz",
"platform": null,
"description": "[](https://gitlab.freedesktop.org/freetype/docwriter/-/commits/master)\n[](https://pypi.org/project/docwriter/)\n\n# FreeType Docwriter\n\nDocwriter is an API documentation generator for the FreeType Library that extracts and builds\nMarkdown docs from the FreeType header files.\n\n## Installation\n\nRun `pip install docwriter` (see (4) below for an automated `virtualenv` usage). It requires\nPython >= 3.5 to run.\n\n## Steps to Generate Docs\n1. Ensure `docwriter` is installed using `pip`.\n\n2. Clone the freetype repository from\n [here](https://gitlab.freedesktop.org/freetype/freetype.git).\n\n3. The FreeType build system can be used to generate the docs:\n\n ```bash\n sh autogen.sh\n ./configure\n make refdoc\n ```\n\n4. Alternatively, step 1 and the make target can be replaced with `make refdoc-venv`. This installs\n all requirements automatically in a separate virtual environment. More information on\n `virtualenv` usage can be found\n [here](https://gitlab.freedesktop.org/freetype/freetype/-/blob/master/docs/README).\n\n## Development Usage\n1. Clone this repository.\n2. Clone the freetype repository from\n [here](https://gitlab.freedesktop.org/freetype/freetype.git).\n3. Run `pip install -r requirements.txt` in your environment (`virtualenv` recommended).\n4. Copy the `include/` directory from `freetype` to `docwriter`.\n5. Run in the `docwriter` directory:\n\n ```bash\n python -m docwriter \\\n --prefix=ft2 \\\n --title=FreeType-2.13.1 \\\n --site=reference \\\n --output=./docs \\\n ./include/freetype/*.h \\\n ./include/freetype/config/*.h \\\n ./include/freetype/cache/*.h\n ```\n6. The markdown files are generated in `docs/markdown/`. Static site can be built by running\n `mkdocs build` in `docs/`. Read more about Mkdocs\n [here](https://www.mkdocs.org/getting-started/#building-the-site).\n\n## Usage Information\n\n```\ndocwriter [-h] [-t T] -o DIR [-p PRE] [-s DIR] [-q | -v] files [files ...]\n\nDocWriter Usage information\n\npositional arguments:\n files list of source files to parse, wildcards are allowed\n\noptional arguments:\n -h, --help show this help message and exit\n -t T, --title T set project title, as in '-t \"My Project\"'\n -o DIR, --output DIR set output directory, as in '-o mydir'\n -p PRE, --prefix PRE set documentation prefix, as in '-p ft2'\n -s DIR, --site DIR set 'site_dir' in mkdocs.yml [default=site]\n -q, --quiet run quietly, show only errors\n -v, --verbose increase output verbosity\n```\n\n## Running Tests\n\nTo test on all supported Python versions:\n\n1. Make sure `tox` is installed:\n ```bash\n pip install tox\n ```\n\n2. Ensure that all Python versions that you need to run the tests on are installed.\n\n3. Run tests:\n ```bash\n tox\n ```\n\nTo run specifc tests, use the `-e` argument. For example,\n\n```bash\ntox -e py37,py38\n```\n\nwill run tests only on Python 3.7 and 3.8 (assuming they are installed). See [tox.ini](tox.ini) for\nall available environments.\n\nMore information on running specific tox environments can be found\n[here](https://tox.readthedocs.io/en/latest/example/general.html#selecting-one-or-more-environments-to-run-tests-against).\n\n### Regression Tests\n\nRegression tests require internet access, `git`, and other FreeType [build\ndependencies](https://gitlab.freedesktop.org/freetype/freetype/-/blob/master/README.git), and are\ntime-consuming. These tests are largely meant to run on Gitlab CI, but can also be run locally:\n\n```bash\ntox -e regression\n```\n\n## License\n\nThis library is licensed under the [FreeType License](https://www.freetype.org/license.html).\n\n## History\n\nThis library was originally written by David Turner as `docmaker` which collected and presented\ndocumentation in HTML. It has since been modified multiple times, including a major refactor to\nallow multiple output formats. The current `docwriter` is the biggest rewrite, with lots of changes\nand additions that allow it to be more flexible, readable, maintainable and usable.\n\n\n",
"bugtrack_url": null,
"license": "FreeType License",
"summary": "API reference documentation generator for FreeType.",
"version": "1.3.3",
"project_urls": {
"Homepage": "https://gitlab.freedesktop.org/freetype/docwriter"
},
"split_keywords": [
"freetype",
"docwriter"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "433efd256341d7cd38932904d751ed6b80abf2388f3247ffa232ed1add30b213",
"md5": "8259b58d3627cca86ab5ad19ebaf25bc",
"sha256": "d2dd32b4ab365bf3ea1826f777ac2cc2c6a4429156f7471a707ac0725060677a"
},
"downloads": -1,
"filename": "docwriter-1.3.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8259b58d3627cca86ab5ad19ebaf25bc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.5",
"size": 28150,
"upload_time": "2023-09-05T23:58:30",
"upload_time_iso_8601": "2023-09-05T23:58:30.177500Z",
"url": "https://files.pythonhosted.org/packages/43/3e/fd256341d7cd38932904d751ed6b80abf2388f3247ffa232ed1add30b213/docwriter-1.3.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2a113c776a43e12bea7f0aaae47b0fbabff1641b534a7b212742e34b13446750",
"md5": "c11181223f398640a8cdd7870b42b37b",
"sha256": "07b27d84060776990d228b3a529c3eb269bf00b25ab33ca69f351ace2042e626"
},
"downloads": -1,
"filename": "docwriter-1.3.3.tar.gz",
"has_sig": false,
"md5_digest": "c11181223f398640a8cdd7870b42b37b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.5",
"size": 70400,
"upload_time": "2023-09-05T23:58:31",
"upload_time_iso_8601": "2023-09-05T23:58:31.799193Z",
"url": "https://files.pythonhosted.org/packages/2a/11/3c776a43e12bea7f0aaae47b0fbabff1641b534a7b212742e34b13446750/docwriter-1.3.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-05 23:58:31",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "docwriter"
}
JSON