From f780ea927c32cf0fc72ab0e3f3fda1d4df644b29 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Sat, 8 Oct 2011 00:27:46 -0400 Subject: 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 --- README | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'README') diff --git a/README b/README index 4cdf66f..f3839cd 100644 --- a/README +++ b/README @@ -110,9 +110,10 @@ Just point your web browser at the file build/html/index.html -It corresponds to the Sphinx file - - source/index.rst +For the most poart, the file build/html/foo.html is built from +source/foo.rst. (The index is an exception, because we needed to +hand-hack the HTML to get the "Contents at a Glance" section to look +nice). Read more about Sphinx and use the existing docs source as an example when writing yours. The directory tmpl/ contains template ReST files -- cgit v1.2.3