Skip to content

docs: Improve 5.0.x <-> main branch doc linkrot #3031

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Jun 16, 2020
Merged

docs: Improve 5.0.x <-> main branch doc linkrot #3031

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
3c3cad5
docs: Improve 5.0.x <-> main branch doc linkrot
jepler Jun 14, 2020
f83b0c2
docs: conf.py: alphabetize imports
jepler Jun 14, 2020
cb8539b
docs: Generate redirects for autoapi renaming
jepler Jun 14, 2020
32a29ff
shared-bindings: Change docstrings with '\x...' chars to raw strings
jepler Jun 14, 2020
7a51719
docs: conf.py: Remove an irrelevant TODO
jepler Jun 15, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,7 @@ _build
######################
genrst/
/autoapi/
/shared-bindings/**/*.rst

# ctags and similar
###################
Expand Down
50 changes: 48 additions & 2 deletions conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -79,6 +81,9 @@
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'
Expand Down Expand Up @@ -374,5 +379,46 @@
"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)
94 changes: 94 additions & 0 deletions docs/redirects.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
2 changes: 1 addition & 1 deletion ports/atmel-samd/README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,4 +21,4 @@ Port Specific modules
---------------------

.. toctree::
../../autoapi/samd/index
../../shared-bindings/samd/index
2 changes: 1 addition & 1 deletion shared-bindings/_bleio/Address.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion shared-bindings/displayio/Display.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion shared-bindings/displayio/Palette.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
2 changes: 1 addition & 1 deletion shared-bindings/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,5 +19,5 @@ Modules
:glob:
:maxdepth: 2

../autoapi/*/index
../shared-bindings/*/index
help
2 changes: 1 addition & 1 deletion shared-bindings/nvm/ByteArray.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down