Skip to content

Commit a345223

Browse files
tannewttannewt
authored
Merge pull request #3031 from jepler/improve-shared-bindings-links
docs: Improve 5.0.x <-> main branch doc linkrot
2 parents dffac11 + 7a51719 commit a345223

File tree

9 files changed

+149
-8
lines changed

9 files changed

+149
-8
lines changed

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,7 @@ _build
5353
######################
5454
genrst/
5555
/autoapi/
56+
/shared-bindings/**/*.rst
5657

5758
# ctags and similar
5859
###################

‎conf.py

Lines changed: 48 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,11 +14,13 @@
1414
# serve to show the default.
1515

1616
import json
17-
import sys
17+
import logging
1818
import os
19+
import subprocess
20+
import sys
21+
import urllib.parse
1922

2023
import recommonmark
21-
import subprocess
2224

2325
# If extensions (or modules to document with autodoc) are in another directory,
2426
# add these directories to sys.path here. If the directory is relative to the
@@ -79,6 +81,9 @@
7981
autoapi_options = ['members', 'undoc-members', 'private-members', 'show-inheritance', 'special-members', 'show-module-summary']
8082
autoapi_template_dir = 'docs/autoapi/templates'
8183
autoapi_python_use_implicit_namespaces = True
84+
autoapi_root = "shared-bindings"
85+
86+
redirects_file = 'docs/redirects.txt'
8287

8388
# The encoding of source files.
8489
#source_encoding = 'utf-8-sig'
@@ -374,5 +379,46 @@
374379
"bus_device": ('https://circuitpython.readthedocs.io/projects/busdevice/en/latest/', None),
375380
"register": ('https://circuitpython.readthedocs.io/projects/register/en/latest/', None)}
376381

382+
# Adapted from sphinxcontrib-redirects
383+
from sphinx.builders import html as builders
384+
385+
TEMPLATE = """<html>
386+
<head><meta http-equiv="refresh" content="0; url=%s"/></head>
387+
</html>
388+
"""
389+
390+
391+
def generate_redirects(app):
392+
path = os.path.join(app.srcdir, app.config.redirects_file)
393+
if not os.path.exists(path):
394+
app.info("Could not find redirects file at '%s'" % path)
395+
return
396+
397+
if not type(app.builder) == builders.StandaloneHTMLBuilder:
398+
logging.warn("The 'sphinxcontib-redirects' plugin is only supported "
399+
"by the 'html' builder. Skipping...")
400+
return
401+
402+
with open(path) as redirects:
403+
for line in redirects.readlines():
404+
from_path, to_path = line.rstrip().split(' ')
405+
406+
logging.debug("Redirecting '%s' to '%s'" % (from_path, to_path))
407+
408+
from_path = os.path.splitext(from_path)[0] + ".html"
409+
to_path_prefix = '..%s' % os.path.sep * (
410+
len(from_path.split(os.path.sep)) - 1)
411+
to_path = to_path_prefix + to_path
412+
413+
redirected_filename = os.path.join(app.builder.outdir, from_path)
414+
redirected_directory = os.path.dirname(redirected_filename)
415+
if not os.path.exists(redirected_directory):
416+
os.makedirs(redirected_directory)
417+
418+
with open(redirected_filename, 'w') as f:
419+
f.write(TEMPLATE % urllib.parse.quote(to_path, '#/'))
420+
377421
def setup(app):
378422
app.add_css_file("customstyle.css")
423+
app.add_config_value('redirects_file', 'redirects', 'env')
424+
app.connect('builder-inited', generate_redirects)

