Clean up documentation

earlephilhower · Apr 6, 2021 · 735c14a · 735c14a
1 parent 952f04d
commit 735c14a
Show file tree

Hide file tree

Showing 15 changed files with 105 additions and 100 deletions.
diff --git a/docs/analog.rst b/docs/analog.rst
@@ -9,12 +9,12 @@ The standard Arduino calls can be used to read their values (with
 3.3V nominally reading as 4095).
 
 int analogRead(pin_size_t pin = A0..A3)
----------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Returns a value from 0...4095 correspionding to the ADC reading
 of the specific pin.
 
 float analogReadTemp()
-----------------------
+~~~~~~~~~~~~~~~~~~~~~~
 Returns the temperature, in Celsius, of the onboard thermal sensor.
 This reading is not exceedingly accurate and of relatively low
 resolution, so it is not a replacement for an external temperature
@@ -28,23 +28,21 @@ simulated using the standard method of using pulse width modulation
 
 While up to 16 PWM channels can be generated, they are not independent
 and there are significant restrictions as to allowed pins in parallel.
-See the [RP2040 datasheet](https://datasheets.raspberrypi.org/rp2040/rp2040-datasheet.pdf)
-for full details.
+See the `RP2040 datasheet <https://datasheets.raspberrypi.org/rp2040/rp2040-datasheet.pdf>`_ for full details.
 
 void analogWriteFreq(uint32_t freq)
------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Sets the master PWM frequency used (i.e. how often the PWM output cycles).
 From 100Hz to 60KHz are supported.
-}
 
 void analogWriteRange(uint32_t range) and analogWriteResolution(int res)
-------------------------------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 These calls set the maximum PWM value (i.e. writing this value will result in
 a PWM duty cycle of 100%)/ either explicitly (range) or as a power-of-two
 (res).  A range of 16 to 65535 is supported.
 
 void analogWrite(pin_size_t pin, int val)
------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Writes a PWM value to a specific pin.  The PWM machine is enabled and set to
 the requested frequency and scale, and the output is generated.  This will
-continue until a `digitalWrite` or other digital output is performed.
+continue until a ``digitalWrite`` or other digital output is performed.
diff --git a/docs/digital.rst b/docs/digital.rst
@@ -1,6 +1,14 @@
 Digital I/O
 ===========
 
+Board-Specific Pins
+-------------------
 The Raspberry Pi Pico RP2040 chip supports up to 30 digital I/O pins,
 however not all boards provide access to all pins.
 
+Tone/noTone
+-----------
+Simple square wave tone generation is possible for up to 8 channels using
+Arduino standard ``tone`` calls.  Because these use the PIO to generate the
+waveform, they must share resources with other calls such as ``I2S`` or
+``Servo`` objects.
diff --git a/docs/eeprom.rst b/docs/eeprom.rst
@@ -9,47 +9,50 @@ writes as the onboard flash chip, not the 100,000 or so of a real EEPROM.**
 Therefore, do not frequently update the EEPROM or you may prematurely wear
 out the flash.
 
+EEPROM Class API
+----------------
+
 EEPROM.begin(size=256...4096)
------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Call before the first use of the EEPROM data for read or write.  It makes a
 copy of the emulated EEPROM sector in RAM to allow random update and access.
 
 EEPROM.read(addr), EEPROM[addr]
--------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Returns the data at a specific offset in the EEPROM. See `EEPROM.get` later
 for a more 
 
 EEPROM.write(addr, data), EEPROM[addr] = data
----------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Writes a byte of data at the offset specified.  Not persisted to flash until
-`EEPROM.commit()` is called.
+``EEPROM.commit()`` is called.
 
 EEPROM.commit()
----------------
+~~~~~~~~~~~~~~~
 Writes the updated data to flash, so next reboot it will be readable.
 
 EEPROM.end()
-------------
-`EEPROM.commit()` and frees all memory used.  Need to call `EEPROM.begin()`
+~~~~~~~~~~~~
+``EEPROM.commit()`` and frees all memory used.  Need to call `EEPROM.begin()`
 before the EEPROM can be used again.
 
 EEPROM.get(addr, val)
----------------------
+~~~~~~~~~~~~~~~~~~~~~
 Copies the (potentially multi-byte) data in EEPROM at the specific byte
 offset into the returned value.  Useful for reading structures from EEPROM.
 
 EEPROM.put(addr, val)
----------------------
+~~~~~~~~~~~~~~~~~~~~~
 Copies the (potentially multi-byte) value into EEPROM a the byte offset
-supplied.  Useful for storing `struct` in EEPROM.  Note that any pointers
+supplied.  Useful for storing ``struct`` in EEPROM.  Note that any pointers
 inside a written structure will not be valid, and that most C++ objects
