Fix/update doc examples, test them as part of build.sh

Hot dayum some of these were outdated

Author: jamwaffles

build.sh

@@ -6,4 +6,7 @@ cargo build --target $TARGET --all-features --release
 
 if [ -z $DISABLE_EXAMPLES ]; then
 	cargo build --target $TARGET --all-features --examples
-fi
+fi
+
+cargo test --lib --target x86_64-unknown-linux-gnu
+cargo test --doc --target x86_64-unknown-linux-gnu

src/builder.rs

@@ -10,17 +10,26 @@
 //!
 //! Connect over SPI with default rotation (0 deg) and size (128x64):
 //!
-//! ```rust,ignore
-//! let spi = /* SPI interface from your HAL of choice */;
-//! let dc = /* GPIO data/command select pin */;
+//! ```rust,no_run
+//! use sh1106::{mode::GraphicsMode, Builder};
+//! let spi = /* SPI interface from your HAL of choice */
+//! # sh1106::test_helpers::SpiStub;
+//! let dc = /* GPIO data/command select pin */
+//! # sh1106::test_helpers::PinStub;
 //!
-//! Builder::new().connect_spi(spi, dc);
+//! // This example does not use a Chip Select pin
+//! let cs = sh1106::builder::NoOutputPin::new();
+//!
+//! Builder::new().connect_spi(spi, dc, cs);
 //! ```
 //!
 //! Connect over I2C, changing lots of options
 //!
-//! ```rust,ignore
-//! let i2c = /* I2C interface from your HAL of choice */;
+//! ```rust,no_run
+//! use sh1106::{displayrotation::DisplayRotation, displaysize::DisplaySize, Builder};
+//!
+//! let i2c = /* I2C interface from your HAL of choice */
+//! # sh1106::test_helpers::I2cStub;
 //!
 //! Builder::new()
 //!     .with_rotation(DisplayRotation::Rotate180)
@@ -33,11 +42,17 @@
 //! by default. You need to coerce them into a mode by specifying a type on assignment. For
 //! example, to use [`GraphicsMode` mode](../mode/graphics/struct.GraphicsMode.html):
 //!
-//! ```rust,ignore
-//! let spi = /* SPI interface from your HAL of choice */;
-//! let dc = /* GPIO data/command select pin */;
+//! ```rust,no_run
+//! use sh1106::{mode::GraphicsMode, Builder};
+//! let spi = /* SPI interface from your HAL of choice */
+//! # sh1106::test_helpers::SpiStub;
+//! let dc = /* GPIO data/command select pin */
+//! # sh1106::test_helpers::PinStub;
+//!
+//! // This example does not use a Chip Select pin
+//! let cs = sh1106::builder::NoOutputPin::new();
 //!
-//! let display: GraphicsMode<_> = Builder::new().connect_spi(spi, dc).into();
+//! let display: GraphicsMode<_> = Builder::new().connect_spi(spi, dc, cs).into();
 //! ```
 
 use core::marker::PhantomData;
@@ -52,6 +67,8 @@ use crate::{
 };
 
 /// Builder struct. Driver options and interface are set using its methods.
