From 6f45284326411f3f3d68e077449f14a2d1caa693 Mon Sep 17 00:00:00 2001 From: bnewbold Date: Wed, 27 May 2015 23:14:00 -0700 Subject: docs: point doxygen fail to the correct README --- docs/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/source/conf.py b/docs/source/conf.py index 50badda..247edbf 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -268,7 +268,7 @@ if os.path.isdir(doxygen_xml_maybe): doxygen_xml_dir = doxygen_xml_maybe else: print("FAIL: doxygen hasn't been run yet in this repository; " - "see ../README") + "see README-building.txt") sys.exit(-1) breathe_projects = {'libmaple' : doxygen_xml_dir} -- cgit v1.2.3 From 124c8964eb81705d0924295e63866370e9c16ede Mon Sep 17 00:00:00 2001 From: bnewbold Date: Wed, 27 May 2015 23:15:55 -0700 Subject: docs: many small broken ref fixes, syntax bugfixes --- docs/source/bootloader.rst | 4 ++-- docs/source/epilog.rst | 3 ++- docs/source/faq.rst | 4 ++-- docs/source/lang/api/hardwarespi.rst | 3 ++- docs/source/lang/cpp/arithmetic.rst | 2 +- docs/source/libmaple/api/dma.rst | 10 +++++++--- docs/source/libmaple/api/gpio.rst | 7 +++++-- docs/source/libmaple/api/nvic.rst | 2 +- docs/source/libmaple/api/util.rst | 2 +- docs/source/libmaple/overview.rst | 2 +- 10 files changed, 24 insertions(+), 15 deletions(-) (limited to 'docs') diff --git a/docs/source/bootloader.rst b/docs/source/bootloader.rst index a4ab5c9..0896ce3 100644 --- a/docs/source/bootloader.rst +++ b/docs/source/bootloader.rst @@ -613,8 +613,8 @@ In order to follow these instructions, you will need: - A binary of the bootloader you want to upload (see below). - Hardware for communicating between the Maple and your computer over serial. -- `Python `_, version 2.5 or higher. -- The `PySerial `_ library (this +- Python_, version 2.5 or higher. +- The PySerial_ library (this must be installed separately; it is not part of the Python standard library). diff --git a/docs/source/epilog.rst b/docs/source/epilog.rst index 0c1a091..3078639 100644 --- a/docs/source/epilog.rst +++ b/docs/source/epilog.rst @@ -12,7 +12,8 @@ .. _Git: http://git-scm.com/ .. _dfu-util: http://wiki.openmoko.org/wiki/Dfu-util .. _easy_install: http://packages.python.org/distribute/easy_install.html -.. _Leaflabs Maple: http://leaflabs.com/docs/hardware/maple-mini.html +.. _Leaflabs Maple: http://leaflabs.com/docs/hardware/maple.html .. _Leaflabs Maple RET6: http://leaflabs.com/docs/hardware/maple-ret6.html .. _Leaflabs Maple Mini: http://leaflabs.com/docs/hardware/maple-mini.html .. _Leaflabs Maple Native Beta: http://leaflabs.com/docs/hardware/maple-native-beta.html +.. _Maple's master pin map: http://static.leaflabs.com/pub/leaflabs/maple-docs/latest/hardware/maple.html#master-pin-map diff --git a/docs/source/faq.rst b/docs/source/faq.rst index bd155ae..b255f52 100644 --- a/docs/source/faq.rst +++ b/docs/source/faq.rst @@ -59,8 +59,8 @@ correspond to the pin you want to write to. If you don't know what that means, don't worry. We'll go through an example here. Let's say you want to write to pin 4 on the Maple. In order to find -out the port and bit number, take look at the Maple's :ref:`master pin -map ` next to "D4". You'll see that in the +out the port and bit number, take look at the `Maple's master pin +map`_ next to "D4". You'll see that in the "GPIO" column, there's "PB5". That's short for "**P**\ ort **B**, bit **5**". So the GPIO port is "B", and the bit is "5". (If you're not on the Maple, you can find your board's pin map :ref:`from here diff --git a/docs/source/lang/api/hardwarespi.rst b/docs/source/lang/api/hardwarespi.rst index a44a65f..4d720ac 100644 --- a/docs/source/lang/api/hardwarespi.rst +++ b/docs/source/lang/api/hardwarespi.rst @@ -42,7 +42,8 @@ function (an example is given below). .. FIXME [Breathe] Output doesn't include the class; fix & submit pull req -.. doxygenfunction:: HardwareSPI::begin +.. doxygenfunction:: HardwareSPI::begin(void) +.. doxygenfunction:: HardwareSPI::begin(SPIFrequency, uint32, uint32) .. note:: If you are using SPI port 3 (on a board that supports it; not all do); you'll need to call :ref:`lang-disabledebugports` diff --git a/docs/source/lang/cpp/arithmetic.rst b/docs/source/lang/cpp/arithmetic.rst index cef3954..b7cb5f6 100644 --- a/docs/source/lang/cpp/arithmetic.rst +++ b/docs/source/lang/cpp/arithmetic.rst @@ -110,7 +110,7 @@ types are approximate): ``short``, "0 --- 65,535", "-32,768 --- 32,767", 2 ``int``, "0 --- 4,294,967,295", "-2,147,483,648 --- 2,147,483,647", 4 ``long``, "0 --- 4,294,967,295", "-2,147,483,648 --- 2,147,483,647", 4 - ``long long``, "0 --- 1.8*10\ :sup:`19`\ " (approx.), "-9.2*10\ :sup:`18` --- 9.2*10\ :sup:`18` (approx.)", 8 + ``long long``, "0 --- 1.8*10\ :sup:`19`\ (approx.)", "-9.2*10\ :sup:`18` --- 9.2*10\ :sup:`18` (approx.)", 8 See Also diff --git a/docs/source/libmaple/api/dma.rst b/docs/source/libmaple/api/dma.rst index 286b6d6..4ce298d 100644 --- a/docs/source/libmaple/api/dma.rst +++ b/docs/source/libmaple/api/dma.rst @@ -34,6 +34,10 @@ Devices Functions --------- +.. NB: Some of these functions have multiple definitions, in which case the + complete function signature needs to be specified to disambiguate or breathe + will choke ("Unable to resolve multiple matches for function"...) + .. doxygenfunction:: dma_init .. doxygenfunction:: dma_setup_transfer .. doxygenfunction:: dma_set_num_transfers @@ -43,12 +47,12 @@ Functions .. doxygenfunction:: dma_get_irq_cause .. doxygenfunction:: dma_enable .. doxygenfunction:: dma_disable -.. doxygenfunction:: dma_set_mem_addr +.. doxygenfunction:: dma_set_mem_addr(dma_dev *, dma_tube, __io void *) .. doxygenfunction:: dma_set_per_addr .. doxygendefine:: dma_channel_regs .. doxygendefine:: dma_is_channel_enabled -.. doxygenfunction:: dma_get_isr_bits -.. doxygenfunction:: dma_clear_isr_bits +.. doxygenfunction:: dma_get_isr_bits(dma_dev *, dma_tube) +.. doxygenfunction:: dma_clear_isr_bits(dma_dev *, dma_tube) Register Map Base Pointers -------------------------- diff --git a/docs/source/libmaple/api/gpio.rst b/docs/source/libmaple/api/gpio.rst index 9e8e5c7..5f631d5 100644 --- a/docs/source/libmaple/api/gpio.rst +++ b/docs/source/libmaple/api/gpio.rst @@ -42,14 +42,17 @@ Functions .. doxygenfunction:: gpio_init .. doxygenfunction:: gpio_init_all -.. doxygenfunction:: gpio_set_mode +.. doxygenfunction:: gpio_set_mode(gpio_dev *, uint8, gpio_pin_mode) .. doxygenfunction:: gpio_exti_port .. doxygenfunction:: gpio_write_bit .. doxygenfunction:: gpio_read_bit .. doxygenfunction:: gpio_toggle_bit .. doxygenfunction:: afio_init -.. doxygenfunction:: afio_exti_select + +.. c:macro:: afio_exti_select(exti, port) + + Macro for `exti_select((exti), (port))`. .. _gpio-h-afio-remap: .. doxygenfunction:: afio_remap diff --git a/docs/source/libmaple/api/nvic.rst b/docs/source/libmaple/api/nvic.rst index 505e36e..815da2b 100644 --- a/docs/source/libmaple/api/nvic.rst +++ b/docs/source/libmaple/api/nvic.rst @@ -49,7 +49,7 @@ Functions .. doxygenfunction:: nvic_globalirq_disable .. doxygenfunction:: nvic_irq_enable .. doxygenfunction:: nvic_irq_disable -.. doxygenfunction:: nvic_irq_disable_all +.. doxygenfunction:: nvic_irq_disable_all(void) .. doxygenfunction:: nvic_sys_reset Register Maps diff --git a/docs/source/libmaple/api/util.rst b/docs/source/libmaple/api/util.rst index 54377c0..2f6e080 100644 --- a/docs/source/libmaple/api/util.rst +++ b/docs/source/libmaple/api/util.rst @@ -50,5 +50,5 @@ If an assertion fails, execution is halted at the point of the failed assertion. When libmaple has been configured properly (Wirish performs this configuration by default), the built-in LED throbs in a smooth pattern to signal the failed assertion (using -:c:func:`throb()`), and the file and line where the assert failed are +``throb()``), and the file and line where the assert failed are transmitted to the user as detailed in :ref:`lang-assert`. diff --git a/docs/source/libmaple/overview.rst b/docs/source/libmaple/overview.rst index 006f1d8..4f0db1b 100644 --- a/docs/source/libmaple/overview.rst +++ b/docs/source/libmaple/overview.rst @@ -467,7 +467,7 @@ do a read-modify-write sequence on the DMA_CCR_PL bits like so:: Of course, before doing that, you should check to make sure there's not already a device-level function for performing the same task! (In -this case, there is. It's called :c:func:`dma_set_priority()`; see +this case, there is. It's called ``dma_set_priority()``; see :ref:`libmaple-dma`.) For instance, **none of the above code is portable** to STM32F4, which uses DMA streams instead of channels for this purpose. -- cgit v1.2.3 From c5f25beb3e50939ff61997717960369c1897f90a Mon Sep 17 00:00:00 2001 From: bnewbold Date: Thu, 28 May 2015 00:20:08 -0700 Subject: legacy branch: set docs release to 'legacy' --- docs/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/source/conf.py b/docs/source/conf.py index 247edbf..dc01672 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -61,7 +61,7 @@ copyright = u'2010, 2011, LeafLabs, LLC. 2014 Various Contributors' version = '0.0' # The full version, including alpha/beta/rc tags. # FIXME [RELEASE] update this for the release -release = 'prerelease' +release = 'legacy' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -- cgit v1.2.3 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(-) (limited to 'docs') 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