-like `String` cannot be written to EEPROM this way because of it.
+like ``String`` cannot be written to EEPROM this way because of it.
 
 EEPROM.length()
----------------
+~~~~~~~~~~~~~~~
 Returns the length of the EEPROM (i.e. the value specified in
-`EEPROM.begin()` ).
+``EEPROM.begin()`` ).
 
 EEPROM Examples
 ---------------
-Three EEPROM [examples](https://github.com/earlephilhower/arduino-pico/tree/master/libraries/EEPROM) are included.
+Three EEPROM `examples<https://github.com/earlephilhower/arduino-pico/tree/master/libraries/EEPROM>`_ are included.
diff --git a/docs/i2s.rst b/docs/i2s.rst
@@ -5,83 +5,85 @@ While the RP2040 chip on the Raspberry Pi Pico does not include a hardware
 I2S device, it is possible to use the PIO (Programmable I/O) state machines
 to implement one dynamically.
 
-This I2S library uses the `pico-extras` I2S audio library and wraps it in
+This I2S library uses the ``pico-extras`` I2S audio library and wraps it in
 an Arduino I2S library.  It supports 16 bits/sample and frequencies of up
 to 48kHZ, with configurable BCLK, LRCLK(always pin "BCLK + 1"), and DOUT pins.
 
 **Note:** This I2S device takes over the entire PIO1 (second) unit and adjusts
 its clock frequency to meet the I2S needs.  That means when only 4 Tones
 or only 4 Servos may be used when the I2S device is used.
 
+I2S Class API
+-------------
+
 bool setBCLK(pin_size_t pin)
-----------------------------
-Sets the BCLK pin of the I2S device.  The LRCLK/word clock will be `pin + 1`
-due to limitations of the PIO state machines.  Call this before `I2S.begin()`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Sets the BCLK pin of the I2S device.  The LRCLK/word clock will be ``pin + 1``
+due to limitations of the PIO state machines.  Call this before ``I2S.begin()``
 Default BCLK = 26, LRCLK = 27
 
 bool setDOUT(pin_size_t pin)
-----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Sets the DOUT pin of the I2S device.  Any pin may be used.  Default DOUT = 28
-Call before `I2S.begin()`
+Call before ``I2S.begin()``
 
 bool begin(long sampleRate)
----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Start the I2S device up with the given sample rate.  The pins selected above
 will be turned to output and the I2S will begin to drive silence frames (all
 zero) out.
 
 void end()
-----------
+~~~~~~~~~~
 Stops the I2S device.  **Note, at present the memory allocated for I2S buffers
-is not freed leading to a memory leak when `end()` is called.  This is due
-to the state of the `pico-extras` release from thich this device came.**
+is not freed leading to a memory leak when ``end()`` is called.  This is due
+to the state of the ``pico-extras`` release which this code uses.**
 
 void flush()
-------------
+~~~~~~~~~~~~
 Sends any partial frames in memory to the I2S output device.  They may NOT play
 immediately.  Potential use case for this call would be when the frequency of
 the output will be changing.
 
 size_t write(uint8_t)
----------------------
+~~~~~~~~~~~~~~~~~~~~~
 Provided for compatibilty, but not very useful.  Writes a sample from 0...255
-to the I2S buffer.  See `write(int16_t)` for a better one
+to the I2S buffer.  See ``write(int16_t)`` for a better one
 
 size_t write(const uint8_t \*buffer, size_t size)
--------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Transfers number of bytes from an application buffer to the I2S output buffer.
-Be aware that `size` is in *bytes** and not samples.  Size must be a multiple
+Be aware that ``size`` is in *bytes** and not samples.  Size must be a multiple
 of **4 bytes** (i.e. one left/right sample).  Will not block, so check
 the return value to find out how many bytes were actually written.
 
 int availableForWrite()
------------------------
+~~~~~~~~~~~~~~~~~~~~~~~
 Returns the number of **32-bit L/R samples** that can be written without
 potentially blocking.
 
 bool setFrequency(int newFreq)
-------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Adjusts the I2S output frequency.  When changing frequency while I2S output
-is underway, be sure to use `I2S.flush()` before changing the frequency to
+is underway, be sure to use ``I2S.flush()`` before changing the frequency to
 ensure the older data is played at the right frequency.
 
-
 size_t write(int16_t)
----------------------
+~~~~~~~~~~~~~~~~~~~~~
 Writes a single 16-bit left or right sample to the I2S output buffer.  The
 user is required to ensure that an even number of samples is written (i.e.
 left and right) over the application lifetime.  The application also needs
 to track which sample is next to be written (right/left).  For this reason,
-the `write(void *b, size_t lrsamples)` call may be easier and faster to use.
+the ``write(void *b, size_t lrsamples)`` call may be easier and faster to use.
 
 size_t write(const void \*buffer, size_t lrsamples)
----------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Writes up to size left+right packed samples to the I2S device.  Non-blocking,
 will writefrom 0...size samples and return that count.  Be sure your app
-handles partial writes (i.e. by yield()ing and then retrying to write the
+handles partial writes (i.e. by ``yield()`` ing and then retrying to write the
 remaining data.)
 
-The `onTransmit` callback is not supported.
+The ``onTransmit`` callback is not supported.
 
-See the [ESP8266Audio](https://github.com/earlephilhower/ESP8266Audio) library
+See the `ESP8266Audio <https://github.com/earlephilhower/ESP8266Audio>`_ library
 for a working example, or look at the included sample tone generator.
diff --git a/docs/index.md b/docs/index.md
@@ -1 +1,4 @@
 ## Welcome to Arduino-Pico
+
+Please go to https://arduino-pico.readthedocs.io/en/latest/ for the
+latest documentation.
diff --git a/docs/index.rst b/docs/index.rst
@@ -18,7 +18,7 @@ For the latest version, always check https://github.com/earlephilhower/arduino-p
 
    Getting Help and Contributing <help>
    Installation <install>
-   Using the IDE <ide>
+   IDE Menus <ide>
 
    Pin (Re)Assignment <pins>
 
@@ -37,10 +37,3 @@ For the latest version, always check https://github.com/earlephilhower/arduino-p
    Using Pico-SDK <sdk>
 
    Licenses <license>
-
-Indices and Tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
diff --git a/docs/install.rst b/docs/install.rst
@@ -48,7 +48,7 @@ To install via GIT (for latest and greatest versions):
 Installing both Arduino and CMake
 ---------------------------------
 Tom's Hardware presented a very nice writeup on installing `arduino-pico` on
-both Windows and Linux, available at [Tom's Hardware](https://www.tomshardware.com/how-to/program-raspberry-pi-pico-with-arduino-ide)
+both Windows and Linux, available at `Tom's Hardware <https://www.tomshardware.com/how-to/program-raspberry-pi-pico-with-arduino-ide>`_ .
 
 If you follow their step-by-step you will also have a fully functional
 `CMake`-based environment to build Pico apps on if you outgrow the Arduino

diff --git a/docs/libraries.rst b/docs/libraries.rst
@@ -1,4 +1,4 @@
-Libraries Ported/Optimizef for the RP2040
+Libraries Ported/Optimized for the RP2040
 =========================================
 
 Most Arduino libraries that work on modern 32-bit CPU based Arduino boards
@@ -8,6 +8,6 @@ The following libraries have undergone additional porting and optimizations
 specifically for the RP2040 and you should consider using them instead of
 the generic versions available in the Library Manager
 
-* [Adafruit GFX Library](https://github.com/Bodmer/Adafruit-GFX-Library) by @Bodmer, 2-20x faster than the standard version on the Pico
-* [Adafruit ILI9341 Library](https://github.com/Bodmer/Adafruit_ILI9341), again by @Bodmer
-* [ESP8266Audio](https://github.com/earlephilhower/ESP8266Audio), ported to use the included `I2S` library
+* `Adafruit GFX Library <https://github.com/Bodmer/Adafruit-GFX-Library>`_ by @Bodmer, 2-20x faster than the standard version on the Pico
+* `Adafruit ILI9341 Library <https://github.com/Bodmer/Adafruit_ILI9341>`_ again by @Bodmer
+* `ESP8266Audio <https://github.com/earlephilhower/ESP8266Audio>_` ported to use the included ``I2S`` library
diff --git a/docs/license.rst b/docs/license.rst
@@ -5,10 +5,10 @@ Arduino-Pico is licensed under the LGPL license as detailed in the included READ
 
 In addition, it contains code from additional open source projects:
 
-* The [Arduino IDE and ArduinoCore-API](https://arduino.cc) are developed and maintained by the Arduino team. The IDE is licensed under GPL.
-* The [RP2040 GCC-based toolchain](https://github.com/earlephilhower/pico-quick-toolchain) is licensed under under the GPL.
-* The [Pico-SDK](https://github.com/raspberrypi/pico-sdk) and [Pico-Extras](https://github.com/raspberrypi/pico-extras) are by Raspberry Pi (Trading) Ltd and licensed under the BSD 3-Clause license.
-* [Arduino-Pico](https://github.com/earlephilhower/arduino-pico) core files are licenses under the LGPL.
-* [LittleFS](https://github.com/ARMmbed/littlefs) library written by ARM Limited and released under the [BSD 3-clause license](https://github.com/ARMmbed/littlefs/blob/master/LICENSE.md).
-* [UF2CONV.PY](https://github.com/microsoft/uf2) is by Microsoft Corporatio and licensed under the MIT license.
-* Some filesystem code taken from the [ESP8266 Arduino Core](https://github.com/esp8266/Arduino) and licensed under the LGPL.
+* The `Arduino IDE and ArduinoCore-API <https://arduino.cc>`_ are developed and maintained by the Arduino team. The IDE is licensed under GPL.
+* The `RP2040 GCC-based toolchain <https://github.com/earlephilhower/pico-quick-toolchain>`_ is licensed under under the GPL.
+* The `Pico-SDK <https://github.com/raspberrypi/pico-sdk>`_ and `Pico-Extras <https://github.com/raspberrypi/pico-extras>`_ are by Raspberry Pi (Trading) Ltd. and licensed under the BSD 3-Clause license.
+* `Arduino-Pico <https://github.com/earlephilhower/arduino-pico>`_ core files are licenses under the LGPL.
+* `LittleFS <https://github.com/ARMmbed/littlefs>`_ library written by ARM Limited and released under the `BSD 3-clause license <https://github.com/ARMmbed/littlefs/blob/master/LICENSE.md>`_ .
+* `UF2CONV.PY <https://github.com/microsoft/uf2>`_ is by Microsoft Corporatio and licensed under the MIT license.
+* Some filesystem code taken from the `ESP8266 Arduino Core <https://github.com/esp8266/Arduino>`_ and licensed under the LGPL.
diff --git a/docs/pins.rst b/docs/pins.rst
@@ -11,33 +11,33 @@ I/O pins **before calling ::begin**.  This is especially helpful when
 using third party libraries:  the library doesn't need to be modified,
 only your own code in `setup()` is needed to adjust pinouts.
 
-I2S:
-----
+I2S
+---
 
 .. code:: cpp
 
         ::setBCLK(pin)
         ::setDOUT(pin)
 
-Serial1 (UART0), Serial2 (UART1):
----------------------------------
+Serial1 (UART0), Serial2 (UART1)
+--------------------------------
 
 .. code:: cpp
 
         ::setRX(pin)
         ::setTX(pin)
 
-SPI (SPI0), SPI1 (SPI1):
-------------------------
+SPI (SPI0), SPI1 (SPI1)
+-----------------------
 
 .. code:: cpp
 
         ::setSCK(pin)
         ::setRX(pin)
         ::setTX(pin)
 
-Wire (I2C0), Wire1 (I2C1):
---------------------------
+Wire (I2C0), Wire1 (I2C1)
+-------------------------
 
 .. code:: cpp
 

diff --git a/docs/sdk.rst b/docs/sdk.rst
@@ -1,7 +1,7 @@
 Using the Raspberry Pi Pico SDK (PICO-SDK)
 ==========================================
 
-A complete copy of the [Raspberry Pi Pico SDK](https://datasheets.raspberrypi.org/pico/raspberry-pi-pico-c-sdk.pdf)
+A complete copy of the `Raspberry Pi Pico SDK <https://datasheets.raspberrypi.org/pico/raspberry-pi-pico-c-sdk.pdf>`_
 is included with the Arduino core, and all functions in the core are available
 inside the standard link libraries.
 

diff --git a/docs/serial.rst b/docs/serial.rst
@@ -5,23 +5,24 @@ The Arduino-Pico core implements a software-based Serial-over-USB port
 using the USB ACM-CDC model to support a wide variety of operating
 systems.
 
-`Serial` is the USB serial port, and while `Serial.begin()` doea allow
+``Serial`` is the USB serial port, and while ``Serial.begin()`` does allow
 specifying a baud rate, this rate is ignored since it is USB-based.
-(Also be aware that this USB `Serial` port is responsible for resetting
+(Also be aware that this USB ``Serial`` port is responsible for resetting
 the RP2040 during the upload process, following the Arduino standard
 of 1200bps = reset to bootloader).
 
 The RP2040 provides two hardware-based UARTS with configurable
 pin selection.
 
-`Serial1` is UART0, and `Serial2` is UART1.
+``Serial1`` is ``UART0``, and ``Serial2`` is ``UART1``.
+
+Configure their pins using the ``setXXX`` calls prior to calling ``begin()``
 
-Configure their pins using the `setXXX` calls prior to calling `begin()`
 .. code:: cpp
 
         Serial1.setRX(pin);
         Serial1.setTX(pin);
         Serial1.begin(baud);
 
 For detailed information about the Serial ports, see the
-Arduino [Serial reference](https://www.arduino.cc/reference/en/language/functions/communication/serial/)
+Arduino `Serial Reference <https://www.arduino.cc/reference/en/language/functions/communication/serial/>`_ .