Redo appearance of top-level docs and pages.

This is a fairly significant set of changes, aimed at improving the
overall usability of the documentation.

Add source/_templates/indexcontent.html, which is a Jinja template
used to generate index.html.  This mimics the Python docs' style of
having a short, styled table as main index interface.  We're doing
this because people keep missing the board hardware pages that are
below the fold.  Hopefully this will make them (and other important
pages) easier to find.  The new file source/_static/index-style.css
controls the presentation of the generated index.html.

Move the contents of source/index.rst to source/contents.rst, and
increase the toctree depths to 2.  This increase has the ancillary
benefit that secondary headers within the current page are displayed
in the sidebar, which should aid navigation within the page.
contents.rst is meant to be a contents in full, where users who know
what they're looking for can go.  The "Table of Contents" link on the
sidebar points here.

Add a new source/_static/leaflabs-docs.css.  It's currently unused,
but is the place where people should put CSS that wants to override
the defaults.

Modify source/_templates/layout.html to include aforementioned
leaflabs-docs.css.  Also tweak the behavior of the rootrellink block,
which provides the breadcrumbs in page headers and footers.

Change the titles of various top-level docs so they can be referenced
from the toctrees in contents.rst directly.  Having two names (one in
the contents, one at the top of the page) has got to be confusing
people.  Make an exception for FAQ so that it appears in one line on
the sidebar.

Adjust conf.py to reflect all of these changes.  Also:

      - Fix "Lucidia" -> "Lucida" typo
      - Get rid of intersphinx_mapping (we don't use it, and including
        it makes it impossible to build the docs offline).
      - Remove the logo from sidebar; it's big and ugly and serves no
        purpose.

Signed-off-by: Marti Bolivar <mbolivar@leaflabs.com>

1 files changed, 112 insertions, 0 deletions

diff --git a/source/_templates/indexcontent.html b/source/_templates/indexcontent.html
new file mode 100644
index 0000000..49e72b7
--- /dev/null
+++ b/source/_templates/indexcontent.html
@@ -0,0 +1,112 @@
+{# This file generates the top-level index.html file. We are very
+   obviously stealing from the Python docs's style ;).
+#}
+
+<!-- Extend our layout.html. So inheritance hierarchy is Sphinx's
+     layout, then our layout.html, then this file. -->
+{% extends "layout.html" %}
+
+<!-- Pull in extra index stylesheet -->
+{% set css_files = css_files + ["_static/index-style.css"] %}
+
+<!-- Separator for contents lists -->
+{% set content_sep = "&middot;" %}
+
+<!-- Content -->
+{% block body %}
+<h1>Index</h1>
+
+Welcome!  This is the documentation for the LeafLabs Maple boards,
+version {{ release }}.
+
+<h2>Read This First</h2>
+
+<p>Just getting started? Try the <a href="{{
+pathto("maple-quickstart") }}">Quickstart</a>. Having problems? Check
+out <a href="{{ pathto("troubleshooting") }}">Troubleshooting</a> and
+the <a href="{{ pathto("faq") }}">FAQ</a>. Can't find what you want
+here?  Look on the <a href="http://wiki.leaflabs.com/">LeafLabs
+wiki</a>.
+</p>
+
+<h2>Contents at a Glance</h2>
+
+<table class="contents-table">
+  <tr>
+    <td><p><strong>Getting Started</strong></p>
+      <ul>
+        <li><a href="{{ pathto("maple-quickstart") }}">Quickstart</a>
+            {{ content_sep }}</li>
+        <li><a href="{{ pathto("maple-ide-install") }}">Installing Maple IDE</a>
+            {{ content_sep }}</li>
+        <li><a href="{{ pathto("ide") }}">Using Maple IDE</a>
+            {{ content_sep }}</li>
+        <li><a href="{{ pathto("unix-toolchain") }}">Command-Line
+                Toolchain</a></li>
+      </ul>
+    </td>
+    <td><p><strong>Boards</strong></p>
+      <ul>
+        <li><a href="{{ pathto("hardware/maple") }}">Maple</a>
+            {{ content_sep }}</li>
+        <li><a href="{{ pathto("hardware/maple-ret6") }}">Maple RET6 Edition</a>
+            {{ content_sep }}</li>
+        <li><a href="{{ pathto("hardware/maple-mini") }}">Maple Mini</a>
+            {{ content_sep }}</li>
+        <li><a href="{{ pathto("hardware/maple-native-beta") }}">Maple
+                Native β</a></li>
+      </ul>
+    </td>
+  </tr>
+  <tr>
+    <td><p><strong>Programming</strong></p>
+      <ul>
+        <li><a href="{{ pathto("language") }}">Language Reference</a>
+            {{ content_sep }}</li>
+        <li><a href="{{ pathto("troubleshooting") }}">Troubleshooting</a>
+            {{ content_sep }}</li>
+        <li><a href="{{ pathto("faq") }}">FAQ</a>
+            {{ content_sep }}</li>
+        <li><a href="{{ pathto("libraries") }}">Libraries</a>
+            {{ content_sep }}</li>
+        <li><a href="{{ pathto("libmaple") }}"><tt>libmaple</tt></a>
+            {{ content_sep }}</li>
+        <li><a href="{{ pathto("bootloader") }}">Bootloader</a>
+            {{ content_sep }}</li>
+        <li><a href="{{ pathto("arm-gcc") }}">GCC and libc</a>
+            {{ content_sep }}</li>
+        <li><a href="{{ pathto("arduino-compatibility") }}">Arduino
+                Compatibility</a></li>
+      </ul>
+    </td>
+    <td><p><strong>Peripherals</strong></p>
+      <ul>
+        <li><a href="{{ pathto("adc") }}">ADC</a>
+            {{ content_sep }}</li>
+        <li><a href="{{ pathto("external-interrupts") }}">External
+            Interrupts</a> {{ content_sep }}</li>
+        <li><a href="{{ pathto("fsmc") }}">FSMC</a>
+            {{ content_sep }}</li>
+        <li><a href="{{ pathto("gpio") }}">GPIO</a>
+            {{ content_sep }}</li>
+        <li><a href="{{ pathto("i2c") }}">I<sup>2</sup>C</a>
+            {{ content_sep }}</li>
+        <li><a href="{{ pathto("jtag") }}">JTAG</a>
+            {{ content_sep }}</li>
+        <li><a href="{{ pathto("pwm") }}">PWM</a>
+            {{ content_sep }}</li>
+        <li><a href="{{ pathto("spi") }}">SPI</a>
+            {{ content_sep }}</li>
+        <li><a href="{{ pathto("systick") }}">SysTick</a>
+            {{ content_sep }}</li>
+        <li><a href="{{ pathto("timers") }}">Timers</a>
+            {{ content_sep }}</li>
+        <li><a href="{{ pathto("usart") }}">USART</a>
+            {{ content_sep }}</li>
+        <li><a href="{{ pathto("usb") }}">USB</a></li>
+      </ul>
+    </td>
+  </tr>
+</table>
+
+{% endblock %}