‎docs/redirects.txt

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
shared-bindings/frequencyio/FrequencyIn.rst shared-bindings/frequencyio/#frequencyio.FrequencyIn
2+
shared-bindings/fontio/BuiltinFont.rst shared-bindings/fontio/#fontio.BuiltinFont
3+
shared-bindings/fontio/Glyph.rst shared-bindings/fontio/#fontio.Glyph
4+
shared-bindings/aesio/AES.rst shared-bindings/aesio/#aesio.AES
5+
shared-bindings/supervisor/Runtime.rst shared-bindings/supervisor/#supervisor.Runtime
6+
shared-bindings/terminalio/Terminal.rst shared-bindings/terminalio/#terminalio.Terminal
7+
shared-bindings/audiopwmio/PWMAudioOut.rst shared-bindings/audiopwmio/#audiopwmio.PWMAudioOut
8+
shared-bindings/gamepadshift/GamePadShift.rst shared-bindings/gamepadshift/#gamepadshift.GamePadShift
9+
shared-bindings/vectorio/Circle.rst shared-bindings/vectorio/#vectorio.Circle
10+
shared-bindings/vectorio/Polygon.rst shared-bindings/vectorio/#vectorio.Polygon
11+
shared-bindings/vectorio/Rectangle.rst shared-bindings/vectorio/#vectorio.Rectangle
12+
shared-bindings/vectorio/VectorShape.rst shared-bindings/vectorio/#vectorio.VectorShape
13+
shared-bindings/displayio/Bitmap.rst shared-bindings/displayio/#displayio.Bitmap
14+
shared-bindings/displayio/ColorConverter.rst shared-bindings/displayio/#displayio.ColorConverter
15+
shared-bindings/displayio/Display.rst shared-bindings/displayio/#displayio.Display
16+
shared-bindings/displayio/EPaperDisplay.rst shared-bindings/displayio/#displayio.EPaperDisplay
17+
shared-bindings/displayio/FourWire.rst shared-bindings/displayio/#displayio.FourWire
18+
shared-bindings/displayio/Group.rst shared-bindings/displayio/#displayio.Group
19+
shared-bindings/displayio/I2CDisplay.rst shared-bindings/displayio/#displayio.I2CDisplay
20+
shared-bindings/displayio/OnDiskBitmap.rst shared-bindings/displayio/#displayio.OnDiskBitmap
21+
shared-bindings/displayio/Palette.rst shared-bindings/displayio/#displayio.Palette
22+
shared-bindings/displayio/ParallelBus.rst shared-bindings/displayio/#displayio.ParallelBus
23+
shared-bindings/displayio/Shape.rst shared-bindings/displayio/#displayio.Shape
24+
shared-bindings/displayio/TileGrid.rst shared-bindings/displayio/#displayio.TileGrid
25+
shared-bindings/_pixelbuf/PixelBuf.rst shared-bindings/_pixelbuf/#_pixelbuf.PixelBuf
26+
shared-bindings/gamepad/GamePad.rst shared-bindings/gamepad/#gamepad.GamePad
27+
shared-bindings/_pew/PewPew.rst shared-bindings/_pew/#_pew.PewPew
28+
shared-bindings/rotaryio/IncrementalEncoder.rst shared-bindings/rotaryio/#rotaryio.IncrementalEncoder
29+
shared-bindings/audiomixer/Mixer.rst shared-bindings/audiomixer/#audiomixer.Mixer
30+
shared-bindings/audiomixer/MixerVoice.rst shared-bindings/audiomixer/#audiomixer.MixerVoice
31+
shared-bindings/pulseio/PWMOut.rst shared-bindings/pulseio/#pulseio.PWMOut
32+
shared-bindings/pulseio/PulseIn.rst shared-bindings/pulseio/#pulseio.PulseIn
33+
shared-bindings/pulseio/PulseOut.rst shared-bindings/pulseio/#pulseio.PulseOut
34+
shared-bindings/time/struct_time.rst shared-bindings/time/#time.struct_time
35+
shared-bindings/i2cslave/I2CSlave.rst shared-bindings/i2cslave/#i2cslave.I2CSlave
36+
shared-bindings/i2cslave/I2CSlaveRequest.rst shared-bindings/i2cslave/#i2cslave.I2CSlaveRequest
37+
shared-bindings/nvm/ByteArray.rst shared-bindings/nvm/#nvm.ByteArray
38+
shared-bindings/busio/I2C.rst shared-bindings/busio/#busio.I2C
39+
shared-bindings/busio/OneWire.rst shared-bindings/busio/#busio.OneWire
40+
shared-bindings/busio/SPI.rst shared-bindings/busio/#busio.SPI
41+
shared-bindings/busio/UART.rst shared-bindings/busio/#busio.UART
42+
shared-bindings/busio/Parity.rst shared-bindings/busio/#busio.Parity
43+
shared-bindings/ulab/array.rst shared-bindings/ulab/#ulab.array
44+
shared-bindings/watchdog/WatchDogMode.rst shared-bindings/watchdog/#watchdog.WatchDogMode
45+
shared-bindings/watchdog/WatchDogTimer.rst shared-bindings/watchdog/#watchdog.WatchDogTimer
46+
shared-bindings/audioio/AudioOut.rst shared-bindings/audioio/#audioio.AudioOut
47+
shared-bindings/ps2io/Ps2.rst shared-bindings/ps2io/#ps2io.Ps2
48+
shared-bindings/touchio/TouchIn.rst shared-bindings/touchio/#touchio.TouchIn
49+
shared-bindings/rgbmatrix/RGBMatrix.rst shared-bindings/rgbmatrix/#rgbmatrix.RGBMatrix
50+
shared-bindings/audiomp3/MP3.rst shared-bindings/audiomp3/#audiomp3.MP3
51+
shared-bindings/usb_midi/PortIn.rst shared-bindings/usb_midi/#usb_midi.PortIn
52+
shared-bindings/usb_midi/PortOut.rst shared-bindings/usb_midi/#usb_midi.PortOut
53+
shared-bindings/usb_hid/Device.rst shared-bindings/usb_hid/#usb_hid.Device
54+
shared-bindings/wiznet/WIZNET5K.rst shared-bindings/wiznet/#wiznet.WIZNET5K
55+
shared-bindings/_bleio/BluetoothError.rst shared-bindings/_bleio/#_bleio.BluetoothError
56+
shared-bindings/_bleio/ConnectionError.rst shared-bindings/_bleio/#_bleio.ConnectionError
57+
shared-bindings/_bleio/RoleError.rst shared-bindings/_bleio/#_bleio.RoleError
58+
shared-bindings/_bleio/SecurityError.rst shared-bindings/_bleio/#_bleio.SecurityError
59+
shared-bindings/_bleio/Adapter.rst shared-bindings/_bleio/#_bleio.Adapter
60+
shared-bindings/_bleio/Address.rst shared-bindings/_bleio/#_bleio.Address
61+
shared-bindings/_bleio/Attribute.rst shared-bindings/_bleio/#_bleio.Attribute
62+
shared-bindings/_bleio/Characteristic.rst shared-bindings/_bleio/#_bleio.Characteristic
63+
shared-bindings/_bleio/CharacteristicBuffer.rst shared-bindings/_bleio/#_bleio.CharacteristicBuffer
64+
shared-bindings/_bleio/Connection.rst shared-bindings/_bleio/#_bleio.Connection
65+
shared-bindings/_bleio/Descriptor.rst shared-bindings/_bleio/#_bleio.Descriptor
66+
shared-bindings/_bleio/PacketBuffer.rst shared-bindings/_bleio/#_bleio.PacketBuffer
67+
shared-bindings/_bleio/ScanEntry.rst shared-bindings/_bleio/#_bleio.ScanEntry
68+
shared-bindings/_bleio/ScanResults.rst shared-bindings/_bleio/#_bleio.ScanResults
69+
shared-bindings/_bleio/Service.rst shared-bindings/_bleio/#_bleio.Service
70+
shared-bindings/_bleio/UUID.rst shared-bindings/_bleio/#_bleio.UUID
71+
shared-bindings/socket/socket.rst shared-bindings/socket/#socket.socket
72+
shared-bindings/microcontroller/Pin.rst shared-bindings/microcontroller/#microcontroller.Pin
73+
shared-bindings/microcontroller/Processor.rst shared-bindings/microcontroller/#microcontroller.Processor
74+
shared-bindings/microcontroller/RunMode.rst shared-bindings/microcontroller/#microcontroller.RunMode
75+
shared-bindings/audiocore/RawSample.rst shared-bindings/audiocore/#audiocore.RawSample
76+
shared-bindings/audiocore/WaveFile.rst shared-bindings/audiocore/#audiocore.WaveFile
77+
shared-bindings/framebufferio/FramebufferDisplay.rst shared-bindings/framebufferio/#framebufferio.FramebufferDisplay
78+
shared-bindings/audiobusio/I2SOut.rst shared-bindings/audiobusio/#audiobusio.I2SOut
79+
shared-bindings/audiobusio/PDMIn.rst shared-bindings/audiobusio/#audiobusio.PDMIn
80+
shared-bindings/countio/Counter.rst shared-bindings/countio/#countio.Counter
81+
shared-bindings/storage/VfsFat.rst shared-bindings/storage/#storage.VfsFat
82+
shared-bindings/digitalio/DigitalInOut.rst shared-bindings/digitalio/#digitalio.DigitalInOut
83+
shared-bindings/digitalio/Direction.rst shared-bindings/digitalio/#digitalio.Direction
84+
shared-bindings/digitalio/DriveMode.rst shared-bindings/digitalio/#digitalio.DriveMode
85+
shared-bindings/digitalio/Pull.rst shared-bindings/digitalio/#digitalio.Pull
86+
shared-bindings/bitbangio/I2C.rst shared-bindings/bitbangio/#bitbangio.I2C
87+
shared-bindings/bitbangio/OneWire.rst shared-bindings/bitbangio/#bitbangio.OneWire
88+
shared-bindings/bitbangio/SPI.rst shared-bindings/bitbangio/#bitbangio.SPI
89+
shared-bindings/rtc/RTC.rst shared-bindings/rtc/#rtc.RTC
90+
shared-bindings/analogio/AnalogIn.rst shared-bindings/analogio/#analogio.AnalogIn
91+
shared-bindings/analogio/AnalogOut.rst shared-bindings/analogio/#analogio.AnalogOut
92+
shared-bindings/_stage/Layer.rst shared-bindings/_stage/#_stage.Layer
93+
shared-bindings/_stage/Text.rst shared-bindings/_stage/#_stage.Text
94+
shared-bindings/samd/Clock.rst shared-bindings/samd/#samd.Clock

