From 3c3cad5ae6f050150931373e1472098671779973 Mon Sep 17 00:00:00 2001 From: Jeff Epler Date: Sun, 14 Jun 2020 11:11:44 -0500 Subject: [PATCH 1/5] docs: Improve 5.0.x <-> main branch doc linkrot This improves, but does not entirely fix, the broken links that result from the autoapi change. It fixes module-level links, but class links still do not work (e.g., /shared-bindings/displayio/Palette.html (5.0.x) is now just /shared-bindings/displayio/#displayio.Palette). --- .gitignore | 1 + conf.py | 1 + ports/atmel-samd/README.rst | 2 +- shared-bindings/index.rst | 2 +- 4 files changed, 4 insertions(+), 2 deletions(-) diff --git a/.gitignore b/.gitignore index f5edb89f0e..8a773970d3 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 3980ea8e1b..06aab271b2 100644 --- a/conf.py +++ b/conf.py @@ -79,6 +79,7 @@ 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" # The encoding of source files. #source_encoding = 'utf-8-sig' diff --git a/ports/atmel-samd/README.rst b/ports/atmel-samd/README.rst index a6881902e9..0746d1de06 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/index.rst b/shared-bindings/index.rst index d941773943..bf04ae18b1 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 From f83b0c2507611a95ab4dea0c87b25ba85a0de9d6 Mon Sep 17 00:00:00 2001 From: Jeff Epler Date: Sun, 14 Jun 2020 12:56:22 -0500 Subject: [PATCH 2/5] docs: conf.py: alphabetize imports --- conf.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/conf.py b/conf.py index 06aab271b2..99423841b8 100644 --- a/conf.py +++ b/conf.py @@ -14,11 +14,12 @@ # serve to show the default. import json -import sys 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 From cb8539b06dd4bce11207341a311bffca741d190c Mon Sep 17 00:00:00 2001 From: Jeff Epler Date: Sun, 14 Jun 2020 13:04:21 -0500 Subject: [PATCH 3/5] docs: Generate redirects for autoapi renaming --- conf.py | 45 ++++++++++++++++++++++ docs/redirects.txt | 94 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 139 insertions(+) create mode 100644 docs/redirects.txt diff --git a/conf.py b/conf.py index 99423841b8..d39f74bd7d 100644 --- a/conf.py +++ b/conf.py @@ -14,6 +14,7 @@ # serve to show the default. import json +import logging import os import subprocess import sys @@ -82,6 +83,8 @@ 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' @@ -376,5 +379,47 @@ 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 = """ + + +""" + + +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 + + # TODO(stephenfin): Add support for DirectoryHTMLBuilder + 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 0000000000..68d0b2de2e --- /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 From 32a29ffdff4f757b818be9d63df44366a9ea389c Mon Sep 17 00:00:00 2001 From: Jeff Epler Date: Sun, 14 Jun 2020 13:04:58 -0500 Subject: [PATCH 4/5] shared-bindings: Change docstrings with '\x...' chars to raw strings Closes: #3032 --- shared-bindings/_bleio/Address.c | 2 +- shared-bindings/displayio/Display.c | 2 +- shared-bindings/displayio/Palette.c | 2 +- shared-bindings/nvm/ByteArray.c | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/shared-bindings/_bleio/Address.c b/shared-bindings/_bleio/Address.c index ccbab1b9d2..9beaff2ab2 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 62ef0f5d00..6e454f34bd 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 871b2b06af..37cfbd82e9 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/nvm/ByteArray.c b/shared-bindings/nvm/ByteArray.c index 326f719a83..06d7d4c95b 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 From 7a51719fa287a1a45af6d411c7a698cb6c20aedb Mon Sep 17 00:00:00 2001 From: Jeff Epler Date: Mon, 15 Jun 2020 16:50:33 -0500 Subject: [PATCH 5/5] docs: conf.py: Remove an irrelevant TODO This TODO made sense in the context of the original project, but for use in CircuitPython it does not appear to be relevant. Remove it. --- conf.py | 1 - 1 file changed, 1 deletion(-) diff --git a/conf.py b/conf.py index d39f74bd7d..38546a5d0a 100644 --- a/conf.py +++ b/conf.py @@ -394,7 +394,6 @@ def generate_redirects(app): app.info("Could not find redirects file at '%s'" % path) return - # TODO(stephenfin): Add support for DirectoryHTMLBuilder if not type(app.builder) == builders.StandaloneHTMLBuilder: logging.warn("The 'sphinxcontib-redirects' plugin is only supported " "by the 'html' builder. Skipping...")