ref: 53c69ce04faed3dcc68ca0f54cb8d703d8babf69
parent: ae5d1a4cec37557f31aec270332cfe886a62f9a0
author: Nikhil Ramakrishnan <[email protected]>
date: Sat Aug 25 08:06:32 EDT 2018
* 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.
--- a/docs/reference/.gitignore
+++ b/docs/reference/.gitignore
@@ -1,1 +1,12 @@
+# Static site folder
+site/
+
+# HTML and Markdown files
*.html
+*.md
+
+# MkDocs Config file
+mkdocs.yml
+
+# Python virtualenv
+env/
--- 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 `[email protected]' or file
+an issue at `https://github.com/freetype/docwriter/issues'.
binary files /dev/null b/docs/reference/markdown/images/favico.ico differ
--- /dev/null
+++ b/docs/reference/markdown/javascripts/extra.js
@@ -1,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);
+}
--- /dev/null
+++ b/docs/reference/markdown/stylesheets/extra.css
@@ -1,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;
+ }
+}