freetype-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[ft-devel] Browsing API docs locally, and other updates


From: Nikhil Ramakrishnan
Subject: [ft-devel] Browsing API docs locally, and other updates
Date: Tue, 19 Jun 2018 17:39:46 +0530

Hi all,

I was looking at how browsing the docs locally would work. With the current
configuration, running `make refdoc` with markdown docs will produce the
following tree in the `docs/reference' directory:

│   .gitignore
│   mkdocs.yml
│   README

├───markdown
│   │   ft2-auto_hinter.md
│   │   ft2-base_interface.md
│   │   ft2-basic_types.md
│   │   ft2-bdf_fonts.md
│   │   (...)
│   │
└───site
    │   404.html
    │   sitemap.xml
    │
    ├───assets
    │   ├───images
    │   ├───_javascript_s
    │   └───stylesheets
    │
    ├───ft2-auto_hinter
    │       index.html
    │
    ├───ft2-base_interface
    │       index.html
    │
    ├───ft2-basic_types
    │       index.html
    │
    ├───ft2-bdf_fonts
    │       index.html
    │ (...)
    ├───images
    ├───_javascript_s
    ├───search
    └───stylesheets

There are a few things to consider:

* As clearly seen in the tree, MkDocs creates a directory for each markdown
`file', which is OK for a website, but creates a problem for local browsing.
Although I can change links in the docs to point to index.html, the
navigation of the current theme I'm using (material) redirects *only* to the
directory URL (I have filed a bug report for this).

* MkDocs is currently getting ready for a major release, and one of the
changes allow html files to be generated in the outer directory. This is
equivalent to how html docs are generated now. This change is included in
their 1.0 release, which is expected to roll out by the end of summer.
(https://github.com/mkdocs/mkdocs/pull/1504). I am looking forward to
integrating this with docmaker, whenever available.

* I have considered alternatives like Jekyll and Sphinx:
    - Jekyll requires installing ruby to build the site. Not everybody has
    the time or patience to do this.

    - Sphinx has too many configuration `knobs' which require tuning before
    the quality of the docs is comparable to the one built with MkDocs.
    IMHO it is a good choice when docs are being written separate from code.

* I have updated the site to the latest commit (7915fd51f). Most problems
with incorrect markdown parsing and formatting have been fixed now. Please
report any problems faced, and please suggest changes!
https://nikramakrishnan.github.io/freetype-site/ft2-toc

* Next, I will start working on converting the FreeType website to Markdown.
Here, we can use anything from Jekyll, Sphinx, MkDocs etc. Please suggest!


--
Nikhil

reply via email to

[Prev in Thread] Current Thread [Next in Thread]