Merge pull request #3031 from jepler/improve-shared-bindings-links

docs: Improve 5.0.x <-> main branch doc linkrot
author: Scott Shawcroft <scott@adafruit.com> 2020-06-16 11:49:27 -0700
committer: GitHub <noreply@github.com> 2020-06-16 11:49:27 -0700
commit: a345223dac6a58f4437cbbbfc28468ebb4b3237a (patch)
tree: 4d151e7a625fe8da05d3cc8017a3d9e500c1a485
parent: dffac11c2fccb6c0ca859a38f7649e13ccdc9081 (diff)
parent: 7a51719fa287a1a45af6d411c7a698cb6c20aedb (diff)
9 files changed, 149 insertions, 8 deletions
diff --git a/.gitignore b/.gitignore
index f5edb89f0..8a773970d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -53,6 +53,7 @@ _build
 ######################
 genrst/
 /autoapi/
+/shared-bindings/**/*.rst
 
 # ctags and similar
 ###################
diff --git a/conf.py b/conf.py
index 3980ea8e1..38546a5d0 100644
--- a/conf.py
+++ b/conf.py
@@ -14,11 +14,13 @@
 # serve to show the default.
 
 import json
-import sys
+import logging
 import os
+import subprocess
+import sys
+import urllib.parse
 
 import recommonmark
-import subprocess
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -79,6 +81,9 @@ autoapi_add_toctree_entry = False
 autoapi_options = ['members', 'undoc-members', 'private-members', 'show-inheritance', 'special-members', 'show-module-summary']
 autoapi_template_dir = 'docs/autoapi/templates'
 autoapi_python_use_implicit_namespaces = True
+autoapi_root = "shared-bindings"
+
+redirects_file = 'docs/redirects.txt'
 
 # The encoding of source files.
 #source_encoding = 'utf-8-sig'
@@ -374,5 +379,46 @@ intersphinx_mapping = {"cpython": ('https://docs.python.org/3/', None),
                        "bus_device": ('https://circuitpython.readthedocs.io/projects/busdevice/en/latest/', None),
                        "register": ('https://circuitpython.readthedocs.io/projects/register/en/latest/', None)}
 
+# Adapted from sphinxcontrib-redirects
+from sphinx.builders import html as builders
+
+TEMPLATE = """<html>
+  <head><meta http-equiv="refresh" content="0; url=%s"/></head>
+</html>
+"""
+
+
+def generate_redirects(app):
+    path = os.path.join(app.srcdir, app.config.redirects_file)
+    if not os.path.exists(path):
+        app.info("Could not find redirects file at '%s'" % path)
+        return
+
+    if not type(app.builder) == builders.StandaloneHTMLBuilder:
+        logging.warn("The 'sphinxcontib-redirects' plugin is only supported "
+                 "by the 'html' builder. Skipping...")
+        return
+
+    with open(path) as redirects:
+        for line in redirects.readlines():
+            from_path, to_path = line.rstrip().split(' ')
+
+            logging.debug("Redirecting '%s' to '%s'" % (from_path, to_path))
+
+            from_path = os.path.splitext(from_path)[0] + ".html"
+            to_path_prefix = '..%s' % os.path.sep * (
+                len(from_path.split(os.path.sep)) - 1)
+            to_path = to_path_prefix + to_path
+
+            redirected_filename = os.path.join(app.builder.outdir, from_path)
+            redirected_directory = os.path.dirname(redirected_filename)
+            if not os.path.exists(redirected_directory):
+                os.makedirs(redirected_directory)
+
+            with open(redirected_filename, 'w') as f:
+                f.write(TEMPLATE % urllib.parse.quote(to_path, '#/'))
+
 def setup(app):
     app.add_css_file("customstyle.css")