+///
+/// See the [module level documentation](crate::builder) for more details.
 #[derive(Clone, Copy)]
 pub struct Builder {
     display_size: DisplaySize,

src/interface/mod.rs

@@ -9,14 +9,12 @@
 //! a type alias. Here's an example for the I2C1 on an STM32F103xx:
 //!
 //! ```rust
-//! # extern crate sh1106;
-//! # extern crate stm32f103xx_hal as hal;
-//! # use hal::gpio::gpiob::{PB8, PB9};
-//! # use hal::gpio::{Alternate, OpenDrain};
-//! # use hal::i2c::I2c;
-//! # use hal::prelude::*;
-//! # use hal::stm32f103xx::I2C1;
-//! # use sh1106::interface::I2cInterface;
+//! # use stm32f1xx_hal::gpio::gpiob::{PB8, PB9};
+//! # use stm32f1xx_hal::gpio::{Alternate, OpenDrain};
+//! # use stm32f1xx_hal::i2c::I2c;
+//! # use stm32f1xx_hal::prelude::*;
+//! # use stm32f1xx_hal::pac::I2C1;
+//! # use sh1106::{interface::I2cInterface, mode::GraphicsMode, Builder};
 //! type OledDisplay = GraphicsMode<
 //!     I2cInterface<I2c<I2C1, (PB8<Alternate<OpenDrain>>, PB9<Alternate<OpenDrain>>)>>,
 //! >;
@@ -25,25 +23,27 @@
 //! Here's one for SPI1 on an STM32F103xx:
 //!
 //! ```rust
-//! # extern crate sh1106;
-//! # extern crate stm32f103xx_hal as hal;
-//! # use hal::gpio::gpioa::{PA5, PA6, PA7};
-//! # use hal::gpio::gpiob::PB1;
-//! # use hal::gpio::{Alternate, Floating, Input, Output, PushPull};
-//! # use hal::spi::Spi;
-//! # use hal::stm32f103xx::SPI1;
-//! # use sh1106::interface::SpiInterface;
+//! # use stm32f1xx_hal::gpio::gpioa::{PA5, PA6, PA7};
+//! # use stm32f1xx_hal::gpio::gpiob::PB1;
+//! # use stm32f1xx_hal::gpio::{Alternate, Floating, Input, Output, PushPull};
+//! # use stm32f1xx_hal::spi;
+//! # use stm32f1xx_hal::spi::Spi;
+//! # use stm32f1xx_hal::pac::SPI1;
+//! # use sh1106::{interface::SpiInterface, mode::GraphicsMode};
 //! pub type OledDisplay = GraphicsMode<
 //!     SpiInterface<
 //!         Spi<
 //!             SPI1,
+//!             spi::Spi1NoRemap,
 //!             (
 //!                 PA5<Alternate<PushPull>>,
 //!                 PA6<Input<Floating>>,
 //!                 PA7<Alternate<PushPull>>,
 //!             ),
+//!             u8
 //!         >,
 //!         PB1<Output<PushPull>>,
+//!         sh1106::builder::NoOutputPin,
 //!     >,
 //! >;
 //! ```

src/lib.rs

@@ -9,13 +9,18 @@
 //! [`mode::GraphicsMode`](mode/graphics/struct.GraphicsMode.html), you would do something like
 //! this:
 //!
-//! ```rust,ignore
-//! let i2c = I2c::i2c1(/* snip */);
+//! ```rust,no_run
+//! use sh1106::{prelude::*, Builder};
+//! # let i2c = sh1106::test_helpers::I2cStub;
 //!
 //! let mut display: GraphicsMode<_> = Builder::new().connect_i2c(i2c).into();
-//! display.init();
+//!
+//! display.init().unwrap();
+//! display.flush().unwrap();
 //!
 //! display.set_pixel(10, 20, 1);
+//!
+//! display.flush().unwrap();
 //! ```
 //!
 //! See the [example](https://github.com/jamwaffles/sh1106/blob/master/examples/graphics_i2c.rs)
@@ -34,56 +39,35 @@
 //!
 //! Uses [mode::GraphicsMode] and [embedded_graphics](../embedded_graphics/index.html).
 //!
-//! ```rust,no-run
-//! #![no_std]
-//!
-//! extern crate cortex_m;
-//! extern crate embedded_graphics;
-//! extern crate embedded_hal as hal;
-//! extern crate panic_abort;
-//! extern crate sh1106;
-//! extern crate stm32f103xx_hal as blue_pill;
-//!
-//! use blue_pill::i2c::{DutyCycle, I2c, Mode};
-//! use blue_pill::prelude::*;
-//! use embedded_graphics::fonts::Font6x8;
-//! use embedded_graphics::prelude::*;
-//! use sh1106::{mode::GraphicsMode, Builder};
-//!
-//! fn main() {
-//!     let dp = blue_pill::stm32f103xx::Peripherals::take().unwrap();
-//!     let mut flash = dp.FLASH.constrain();
-//!     let mut rcc = dp.RCC.constrain();
-//!     let clocks = rcc.cfgr.freeze(&mut flash.acr);
-//!     let mut afio = dp.AFIO.constrain(&mut rcc.apb2);
-//!     let mut gpiob = dp.GPIOB.split(&mut rcc.apb2);
-//!     let scl = gpiob.pb8.into_alternate_open_drain(&mut gpiob.crh);
-//!     let sda = gpiob.pb9.into_alternate_open_drain(&mut gpiob.crh);
-//!
-//!     let i2c = I2c::i2c1(
-//!         dp.I2C1,
-//!         (scl, sda),
-//!         &mut afio.mapr,
-//!         Mode::Fast {
-//!             frequency: 400_000,
-//!             duty_cycle: DutyCycle::Ratio1to1,
-//!         },
-//!         clocks,
-//!         &mut rcc.apb1,
-//!     );
-//!
-//!     let mut display: GraphicsMode<_> = Builder::new().connect_i2c(i2c).into();
-//!
-//!     display.init().unwrap();
-//!     display.flush().unwrap();
-//!     display.draw(Font6x8::render_str("Hello world!", 1u8.into()).into_iter());
-//!     display.draw(
-//!         Font6x8::render_str("Hello Rust!")
-//!             .translate(Coord::new(0, 16))
-//!             .into_iter(),
-//!     );
-//!     display.flush().unwrap();
-//! }
+//! ```rust,no_run
+//! use embedded_graphics::{
+//!     mono_font::{ascii::FONT_6X10, MonoTextStyleBuilder},
+//!     pixelcolor::BinaryColor,
+//!     prelude::*,
+//!     text::{Baseline, Text},
+//! };
+//! use sh1106::{prelude::*, Builder};
+//! # let i2c = sh1106::test_helpers::I2cStub;
+//!
+//! let mut display: GraphicsMode<_> = Builder::new().connect_i2c(i2c).into();
+//!
+//! display.init().unwrap();
+//! display.flush().unwrap();
+//!
+//! let text_style = MonoTextStyleBuilder::new()
+//!     .font(&FONT_6X10)
+//!     .text_color(BinaryColor::On)
+//!     .build();
+//!
+//! Text::with_baseline("Hello world!", Point::zero(), text_style, Baseline::Top)
+//!     .draw(&mut display)
+//!     .unwrap();
+//!
+//! Text::with_baseline("Hello Rust!", Point::new(0, 16), text_style, Baseline::Top)
+//!     .draw(&mut display)
+//!     .unwrap();
+//!
+//! display.flush().unwrap();
 //! ```
 
 #![no_std]
@@ -110,10 +94,12 @@ extern crate embedded_hal as hal;
 pub mod builder;
 mod command;
 pub mod displayrotation;
-mod displaysize;
+pub mod displaysize;
 pub mod interface;
 pub mod mode;
 pub mod prelude;
 pub mod properties;
+#[doc(hidden)]
+pub mod test_helpers;
 
 pub use crate::builder::{Builder, NoOutputPin};

src/mode/graphics.rs

@@ -1,17 +1,44 @@
-//! Buffered display module for use with the [embedded_graphics] crate
+//! Buffered display module for use with the [embedded-graphics] crate
 //!
-//! ```rust,ignore
-//! let i2c = /* I2C interface from your HAL of choice */;
-//! let display: GraphicsMode<_> = Builder::new().connect_i2c(i2c).into();
-//! let image = include_bytes!("image_16x16.raw");
+//! ```rust,no_run
+//! use embedded_graphics::{
+//!     pixelcolor::BinaryColor,
+//!     prelude::*,
+//!     primitives::{Circle, Line, PrimitiveStyle, Rectangle},
+//! };
+//! use sh1106::{prelude::*, Builder};
+//! # let i2c = sh1106::test_helpers::I2cStub;
+//!
+//! let mut display: GraphicsMode<_> = Builder::new().connect_i2c(i2c).into();
 //!
 //! display.init().unwrap();
 //! display.flush().unwrap();
-//! display.draw(Line::new(Coord::new(0, 0), (16, 16), 1.into()).into_iter());
-//! display.draw(Rect::new(Coord::new(24, 0), (40, 16), 1u8.into()).into_iter());
-//! display.draw(Circle::new(Coord::new(64, 8), 8, 1u8.into()).into_iter());
-//! display.draw(Image1BPP::new(image, 0, 24));
-//! display.draw(Font6x8::render_str("Hello Rust!", 1u8.into()).translate(Coord::new(24, 24)).into_iter());
+//!
+//! Line::new(Point::new(8, 16 + 16), Point::new(8 + 16, 16 + 16))
+//!     .into_styled(PrimitiveStyle::with_stroke(BinaryColor::On, 1))
+//!     .draw(&mut display)
+//!     .unwrap();
+//!
+//! Line::new(Point::new(8, 16 + 16), Point::new(8 + 8, 16))
+//!     .into_styled(PrimitiveStyle::with_stroke(BinaryColor::On, 1))
+//!     .draw(&mut display)
+//!     .unwrap();
+//!
+//! Line::new(Point::new(8 + 16, 16 + 16), Point::new(8 + 8, 16))
+//!     .into_styled(PrimitiveStyle::with_stroke(BinaryColor::On, 1))
+//!     .draw(&mut display)
+//!     .unwrap();
+//!
+//! Rectangle::with_corners(Point::new(48, 16), Point::new(48 + 16, 16 + 16))
+//!     .into_styled(PrimitiveStyle::with_stroke(BinaryColor::On, 1))
+//!     .draw(&mut display)
+//!     .unwrap();
+//!
+//! Circle::new(Point::new(88, 16), 16)
+//!     .into_styled(PrimitiveStyle::with_stroke(BinaryColor::On, 1))
+//!     .draw(&mut display)
+//!     .unwrap();
+//!
 //! display.flush().unwrap();
 //! ```
 

src/properties.rs

@@ -125,32 +125,6 @@ where
     }
 
     /// Get display dimensions, taking into account the current rotation of the display