‎ports/atmel-samd/README.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,4 +21,4 @@ Port Specific modules
2121
---------------------
2222

2323
.. toctree::
24-
../../autoapi/samd/index
24+
../../shared-bindings/samd/index

‎shared-bindings/_bleio/Address.c

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -78,7 +78,7 @@ STATIC mp_obj_t bleio_address_make_new(const mp_obj_type_t *type, size_t n_args,
7878
}
7979

8080
//| address_bytes: Any = ...
81-
//| """The bytes that make up the device address (read-only).
81+
//| r"""The bytes that make up the device address (read-only).
8282
//|
8383
//| Note that the ``bytes`` object returned is in little-endian order:
8484
//| The least significant byte is ``address_bytes[0]``. So the address will

‎shared-bindings/displayio/Display.c

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@
5050
//| contain the initialization sequence at minimum."""
5151
//|
5252
//| 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):
53-
//| """Create a Display object on the given display bus (`displayio.FourWire` or `displayio.ParallelBus`).
53+
//| r"""Create a Display object on the given display bus (`displayio.FourWire` or `displayio.ParallelBus`).
5454
//|
5555
//| The ``init_sequence`` is bitpacked to minimize the ram impact. Every command begins with a
5656
//| command byte followed by a byte to determine the parameter count and if a delay is need after.