+    app.add_config_value('redirects_file', 'redirects', 'env')
+    app.connect('builder-inited', generate_redirects)
diff --git a/docs/redirects.txt b/docs/redirects.txt
new file mode 100644
index 000000000..68d0b2de2
--- /dev/null
+++ b/docs/redirects.txt
@@ -0,0 +1,94 @@
+shared-bindings/frequencyio/FrequencyIn.rst shared-bindings/frequencyio/#frequencyio.FrequencyIn
+shared-bindings/fontio/BuiltinFont.rst shared-bindings/fontio/#fontio.BuiltinFont
+shared-bindings/fontio/Glyph.rst shared-bindings/fontio/#fontio.Glyph
+shared-bindings/aesio/AES.rst shared-bindings/aesio/#aesio.AES
+shared-bindings/supervisor/Runtime.rst shared-bindings/supervisor/#supervisor.Runtime
+shared-bindings/terminalio/Terminal.rst shared-bindings/terminalio/#terminalio.Terminal
+shared-bindings/audiopwmio/PWMAudioOut.rst shared-bindings/audiopwmio/#audiopwmio.PWMAudioOut
+shared-bindings/gamepadshift/GamePadShift.rst shared-bindings/gamepadshift/#gamepadshift.GamePadShift
+shared-bindings/vectorio/Circle.rst shared-bindings/vectorio/#vectorio.Circle
+shared-bindings/vectorio/Polygon.rst shared-bindings/vectorio/#vectorio.Polygon
+shared-bindings/vectorio/Rectangle.rst shared-bindings/vectorio/#vectorio.Rectangle
+shared-bindings/vectorio/VectorShape.rst shared-bindings/vectorio/#vectorio.VectorShape
+shared-bindings/displayio/Bitmap.rst shared-bindings/displayio/#displayio.Bitmap
+shared-bindings/displayio/ColorConverter.rst shared-bindings/displayio/#displayio.ColorConverter
+shared-bindings/displayio/Display.rst shared-bindings/displayio/#displayio.Display
+shared-bindings/displayio/EPaperDisplay.rst shared-bindings/displayio/#displayio.EPaperDisplay
+shared-bindings/displayio/FourWire.rst shared-bindings/displayio/#displayio.FourWire
+shared-bindings/displayio/Group.rst shared-bindings/displayio/#displayio.Group
+shared-bindings/displayio/I2CDisplay.rst shared-bindings/displayio/#displayio.I2CDisplay
+shared-bindings/displayio/OnDiskBitmap.rst shared-bindings/displayio/#displayio.OnDiskBitmap
+shared-bindings/displayio/Palette.rst shared-bindings/displayio/#displayio.Palette
+shared-bindings/displayio/ParallelBus.rst shared-bindings/displayio/#displayio.ParallelBus
+shared-bindings/displayio/Shape.rst shared-bindings/displayio/#displayio.Shape
+shared-bindings/displayio/TileGrid.rst shared-bindings/displayio/#displayio.TileGrid
+shared-bindings/_pixelbuf/PixelBuf.rst shared-bindings/_pixelbuf/#_pixelbuf.PixelBuf
+shared-bindings/gamepad/GamePad.rst shared-bindings/gamepad/#gamepad.GamePad
+shared-bindings/_pew/PewPew.rst shared-bindings/_pew/#_pew.PewPew
+shared-bindings/rotaryio/IncrementalEncoder.rst shared-bindings/rotaryio/#rotaryio.IncrementalEncoder
+shared-bindings/audiomixer/Mixer.rst shared-bindings/audiomixer/#audiomixer.Mixer
+shared-bindings/audiomixer/MixerVoice.rst shared-bindings/audiomixer/#audiomixer.MixerVoice
+shared-bindings/pulseio/PWMOut.rst shared-bindings/pulseio/#pulseio.PWMOut
+shared-bindings/pulseio/PulseIn.rst shared-bindings/pulseio/#pulseio.PulseIn
+shared-bindings/pulseio/PulseOut.rst shared-bindings/pulseio/#pulseio.PulseOut
+shared-bindings/time/struct_time.rst shared-bindings/time/#time.struct_time
+shared-bindings/i2cslave/I2CSlave.rst shared-bindings/i2cslave/#i2cslave.I2CSlave
+shared-bindings/i2cslave/I2CSlaveRequest.rst shared-bindings/i2cslave/#i2cslave.I2CSlaveRequest
+shared-bindings/nvm/ByteArray.rst shared-bindings/nvm/#nvm.ByteArray
+shared-bindings/busio/I2C.rst shared-bindings/busio/#busio.I2C
+shared-bindings/busio/OneWire.rst shared-bindings/busio/#busio.OneWire
+shared-bindings/busio/SPI.rst shared-bindings/busio/#busio.SPI
+shared-bindings/busio/UART.rst shared-bindings/busio/#busio.UART
+shared-bindings/busio/Parity.rst shared-bindings/busio/#busio.Parity
+shared-bindings/ulab/array.rst shared-bindings/ulab/#ulab.array
+shared-bindings/watchdog/WatchDogMode.rst shared-bindings/watchdog/#watchdog.WatchDogMode
+shared-bindings/watchdog/WatchDogTimer.rst shared-bindings/watchdog/#watchdog.WatchDogTimer
+shared-bindings/audioio/AudioOut.rst shared-bindings/audioio/#audioio.AudioOut
+shared-bindings/ps2io/Ps2.rst shared-bindings/ps2io/#ps2io.Ps2
+shared-bindings/touchio/TouchIn.rst shared-bindings/touchio/#touchio.TouchIn
+shared-bindings/rgbmatrix/RGBMatrix.rst shared-bindings/rgbmatrix/#rgbmatrix.RGBMatrix
+shared-bindings/audiomp3/MP3.rst shared-bindings/audiomp3/#audiomp3.MP3
+shared-bindings/usb_midi/PortIn.rst shared-bindings/usb_midi/#usb_midi.PortIn
+shared-bindings/usb_midi/PortOut.rst shared-bindings/usb_midi/#usb_midi.PortOut
+shared-bindings/usb_hid/Device.rst shared-bindings/usb_hid/#usb_hid.Device
+shared-bindings/wiznet/WIZNET5K.rst shared-bindings/wiznet/#wiznet.WIZNET5K
+shared-bindings/_bleio/BluetoothError.rst shared-bindings/_bleio/#_bleio.BluetoothError
+shared-bindings/_bleio/ConnectionError.rst shared-bindings/_bleio/#_bleio.ConnectionError
+shared-bindings/_bleio/RoleError.rst shared-bindings/_bleio/#_bleio.RoleError
+shared-bindings/_bleio/SecurityError.rst shared-bindings/_bleio/#_bleio.SecurityError
+shared-bindings/_bleio/Adapter.rst shared-bindings/_bleio/#_bleio.Adapter
+shared-bindings/_bleio/Address.rst shared-bindings/_bleio/#_bleio.Address
+shared-bindings/_bleio/Attribute.rst shared-bindings/_bleio/#_bleio.Attribute
+shared-bindings/_bleio/Characteristic.rst shared-bindings/_bleio/#_bleio.Characteristic
+shared-bindings/_bleio/CharacteristicBuffer.rst shared-bindings/_bleio/#_bleio.CharacteristicBuffer
+shared-bindings/_bleio/Connection.rst shared-bindings/_bleio/#_bleio.Connection
+shared-bindings/_bleio/Descriptor.rst shared-bindings/_bleio/#_bleio.Descriptor
+shared-bindings/_bleio/PacketBuffer.rst shared-bindings/_bleio/#_bleio.PacketBuffer
+shared-bindings/_bleio/ScanEntry.rst shared-bindings/_bleio/#_bleio.ScanEntry
+shared-bindings/_bleio/ScanResults.rst shared-bindings/_bleio/#_bleio.ScanResults
+shared-bindings/_bleio/Service.rst shared-bindings/_bleio/#_bleio.Service
+shared-bindings/_bleio/UUID.rst shared-bindings/_bleio/#_bleio.UUID
+shared-bindings/socket/socket.rst shared-bindings/socket/#socket.socket
+shared-bindings/microcontroller/Pin.rst shared-bindings/microcontroller/#microcontroller.Pin
+shared-bindings/microcontroller/Processor.rst shared-bindings/microcontroller/#microcontroller.Processor
+shared-bindings/microcontroller/RunMode.rst shared-bindings/microcontroller/#microcontroller.RunMode
+shared-bindings/audiocore/RawSample.rst shared-bindings/audiocore/#audiocore.RawSample
+shared-bindings/audiocore/WaveFile.rst shared-bindings/audiocore/#audiocore.WaveFile
+shared-bindings/framebufferio/FramebufferDisplay.rst shared-bindings/framebufferio/#framebufferio.FramebufferDisplay
+shared-bindings/audiobusio/I2SOut.rst shared-bindings/audiobusio/#audiobusio.I2SOut
+shared-bindings/audiobusio/PDMIn.rst shared-bindings/audiobusio/#audiobusio.PDMIn
+shared-bindings/countio/Counter.rst shared-bindings/countio/#countio.Counter
+shared-bindings/storage/VfsFat.rst shared-bindings/storage/#storage.VfsFat
+shared-bindings/digitalio/DigitalInOut.rst shared-bindings/digitalio/#digitalio.DigitalInOut
+shared-bindings/digitalio/Direction.rst shared-bindings/digitalio/#digitalio.Direction
+shared-bindings/digitalio/DriveMode.rst shared-bindings/digitalio/#digitalio.DriveMode
+shared-bindings/digitalio/Pull.rst shared-bindings/digitalio/#digitalio.Pull
+shared-bindings/bitbangio/I2C.rst shared-bindings/bitbangio/#bitbangio.I2C
+shared-bindings/bitbangio/OneWire.rst shared-bindings/bitbangio/#bitbangio.OneWire
+shared-bindings/bitbangio/SPI.rst shared-bindings/bitbangio/#bitbangio.SPI
+shared-bindings/rtc/RTC.rst shared-bindings/rtc/#rtc.RTC
+shared-bindings/analogio/AnalogIn.rst shared-bindings/analogio/#analogio.AnalogIn
+shared-bindings/analogio/AnalogOut.rst shared-bindings/analogio/#analogio.AnalogOut
+shared-bindings/_stage/Layer.rst shared-bindings/_stage/#_stage.Layer
+shared-bindings/_stage/Text.rst shared-bindings/_stage/#_stage.Text
+shared-bindings/samd/Clock.rst shared-bindings/samd/#samd.Clock
diff --git a/ports/atmel-samd/README.rst b/ports/atmel-samd/README.rst
index a6881902e..0746d1de0 100644
--- a/ports/atmel-samd/README.rst
+++ b/ports/atmel-samd/README.rst
@@ -21,4 +21,4 @@ Port Specific modules
 ---------------------
 
 .. toctree::
