aboutsummaryrefslogtreecommitdiffstats
path: root/source
diff options
context:
space:
mode:
authorMarti Bolivar <mbolivar@leaflabs.com>2011-10-08 00:27:46 -0400
committerMarti Bolivar <mbolivar@leaflabs.com>2011-10-08 00:32:02 -0400
commitf780ea927c32cf0fc72ab0e3f3fda1d4df644b29 (patch)
treed96f8b1e964865ac35d6dd9fc2562b8b3210186b /source
parent0b5fd1df1a87f240b9a93c4f46983ebcb9d71242 (diff)
downloadlibrambutan-f780ea927c32cf0fc72ab0e3f3fda1d4df644b29.tar.gz
librambutan-f780ea927c32cf0fc72ab0e3f3fda1d4df644b29.zip
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>
Diffstat (limited to 'source')
-rw-r--r--source/_static/index-style.css15
-rw-r--r--source/_static/leaflabs-docs.css1
-rw-r--r--source/_templates/indexcontent.html112
-rw-r--r--source/_templates/layout.html10
-rw-r--r--source/arm-gcc.rst4
-rw-r--r--source/conf.py12
-rw-r--r--source/contents.rst68
-rw-r--r--source/ide.rst4
-rw-r--r--source/index.rst78
-rw-r--r--source/language.rst6
10 files changed, 218 insertions, 92 deletions
diff --git a/source/_static/index-style.css b/source/_static/index-style.css
new file mode 100644
index 0000000..a0ef75c
--- /dev/null
+++ b/source/_static/index-style.css
@@ -0,0 +1,15 @@
+/* Contents style */
+
+.contents-table {
+ font-size: large;
+}
+
+.contents-table ul, .contents-table li {
+ display: inline;
+}
+
+.contents-table ul {
+ list-style-type: none;
+ margin: 0em;
+ padding-left: 0px;
+}
diff --git a/source/_static/leaflabs-docs.css b/source/_static/leaflabs-docs.css
new file mode 100644
index 0000000..18f5bcc
--- /dev/null
+++ b/source/_static/leaflabs-docs.css
@@ -0,0 +1 @@
+/* Any custom CSS you want applied goes here */
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 %}
diff --git a/source/_templates/layout.html b/source/_templates/layout.html
index 4d92d33..2fd81ce 100644
--- a/source/_templates/layout.html
+++ b/source/_templates/layout.html
@@ -1,5 +1,11 @@
{% extends "!layout.html" %}
+
+{% set css_files = css_files + ["_static/leaflabs-docs.css"] %}
+
{% block rootrellink %}
- <li><a href="http://leaflabs.com/">LeafLabs</a> |</li>
- {{ super() }}
+ <li><a href="http://leaflabs.com/">
+ <img width="16px" src="_static/img/round_logo_32x32.ico"></img>
+ leaflabs.com
+ </a>&middot;</li>
+ <li><a href="{{ pathto('index') }}">{{ shorttitle }}</a>{{ reldelim1 }}</li>
{% endblock %}
diff --git a/source/arm-gcc.rst b/source/arm-gcc.rst
index 1d55d07..30667a2 100644
--- a/source/arm-gcc.rst
+++ b/source/arm-gcc.rst
@@ -1,8 +1,8 @@
.. _arm-gcc:
-GCC for Maple
-=============
+GCC and libc
+============
This document provides notes on using ``arm-none-eabi-gcc``, the
`CodeSourcery <http://www.codesourcery.com/>`_ version of the GNU `GCC
diff --git a/source/conf.py b/source/conf.py
index 1e18f25..5b8f2d8 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -45,7 +45,7 @@ source_suffix = '.rst'
#source_encoding = 'utf-8-sig'
# The master toctree document.
-master_doc = 'index'
+master_doc = 'contents'
# General information about the project.
project = u'Maple'
@@ -135,7 +135,7 @@ html_theme_options = {
## Font
'headfont' : 'Georgia',
- 'bodyfont' : 'Lucidia'
+ 'bodyfont' : 'Lucida'
}
# Add any paths that contain custom themes here, relative to this directory.
@@ -150,7 +150,7 @@ html_short_title = 'Index'
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
-html_logo = '_static/img/round_logo_60x60.png'
+# html_logo = '_static/img/round_logo_60x60.png'
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
@@ -177,7 +177,9 @@ html_sidebars = {
# Additional templates that should be rendered to pages, maps page names to
# template names.
-#html_additional_pages = {}
+html_additional_pages = {
+ 'index': 'indexcontent.html'
+}
# If false, no module index is generated.
#html_domain_indices = True
@@ -259,7 +261,7 @@ man_pages = [
# Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'http://docs.python.org/': None}
+#intersphinx_mapping = {'http://docs.python.org/': None}
# -- Options for breathe integration ------------------------------------------
diff --git a/source/contents.rst b/source/contents.rst
new file mode 100644
index 0000000..63aebee
--- /dev/null
+++ b/source/contents.rst
@@ -0,0 +1,68 @@
+.. _index:
+
+Contents in Full
+================
+
+.. _index-usage:
+
+**Getting Started**
+
+.. toctree::
+ :maxdepth: 2
+
+ maple-quickstart
+ maple-ide-install
+ ide
+ unix-toolchain
+
+.. _index-maple-programming:
+
+**Programming**
+
+.. toctree::
+ :maxdepth: 2
+
+ language
+ libraries
+ arduino-compatibility
+ libmaple
+ bootloader
+ troubleshooting
+ FAQ <faq>
+ arm-gcc
+ language-index
+
+.. _index-hardware:
+
+**Peripherals**
+
+.. toctree::
+ :maxdepth: 2
+
+ adc
+ external-interrupts
+ fsmc
+ gpio
+ i2c
+ jtag
+ pwm
+ spi
+ timers
+ systick
+ usb
+ usart
+
+.. _index-boards:
+
+**Boards**
+
+.. toctree::
+ :maxdepth: 2
+
+ hardware/maple.rst
+ hardware/maple-ret6.rst
+ hardware/maple-mini.rst
+ hardware/maple-native-beta.rst
+
+.. TODO [Maple Native] write/include upon finished Native release
+.. hardware/maple-native.rst
diff --git a/source/ide.rst b/source/ide.rst
index 6e36e47..e6d49fc 100644
--- a/source/ide.rst
+++ b/source/ide.rst
@@ -1,7 +1,7 @@
.. _ide:
-Maple IDE
-=========
+Using Maple IDE
+===============
This page documents the basic functionality of the Maple IDE.
Specifically, it describes the operation of the buttons on the main
diff --git a/source/index.rst b/source/index.rst
deleted file mode 100644
index e8f0277..0000000
--- a/source/index.rst
+++ /dev/null
@@ -1,78 +0,0 @@
-.. _index:
-
-LeafLabs Documentation Index
-============================
-
-Welcome to the LeafLabs documentation!
-
-If you're setting up a board for the first time, try the
-:ref:`quickstart <maple-quickstart>`. If you're having problems,
-check out the :ref:`troubleshooting <troubleshooting>` and :ref:`FAQ
-<faq>` pages.
-
-If you can't find what you're looking for here, try the `LeafLabs wiki
-<http://wiki.leaflabs.com/index.php?title=Main_Page>`_.
-
-.. _index-usage:
-
-**Usage Guides:**
-
-.. toctree::
- :maxdepth: 1
-
- Quickstart <maple-quickstart>
- IDE Installation <maple-ide-install>
- IDE Usage <ide>
- Command-Line Toolchain <unix-toolchain>
-
-.. _index-maple-programming:
-
-**Maple Programming:**
-
-.. toctree::
- :maxdepth: 1
-
- Language <language>
- Libraries <libraries>
- Arduino Compatibility <arduino-compatibility>
- libmaple
- Bootloader <bootloader>
- Troubleshooting <troubleshooting>
- FAQ <faq>
- GCC and libc for Maple <arm-gcc>
- Language Index <language-index>
-
-.. _index-hardware:
-
-**Hardware Peripherals:**
-
-.. toctree::
- :maxdepth: 1
-
- adc
- external-interrupts
- fsmc
- gpio
- i2c
- jtag
- pwm
- spi
- timers
- systick
- usb
- usart
-
-.. _index-boards:
-
-**Board Hardware Documentation:**
-
-.. toctree::
- :maxdepth: 1
-
- hardware/maple.rst
- hardware/maple-ret6.rst
- hardware/maple-mini.rst
- hardware/maple-native-beta.rst
-
-.. TODO [Maple Native] write/include upon finished Native release
-.. hardware/maple-native.rst
diff --git a/source/language.rst b/source/language.rst
index 1a8ef30..20827cc 100644
--- a/source/language.rst
+++ b/source/language.rst
@@ -2,9 +2,9 @@
.. _language:
-==========================
- Maple Language Reference
-==========================
+====================
+ Language Reference
+====================
The Maple can be programmed in the `Wiring
<http://www.wiring.org.co/reference/>`_ language, which is the same