-    ///
-    /// ```rust
-    /// # struct FakeInterface;
-    /// #
-    /// # impl DisplayInterface for FakeInterface {
-    /// #     fn send_command(&mut self, cmd: u8) -> Result<(), ()> { Ok(()) }
-    /// #     fn send_data(&mut self, buf: &[u8]) -> Result<(), ()> { Ok(()) }
-    /// # }
-    /// #
-    /// # let interface = FakeInterface {};
-    /// #
-    /// let disp = DisplayProperties::new(
-    ///     interface,
-    ///     DisplaySize::Display128x64,
-    ///     DisplayRotation::Rotate0,
-    /// );
-    /// assert_eq!(display.get_dimensions(), (128, 64));
-    ///
-    /// # let interface = FakeInterface {};
-    /// let rotated_disp = DisplayProperties::new(
-    ///     interface,
-    ///     DisplaySize::Display128x64,
-    ///     DisplayRotation::Rotate90,
-    /// );
-    /// assert_eq!(rotated_display.get_dimensions(), (64, 128));
-    /// ```
     pub fn get_dimensions(&self) -> (u8, u8) {
         let (w, h) = self.display_size.dimensions();
 

src/test_helpers.rs

@@ -0,0 +1,57 @@
+//! Helpers for use in examples and tests
+
+use embedded_hal::{
+    blocking::{
+        i2c,
+        spi::{self, Transfer},
+    },
+    digital::v2::OutputPin,
+};
+
+#[allow(dead_code)]
+#[derive(Debug, Clone, Copy)]
+pub struct SpiStub;
+
+impl spi::Write<u8> for SpiStub {
+    type Error = ();
+
+    fn write(&mut self, _buf: &[u8]) -> Result<(), ()> {
+        Ok(())
+    }
+}
+
+impl Transfer<u8> for SpiStub {
+    type Error = ();
+
+    fn transfer<'a>(&mut self, buf: &'a mut [u8]) -> Result<&'a [u8], ()> {
+        Ok(buf)
+    }
+}
+
+#[allow(dead_code)]
+#[derive(Debug, Clone, Copy)]
+pub struct PinStub;
+
+impl OutputPin for PinStub {
+    type Error = ();
+
+    fn set_high(&mut self) -> Result<(), ()> {
+        Ok(())
+    }
+
+    fn set_low(&mut self) -> Result<(), ()> {
+        Ok(())
+    }
+}
+
+#[allow(dead_code)]
+#[derive(Debug, Clone, Copy)]
+pub struct I2cStub;
+
+impl i2c::Write for I2cStub {
+    type Error = ();
+
+    fn write(&mut self, _addr: u8, _buf: &[u8]) -> Result<(), ()> {
+        Ok(())
+    }
+}