-    ../../autoapi/samd/index
+    ../../shared-bindings/samd/index
diff --git a/shared-bindings/_bleio/Address.c b/shared-bindings/_bleio/Address.c
index ccbab1b9d..9beaff2ab 100644
--- a/shared-bindings/_bleio/Address.c
+++ b/shared-bindings/_bleio/Address.c
@@ -78,7 +78,7 @@ STATIC mp_obj_t bleio_address_make_new(const mp_obj_type_t *type, size_t n_args,
 }
 
 //|     address_bytes: Any = ...
-//|     """The bytes that make up the device address (read-only).
+//|     r"""The bytes that make up the device address (read-only).
 //|
 //|     Note that the ``bytes`` object returned is in little-endian order:
 //|     The least significant byte is ``address_bytes[0]``. So the address will
diff --git a/shared-bindings/displayio/Display.c b/shared-bindings/displayio/Display.c
index 62ef0f5d0..6e454f34b 100644
--- a/shared-bindings/displayio/Display.c
+++ b/shared-bindings/displayio/Display.c
@@ -50,7 +50,7 @@
 //|     contain the initialization sequence at minimum."""
 //|
 //|     def __init__(self, display_bus: Any, init_sequence: buffer, *, width: int, height: int, colstart: int = 0, rowstart: int = 0, rotation: int = 0, color_depth: int = 16, grayscale: bool = False, pixels_in_byte_share_row: bool = True, bytes_per_cell: int = 1, reverse_pixels_in_byte: bool = False, set_column_command: int = 0x2a, set_row_command: int = 0x2b, write_ram_command: int = 0x2c, set_vertical_scroll: int = 0, backlight_pin: microcontroller.Pin = None, brightness_command: int = None, brightness: bool = 1.0, auto_brightness: bool = False, single_byte_bounds: bool = False, data_as_commands: bool = False, auto_refresh: bool = True, native_frames_per_second: int = 60):