‎shared-bindings/displayio/Palette.c

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,7 @@ STATIC mp_obj_t group_unary_op(mp_unary_op_t op, mp_obj_t self_in) {
8585
}
8686

8787
//| def __setitem__(self, index: Any, value: Any) -> Any:
88-
//| """Sets the pixel color at the given index. The index should be an integer in the range 0 to color_count-1.
88+
//| r"""Sets the pixel color at the given index. The index should be an integer in the range 0 to color_count-1.
8989
//|
9090
//| The value argument represents a color, and can be from 0x000000 to 0xFFFFFF (to represent an RGB value).
9191
//| Value can be an int, bytes (3 bytes (RGB) or 4 bytes (RGB + pad byte)), bytearray,

‎shared-bindings/index.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,5 +19,5 @@ Modules
1919
:glob:
2020
:maxdepth: 2
2121

22-
../autoapi/*/index
22+
../shared-bindings/*/index
2323
help

‎shared-bindings/nvm/ByteArray.c

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@
3232
#include "supervisor/shared/translate.h"
3333

3434
//| class ByteArray:
35-
//| """Presents a stretch of non-volatile memory as a bytearray.
35+
//| r"""Presents a stretch of non-volatile memory as a bytearray.
3636
//|
3737
//| Non-volatile memory is available as a byte array that persists over reloads
3838
//| and power cycles. Each assignment causes an erase and write cycle so its recommended to assign

0 commit comments

Comments
 (0)