[freetype2] master 53c69ce 2/4: * docs/reference: Add resources for `docwriter'.

[Nikhil Ramakrishnan]

branch: master
commit 53c69ce04faed3dcc68ca0f54cb8d703d8babf69
Author: Nikhil Ramakrishnan <address@hidden>
Commit: Nikhil Ramakrishnan <address@hidden>

    * 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(-)

diff --git a/docs/reference/.gitignore b/docs/reference/.gitignore
index 2d19fc7..e245bdc 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 51b04d6..3ffcfc0 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 address@hidden' 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 0000000..a1a22ed
Binary files /dev/null and b/docs/reference/markdown/images/favico.ico differ
diff --git a/docs/reference/markdown/javascripts/extra.js 
b/docs/reference/markdown/javascripts/extra.js
new file mode 100644
index 0000000..00f1670
--- /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 0000000..92850ef
--- /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. */
address@hidden 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;
+   }
+}