From 53c69ce04faed3dcc68ca0f54cb8d703d8babf69 Mon Sep 17 00:00:00 2001
From: Nikhil Ramakrishnan <ramakrishnan.nikhil@gmail.com>
Date: Sat, 25 Aug 2018 12:06:32 +0530
Subject: [PATCH] * docs/reference: Add resources for `docwriter'.

Add the required resources (images, JS, CSS) for `docwriter'.

* docs/reference/.gitignore: Update to ignore `site' folder and other
files generated by docwriter.

* docs/reference/README: Add docwriter usage information and
troubleshooting tips.

* docs/reference/markdown: New directory to hold generated markdown
files and other resources.
---
 docs/reference/.gitignore                     |  11 +
 docs/reference/README                         |  34 ++-
 docs/reference/markdown/images/favico.ico     | Bin 0 -> 1150 bytes
 docs/reference/markdown/javascripts/extra.js  |  54 +++++
 docs/reference/markdown/stylesheets/extra.css | 218 ++++++++++++++++++
 5 files changed, 315 insertions(+), 2 deletions(-)
 create mode 100644 docs/reference/markdown/images/favico.ico
 create mode 100644 docs/reference/markdown/javascripts/extra.js
 create mode 100644 docs/reference/markdown/stylesheets/extra.css

diff --git a/docs/reference/.gitignore b/docs/reference/.gitignore
index 2d19fc766..e245bdc52 100644
--- a/docs/reference/.gitignore
+++ b/docs/reference/.gitignore
@@ -1 +1,12 @@
+# Static site folder
+site/
+
+# HTML and Markdown files
 *.html
+*.md
+
+# MkDocs Config file
+mkdocs.yml
+
+# Python virtualenv
+env/
diff --git a/docs/reference/README b/docs/reference/README
index 51b04d6f1..3ffcfc080 100644
--- a/docs/reference/README
+++ b/docs/reference/README
@@ -1,5 +1,35 @@
-After saying `make refdoc' this directory contains the FreeType API
-reference.  You need python to make this target.
+After saying `make refdoc' or `make refdoc-venv' the `site/' directory
+contains the FreeType API reference.  You need python and pip to make this
+target.
+
+There are two ways to generate the documentation:
+
+1. Using `make refdoc':
+
+    - Ensure `python' and `pip' are available.
+    - Install pip package `docwriter' with `pip install --user docwriter'.
+    - Make target with `make refdoc'.
+    - This target can be run offline once required packages are installed.
+
+2. Using `make refdoc-venv' (requires internet access):
+
+    - Ensure `python', `pip' and python package `virtualenv' are available.
+    - Make target with `make refdoc-venv'.
+    - This may or may not require internet access every time depending on
+    pip and system caching.
 
 This also works with Jam: Just type `jam refdoc' in the main directory.
 