-//|         """Create a Display object on the given display bus (`displayio.FourWire` or `displayio.ParallelBus`).
+//|         r"""Create a Display object on the given display bus (`displayio.FourWire` or `displayio.ParallelBus`).
 //|
 //|         The ``init_sequence`` is bitpacked to minimize the ram impact. Every command begins with a
 //|         command byte followed by a byte to determine the parameter count and if a delay is need after.
diff --git a/shared-bindings/displayio/Palette.c b/shared-bindings/displayio/Palette.c
index 871b2b06a..37cfbd82e 100644
--- a/shared-bindings/displayio/Palette.c
+++ b/shared-bindings/displayio/Palette.c
@@ -85,7 +85,7 @@ STATIC mp_obj_t group_unary_op(mp_unary_op_t op, mp_obj_t self_in) {
 }
 
 //|     def __setitem__(self, index: Any, value: Any) -> Any:
-//|         """Sets the pixel color at the given index. The index should be an integer in the range 0 to color_count-1.
+//|         r"""Sets the pixel color at the given index. The index should be an integer in the range 0 to color_count-1.
 //|
 //|         The value argument represents a color, and can be from 0x000000 to 0xFFFFFF (to represent an RGB value).
 //|         Value can be an int, bytes (3 bytes (RGB) or 4 bytes (RGB + pad byte)), bytearray,
