Skip to content

Instantly share code, notes, and snippets.

@nikramakrishnan

nikramakrishnan/gsoc_2018_report.md

Last active May 4, 2021 16:40
Show Gist options
  • Star 2 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save nikramakrishnan/416e34ea126287446df7764b2ebba8ca to your computer and use it in GitHub Desktop.
Save nikramakrishnan/416e34ea126287446df7764b2ebba8ca to your computer and use it in GitHub Desktop.
Download ZIP
GSoC 2018: Redevelop FreeType's documentation using markdown
Raw
gsoc_2018_report.md

GSoC 2018: Redevelop FreeType's documentation using markdown

Project Details

Project Proposal: https://docs.google.com/document/d/1T6QMVbyBl44PJMI9eJxfjmTCRJyJYyRVZcWjArm8Il4/edit?usp=sharing

GSoC Project Link: https://summerofcode.withgoogle.com/projects/#6722924292079616

Contributed Repositories: freetype/docwriter (copied from nikramakrishnan/freetype-docwriter), freetype2, nikramakrishnan/freetype-docs, nikramakrishnan/freetype-web-jekyll,

Languages: Python, Unix build tools, Markdown.

Final Work Product:

  1. A documentation extractor/generator library docwriter for FreeType published on PyPI. Documentation is extracted from the FreeType header files in Markdown format.

  2. A revamped FreeType Project website. Pages are written in Markdown, eliminating the need to maintain HTML code for every page.

Project Description

The goal of this project is to redesign and fully automate the documentation methods for FreeType, and make it easier to update and manage the FreeType website.

Introduction

Docwriter (previously docmaker) is a documentation writer that extracts, organizes and writes the API reference of the FreeType library in Markdown format, which is then converted to a static website that provides navigation and search functionality. Generating documentation in Markdown makes it much more readable and future-proof, opening up the possibility of integrating many markdown-related documentation libraries and extensions.

Usage

Generating the API reference using docwriter is fairly simple:

  1. Clone the freetype2 repository.
  2. Run pip install docwriter to get docwriter.
  3. Run make/make devel on the freetype2 root.
  4. Run make refdoc.

The markdown files are generated in docs/reference/markdown and the static site is generated in docs/reference/site.

Goals Achieved

Docwriter

  • Standardize Comment Formats (report).
  • Write the Markdown Documenatation Feature Draft (report).
  • Convert Current Documentation Syntax to Markdown (report).
  • Extend docmaker to emit markdown (report).
  • Generate MkDocs configuration file with docwriter (report).
  • Write the Documentation Guidelines for FreeType.
  • Add tests for docwriter.
  • Refactor original docmaker code to support Python 2 and 3, and other changes for better maintainability (use argparse and standard logging library).
  • Add checks and targets to the FreeType build system to generate API reference with docwriter.
  • Make docwriter a Python library and deploy on PyPI.

FreeType Site

  • Test multiple themes/generators for the FreeType website. (thread).
  • Implement the Jekyll theme for the website.
  • Convert website pages to markdown. (Pandoc followed by manual cleanup).
  • Major UI changes: Integrate FreeType logo topbar, change page color scheme depending on page depth, and more.

Final Results

Note: The links are only demos since some work is yet to be merged into the official FreeType repository.

API Reference Sample: http://nikramakrishnan.github.io/freetype-web-jekyll/docs/reference/index.html

FreeType Website Preview: http://nikramakrishnan.github.io/freetype-web-jekyll

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment