From f8b2b9341661440dde1644f3c7f1c8479dd7c149 Mon Sep 17 00:00:00 2001 From: bnewbold Date: Thu, 28 May 2015 00:24:56 -0700 Subject: docs: superficial librambutan rebranding --- docs/Makefile | 4 ++-- docs/README | 15 ++++-------- docs/README-building.txt | 39 ++++++++++++++++++++------------ docs/README-maintainers.txt | 14 ++++-------- docs/source/_templates/indexcontent.html | 13 ++++++----- 5 files changed, 43 insertions(+), 42 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index 5255525..8b35b93 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,4 +1,4 @@ -# Makefile for LeafLabs documentation (automatically generated by +# Makefile for librambutan documentation (automatically generated by # Sphinx). # You can set these variables from the command line. @@ -130,5 +130,5 @@ doctest: "results in $(BUILDDIR)/doctest/output.txt." doxygen: - @echo "Wrong! You need to run this from within libmaple!" + @echo "Wrong! You need to run this from the top level!" false diff --git a/docs/README b/docs/README index 60fb888..cdfe0ae 100644 --- a/docs/README +++ b/docs/README @@ -1,14 +1,14 @@ -This repository contains source files used to generate the -documentation for LeafLabs' libmaple and Maple IDE projects [*]. The -HTML documentation generated from these sources is available online: +This directory contains source files used to generate the documentation for +librambutan. The HTML documentation generated from these sources is available +online: - http://leaflabs.com/docs/ + http://docs.rambutan.cc/projects/librambutan/en/master The above URL is the recommended way for users to read the documentation. The docs for the latest release are always available there. -Older versions are here: +Ancient libmaple versions are here: http://static.leaflabs.com/pub/leaflabs/maple-docs/ @@ -17,8 +17,3 @@ The file README-building.txt explains how to build the HTML docs. The file README-maintainers.txt contains important information for maintainers of the documentation (e.g. how to add docs for a new board, how to cut a release version of the docs, etc.). - -[*] libmaple and Maple IDE themselves are in separate repositories: - - https://github.com/leaflabs/libmaple - https://github.com/leaflabs/maple-ide diff --git a/docs/README-building.txt b/docs/README-building.txt index 6846bf7..b763f84 100644 --- a/docs/README-building.txt +++ b/docs/README-building.txt @@ -1,8 +1,7 @@ -This file explains how to build the HTML documentation. As such, it's -probably only useful to LeafLabs developers. Users can read the HTML -for the latest release here: +This file explains how to build the HTML documentation. Users can quickly read +the HTML for the latest release here: - http://leaflabs.com/docs/ + http://docs.rambutan.cc/projects/librambutan/en/master/ Install Dependencies -------------------- @@ -11,8 +10,7 @@ First, you will need to install some dependencies (Doxygen, Sphinx, and Breathe). 1. Much of the documentation is pulled out of the libmaple source - code's Doxygen comments, so you need a recent-ish version of - Doxygen in your PATH: + code's Doxygen comments, so you need Doxygen in your PATH: http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc @@ -22,21 +20,32 @@ and Breathe). These are your choices for how to install Sphinx: - - From source or .egg: - http://pypi.python.org/pypi/Sphinx#downloads + - From a Linux package manager, eg: + $ sudo apt-get install python-sphinx + + - From an OS X package manager, like MacPorts or homebrew. + + - Via pip: + $ sudo pip install Sphinx - Via easy_install: $ sudo easy_install -U Sphinx + - From source or .egg: + http://pypi.python.org/pypi/Sphinx#downloads + You need Sphinx version >= 1.0.6. 3. We use a Sphinx plugin called Breathe to parse Doxygen's XML output into a form usable by Sphinx. (More about Breathe: http://michaeljones.github.com/breathe/). - LeafLabs sometimes patches Breathe for the purposes of building our + The more recent versions of Breathe seem to have all the features necessary + to build these docs, so you can install the distribution version (breathe-doc). + + Alternatively, LeafLabs sometimes patches Breathe for the purposes of building docs, so clone the LeafLabs Breathe tree from GitHub (somewhere - else on your system, NOT in the leaflabs-docs repo): + else on your system, NOT in the librambutan repo): - LeafLabs developers, clone with push permissions: $ git clone git@github.com:leaflabs/breathe.git @@ -44,7 +53,7 @@ and Breathe). - Everyone else, clone without them: $ git clone git://github.com/leaflabs/breathe.git -4. After that's done, set environment variable BREATHE_HOME to point to + After that's done, set environment variable BREATHE_HOME to point to Breathe. Something like this in Bash: $ export BREATHE_HOME=/path/to/breathe/repo/ @@ -59,14 +68,14 @@ produce Doxygen XML output, then you can generate the final HTML docs. 1. Before the first time you run Sphinx (and any time the Doxygen comments in the libmaple source code are changed), you'll need to - re-run doxygen on libmaple. + re-run doxygen on the top level of librambutan. - $ cd /path/to/top/level + $ cd /path/to/top/level/librambutan $ make doxygen Doxygen will yell at you a lot; it's generally safe to ignore it. -2. Finally, you can build the HTML (in the leaflabs-docs repository): +2. Finally, you can build the HTML: $ cd /path/to/docs $ make html @@ -93,7 +102,7 @@ comments lives in source/. The directory source/_static/ is for static content (like style sheets); source/_templates/ is meant to contain Sphinx templates. -Read more about Sphinx and use the existing leaflabs-docs source for +Read more about Sphinx and use the existing source for examples when writing new docs. The directory tmpl/ contains template ReST files you should sometimes use when creating a page that follows a pattern (like a libmaple API page), in order to keep the style diff --git a/docs/README-maintainers.txt b/docs/README-maintainers.txt index 48e8e5c..959c5e8 100644 --- a/docs/README-maintainers.txt +++ b/docs/README-maintainers.txt @@ -1,14 +1,10 @@ This file contains information useful for the documentation's -maintainers. As such, it's probably only useful to LeafLabs -developers. Users can read the HTML for the latest release here: +maintainers. Users can read the HTML for the latest release here: - http://leaflabs.com/docs/ + http://docs.rambutan.cc/projects/librambutan/en/master/ -Things you can learn how to do from this file: - -- Cut a release version -- Fix errors in/otherwise maintain the current docs release -- Add docs for a new board +This file is out of date (libmaple era). librambutan uses readthedocs.org to +auto-build documentation. Building Documentation for a Release ------------------------------------ @@ -184,7 +180,7 @@ It needs to be updated RIGHT AWAY, you say? Here's what you do: - Distribute the updated docs. These are world-visible here: - http://static.leaflabs.com/pub/leaflabs/maple-docs/ + http://docs.rambutan.cc/ Adding a New Board ------------------ diff --git a/docs/source/_templates/indexcontent.html b/docs/source/_templates/indexcontent.html index d1bb65b..2d1c8f9 100644 --- a/docs/source/_templates/indexcontent.html +++ b/docs/source/_templates/indexcontent.html @@ -14,22 +14,23 @@ {% block body %} -

Hi!

+

Hi There!

-This is the documentation for the LeafLabs Maple boards, version {{ -release }}. +This is the documentation for librambutan, a libre firmware library for STM32 +ARM microcontrollers. If browsing on the docs.rambutan.cc website, you can +select the version/branch from the box in the lower right-hand corner.

Read This First

Having problems? Check out Troubleshooting and the FAQ. Can't find what you want -here? Look on the LeafLabs -wiki. +here? Head back up to the project-wide +docs.

See the What's New page for -changes that are new in {{ release }}.

+changes that are new in '{{ release }}'.

Contents at a Glance

-- cgit v1.2.3