diff --git a/shared-bindings/index.rst b/shared-bindings/index.rst
index d94177394..bf04ae18b 100644
--- a/shared-bindings/index.rst
+++ b/shared-bindings/index.rst
@@ -19,5 +19,5 @@ Modules
     :glob:
     :maxdepth: 2
 
-    ../autoapi/*/index
+    ../shared-bindings/*/index
     help
diff --git a/shared-bindings/nvm/ByteArray.c b/shared-bindings/nvm/ByteArray.c
index 326f719a8..06d7d4c95 100644
--- a/shared-bindings/nvm/ByteArray.c
+++ b/shared-bindings/nvm/ByteArray.c
@@ -32,7 +32,7 @@
 #include "supervisor/shared/translate.h"
 
 //| class ByteArray:
-//|     """Presents a stretch of non-volatile memory as a bytearray.
+//|     r"""Presents a stretch of non-volatile memory as a bytearray.
 //|
 //|     Non-volatile memory is available as a byte array that persists over reloads
 //|     and power cycles. Each assignment causes an erase and write cycle so its recommended to assign
author	Scott Shawcroft <scott@adafruit.com>	2020-06-16 11:49:27 -0700
committer	GitHub <noreply@github.com>	2020-06-16 11:49:27 -0700
commit	a345223dac6a58f4437cbbbfc28468ebb4b3237a (patch)
tree	4d151e7a625fe8da05d3cc8017a3d9e500c1a485
parent	dffac11c2fccb6c0ca859a38f7649e13ccdc9081 (diff)
parent	7a51719fa287a1a45af6d411c7a698cb6c20aedb (diff)