+Some troubleshooting tips:
+
+* Regularly run `pip install --upgrade docwriter' to check for updates which
+may include bug fixes.
+
+* Ensure that `docwriter' is installed in the same python target that
+`make refdoc' uses (python3/python2/python).
+
+* `pip' and `python' may point to different versions of Python.  Check using
+`python --version' and `pip --version'.
+
+* If none of this works, send a mail to `freetype-devel@nongnu.org' or file
+an issue at `https://github.com/freetype/docwriter/issues'.
diff --git a/docs/reference/markdown/images/favico.ico b/docs/reference/markdown/images/favico.ico
new file mode 100644
index 0000000000000000000000000000000000000000..a1a22ed43bd4a8f885c727c8061f5559517b5a0d
GIT binary patch
literal 1150
zcmdT^-7AAp7(X&LEj3e{LS{3z`3MP{Bt;~jGZfzUrDQ|%wJ=hwk&lHdqZO`Xxpv|2
za^b?w&pFS_TBLBdPS1JHd4A9DoagzS-j}f~J`4uNXA28x7&9@(9Nc(_N7OiXjB(7U
zSB>_3vPwC~WRuRi@%r|XvVp^Dv~HT<**3$yWrinQgz=-c6fSZ{V-0YJ)tvHa4OZgQ
zg!dg=V4u~J9u+gW<ON<b$uPX{p`6hD2weU=SUz;CP_zhLDTEEgY^e6@QNL(F<FXL~
z6WW$Z+3-f%DQ7e3L(PI7Hd#GCo$re~c+G{BH+brTeMXn!`=USdSFa@Er0Xzo)&lEC
z590pc@OP3jq*xD~)v;xR&_L8_naalKm-<Ct)C2Ev?OG;I&rvC?N*0=f#i-#rIOla-
zk9=5V%{RW_I_7k!oXx|=jjG?!g&oc7M!1%=2qwH3J8`2kQjDfh0p#;8x+DBJ&fnLF
zx}Y9`L?7`lpAHBcJ8wj9v<iF4c_f~XDJC=-KB>jV-4yM29~AT-I<a!=P2uUf{dJwm
N-;SvL^FQ!k{|@GV8D9VZ

literal 0
HcmV?d00001

diff --git a/docs/reference/markdown/javascripts/extra.js b/docs/reference/markdown/javascripts/extra.js
new file mode 100644
index 000000000..00f167089
--- /dev/null
+++ b/docs/reference/markdown/javascripts/extra.js
@@ -0,0 +1,54 @@
+/*
+Internal link topbar offest adjust Javascript
+Code provided by @makshh on GitHub
+
+Bug report on material-mkdocs
+  https://github.com/squidfunk/mkdocs-material/issues/791
+*/
+
+// Offset top helper
+function offsetY(elem) {
+    if(!elem) elem = this;
+    var y = elem.offsetTop;
+    while (elem = elem.offsetParent) {
+        y += elem.offsetTop;
+    }
+    return y;
+}
+
+// If a link on the same page is clicked, calculate the
+// correct offset and scroll to that part of the page.
+//
+var links = document.getElementsByTagName('a');
+for(var i = 0; i < links.length; i++) {
+    links[i].onclick = function (event) {
+        if (this.pathname == window.location.pathname &&
+            this.protocol == window.location.protocol &&
+            this.host == window.location.host) {
+                event.preventDefault();
+                if(this.hash.substr(1)){
+                    var o = document.getElementById(this.hash.substr(1));
+                    var sT = offsetY(o) - document.getElementsByClassName('md-header')[0].clientHeight;
+                    window.location.hash = this.hash;
+                    window.scrollTo(0, sT);
+                }
+        }
+    }
+}
+
+// Slugify supplied text
+function slugify(text){
+    text = text.toLowerCase();
+    text = text.replace(" ", "-");
+    return text;
+}
+
+// If there is a hash in the url, slugify it
+// and replace
+if(window.location.hash) {
+    // Fragment exists
+    slug = slugify(window.location.hash);
+    history.replaceState(undefined, undefined, slug)
+    //window.location.hash = slug;
+    document.location.replace(window.location.href);
+}
diff --git a/docs/reference/markdown/stylesheets/extra.css b/docs/reference/markdown/stylesheets/extra.css
new file mode 100644
index 000000000..92850ef19
--- /dev/null
+++ b/docs/reference/markdown/stylesheets/extra.css
@@ -0,0 +1,218 @@
+/* Body and page */
+.wy-nav-content {
+    max-width: 90%;
+}
+.md-grid {
+    max-width: 90%;
+}
+.md-sidebar--secondary {
+    margin-left: 90%;
+}
+p {
+    text-align: justify;
+   /* margin: 1.5ex 0 1.5ex 0;
+    */
+}
+/* .md-typeset p{
+    margin: 1em 1em 0 1em;
+}
+*/
+/* code blocks */
+pre.colored {
+    color: blue;
+}
+pre {
+    font-family: monospace;
+    background-color: #D6E8FF;
+    padding: 2ex 0 2ex 1%;
+    overflow-x:auto;
+}
+span.keyword {
+    font-family: monospace;
+    text-align: left;
+    white-space: pre;
+    color: #d73a49;
+}
+/* H4 Heading */
+h4 {
+    background-color: #EEEEFF;
+    font-size: medium;
+    font-style: oblique;
+    font-weight: bold;
+   /* margin: 3ex 0 1.5ex 9%;
+    */
+    padding: 0.3em 0 0.3em 1%;
+}
+/* Fields table */
+table.fields {
+    width: 90%;
+    margin: 1.5ex 0 1.5ex 10%;
+}
+table.fields td.val {
+    font-weight: bold;
+    text-align: right;
+    width: 30%;
+    vertical-align: baseline;
+    padding: 1em 1em 0 0;
+}
+table.fields td.desc {
+    vertical-align: baseline;
+    padding: 1ex 0 0 1em;
+}
+table.fields td.desc p:first-child {
+    margin: 0;
+}
+
+table.fields td.desc p {
+    margin: 1.5ex 0 0 0;
+}
+
+/* START EXPERIMENTAL CODE */
+table.long {
+    display: block;
+    width: 93%;
+}
+table.long thead,
+table.long tbody,
+table.long th,
+table.long td,
+table.long tr {
+    display: block;
+}
+/* Hide table headers (but not display: none;
+, for accessibility) */
+table.long thead tr {
+    position: absolute;
+    top: -9999px;
+    left: -9999px;
+}
+table.long tr {
+    border: 0;
+}
+table.long {
+    margin: 1.5ex 3% 1.5ex 3%;
+}
+table.long td.val {
+    text-align: left;
+}
+table.long td {
+   /* Behave like a "row" */
+    border: none;
+    border-bottom: 0;
+    position: relative;
+    padding-left: 50%;
+}
+table.long td:before {
+   /* Now like a table header */
+    position: absolute;
+   /* Top/left values mimic padding */
+    top: 6px;
+    left: 6px;
+    width: 45%;
+    padding-right: 10px;
+    white-space: nowrap;
+}
+/* END EXPERIMENTAL CODE */
+
+/* Index table */
+table.index {
+    width: 100%;
+    border-collapse: collapse;
+    border: 0;
+    border-spacing: 1em 0.3ex;
+}
+table.index tr {
+    padding: 0;
+}
+table.index td {
+    padding: 0;
+}
+table.index-toc-link {
+    width: 100%;
+    border: 0;
+    border-spacing: 0;
+    margin: 1ex 0 1ex 0;
+}
+table.index-toc-link td.left {
+    padding: 0 0.5em 0 0.5em;
+    font-size: 83%;
+    text-align: left;
+}
+table.index-toc-link td.middle {
+    padding: 0 0.5em 0 0.5em;
+    font-size: 83%;
+    text-align: center;
+}
+table.index-toc-link td.right {
+    padding: 0 0.5em 0 0.5em;
+    font-size: 83%;
+    text-align: right;
+}
+/* toc table */
+table.toc {
+    width: 95%;
+    margin: 1.5ex 0 1.5ex 5%;
+}
+table.toc td.link {
+    width: 30%;
+    text-align: right;
+    vertical-align: baseline;
+    padding: 1ex 1em 1ex 0;
+}
+table.toc td.desc {
+    vertical-align: baseline;
+    padding: 1ex 0 1ex 1em;
+    text-align: left;
+}
+table.toc td.desc p:first-child {
+    margin: 0;
+    text-align: left;
+}
+table.toc td.desc p {
+    margin: 1.5ex 0 0 0;
+    text-align: left;
+}
+div.timestamp {
+    font-size: small;
+}
+/* Max width before this PARTICULAR table gets nasty This query will take effect for any screen smaller than 760px and also iPads specifically. */
+@media only screen and (max-width: 760px), (min-device-width: 768px) and (max-device-width: 1024px) {
+   /* Force table to not be like tables anymore */
+    table, thead, tbody, th, td, tr {
+        display: block;
+   }
+   /* Hide table headers (but not display: none;
+    , for accessibility) */
+    thead tr {
+        position: absolute;
+        top: -9999px;
+        left: -9999px;
+   }
+    tr {
+        border: 0;
+   }
+    table.fields {
+        width: 93%;
+        margin: 1.5ex 3% 1.5ex 3%;
+   }
+    table.fields td.val {
+        text-align: left;
+   }
+    td {
+       /* Behave like a "row" */
+        border: none;
+        border-bottom: 0;
+        position: relative;
+        padding-left: 50%;
+   }
+    td:before {
+       /* Now like a table header */
+        position: absolute;
+       /* Top/left values mimic padding */
+        top: 6px;
+        left: 6px;
+        width: 45%;
+        padding-right: 10px;
+        white-space: nowrap;
+   }
+}