Merge pull request #68 from bxparks/develop

merge v1.7.3 into master

Author: bxparks

CHANGELOG.md

@@ -1,6 +1,12 @@
 # Changelog
 
 * Unreleased
+* 1.7.3 (2021-08-25)
+    * Fix numerous broken links in documents moved to `docs/*.md` in an earlier
+      refactoring.
+    * Add experimental `DS3231Module` class that uses `AceWire` library.
+    * This is a maintenance release before some major refactoring. No changes to
+      core library code.
 * 1.7.2 (2021-06-02)
     * **Bug Fix**: Add `ZonedDateTime::normalize()`, which must be called by
       the client code after calling a `ZonedDateTime` mutation function.

README.md

@@ -4,11 +4,6 @@
 [![Python Tools](https://github.com/bxparks/AceTime/actions/workflows/python_tools.yml/badge.svg)](https://github.com/bxparks/AceTime/actions/workflows/python_tools.yml)
 [![Validation Tests](https://github.com/bxparks/AceTime/actions/workflows/validation.yml/badge.svg)](https://github.com/bxparks/AceTime/actions/workflows/validation.yml)
 
-**New**: [GitHub Discussions](https://github.com/bxparks/AceTime/discussions)
-for this project is now active! Let's use that for general support questions,
-and reserve the [GitHub Issues](https://github.com/bxparks/AceTime/issues)
-section for bugs and feature requests.
-
 The AceTime library provides Date, Time, and TimeZone classes which can convert
 "epoch seconds" to human-readable local date and time fields. Those classes can
 also convert local date and time between different time zones, properly
@@ -40,7 +35,7 @@ This library can be an alternative to the Arduino Time
 (https://github.com/PaulStoffregen/Time) and Arduino Timezone
 (https://github.com/JChristensen/Timezone) libraries.
 
-**Version**: 1.7.2 (2021-06-02, TZ DB version 2021a)
+**Version**: 1.7.3 (2021-08-25, TZ DB version 2021a)
 
 **Changelog**: [CHANGELOG.md](CHANGELOG.md)
 
@@ -63,13 +58,7 @@ installation instructions.
     * [HelloSystemClock](#HelloSystemClock)
     * [WorldClock](#WorldClock)
 * [Installation](#Installation)
-* [User Guides](#UserGuides)
-    * [docs/date_time_timezone.md](docs/date_time_timezone.md)
-    * [docs/clock_system_clock.md](docs/clock_system_clock.md)
-    * [Doxygen docs](https://bxparks.github.io/AceTime/html) hosted on GitHub
-      Pages
-* [Benchmarks](#Benchmarks)
-* [Comparisons to other Libraries](#Comparisons)
+* [Documentation](#Documentation)
 * [System Requirements](#SystemRequirements)
     * [Hardware](#Hardware)
     * [Tool Chain](#ToolChain)
@@ -558,13 +547,13 @@ for all 3 zones:
 
 See [docs/installation.md](docs/installation.md).
 
-<a name="UserGuides"></a>
-## User Guides
+<a name="Documentation"></a>
+## Documentation
 
 * [README.md](README.md)
     * this file
 * Date, Time and TimeZones
-  ([docs/date_time_timezone.md](docs/date_time_timezone.md))
+    * See [docs/date_time_timezone.md](docs/date_time_timezone.md)
     * Date and Time classes
     * TimeZone classes
     * ZoneInfo Database
@@ -573,31 +562,26 @@ See [docs/installation.md](docs/installation.md).
     * Motivation and Design Considerations
     * Bugs and Limitations
 * Clocks and SystemClocks
-  ([docs/clock_system_clock.md](docs/clock_system_clock.md))
-    * Clock
+    * See [docs/clock_system_clock.md](docs/clock_system_clock.md))
     * NTP Clock, DS3231 Clock, STM32 RTC Clock, STM32F1 Clock
     * SystemClock, SystemClockLoop, SystemClockCoroutine
-* [Doxygen docs](https://bxparks.github.io/AceTime/html) hosted on GitHub Pages
-
-<a name="Benchmarks"></a>
-## Benchmarks
-
-See [docs/benchmarks.md](docs/benchmarks.md) for CPU and memory usage
-benchmarks.
-
-<a name="Comparisons"></a>
-## Comparisons to Other Libraries
-
-See [docs/comparisons.md](docs/comparisons.md) for comparisons to other date,
-time and timezone libraries.
+* Doxygen docs
+    * See [Doxygen docs](https://bxparks.github.io/AceTime/html) hosted on
+      GitHub Pages
+* Benchmarks
+    * See [docs/benchmarks.md](docs/benchmarks.md) for CPU and memory usage
+      benchmarks
+* Comparisons to Other Libraries
+    * See [docs/comparisons.md](docs/comparisons.md) for comparisons to other
+      date, time and timezone libraries
 
 <a name="SystemRequirements"></a>
 ## System Requirements
 
 <a name="Hardware"></a>
 ### Hardware
 
-The library is tested on the following boards:
+This library has Tier 1 support on the following boards:
 
 * Arduino Nano clone (16 MHz ATmega328P)
 * SparkFun Pro Micro clone (16 MHz ATmega32U4)
@@ -608,15 +592,22 @@ The library is tested on the following boards:
 * ESP32 dev board (ESP-WROOM-32 module, 240 MHz dual core Tensilica LX6)
 * Teensy 3.2 (96 MHz ARM Cortex-M4)
 
-I will occasionally test on the following hardware as a sanity check:
+Tier 2 support can be expected on the following boards, mostly because I don't
+test these as often:
 
+* ATtiny85 (8 MHz ATtiny85)
+* Arduino Pro Mini (16 MHz ATmega328P)
 * Mini Mega 2560 (Arduino Mega 2560 compatible, 16 MHz ATmega2560)
 * Teensy LC (48 MHz ARM Cortex-M0+)
 
 The following boards are *not* supported:
 
-* megaAVR (e.g. Nano Every)
-* SAMD21 boards w/ `arduino:samd` version >= 1.8.10 (e.g. MKRZero)
+* Any platform using the ArduinoCore-API
+  (https://github.com/arduino/ArduinoCore-api), such as:
+    * megaAVR (e.g. Nano Every)
+    * SAMD21 boards w/ `arduino:samd` version >= 1.8.10 (e.g. MKRZero)
+    * MKRZero
+    * Raspberry Pi Pic RP2040
 
 <a name="ToolChain"></a>
 ### Tool Chain
@@ -625,13 +616,14 @@ This library was developed and tested using:
 
 * [Arduino IDE 1.8.13](https://www.arduino.cc/en/Main/Software)
 * [Arduino CLI 0.14.0](https://arduino.github.io/arduino-cli)
+* [SpenceKonde ATTinyCore 1.5.2](https://github.com/SpenceKonde/ATTinyCore)
 * [Arduino AVR Boards 1.8.3](https://github.com/arduino/ArduinoCore-avr)
 * [Arduino SAMD Boards 1.8.9](https://github.com/arduino/ArduinoCore-samd)
 * [SparkFun AVR Boards 1.1.13](https://github.com/sparkfun/Arduino_Boards)
-* [SparkFun SAMD Boards 1.8.1](https://github.com/sparkfun/Arduino_Boards)
-* [STM32duino 1.9.0](https://github.com/stm32duino/Arduino_Core_STM32)
+* [SparkFun SAMD Boards 1.8.3](https://github.com/sparkfun/Arduino_Boards)
+* [STM32duino 2.0.0](https://github.com/stm32duino/Arduino_Core_STM32)
 * [ESP8266 Arduino 2.7.4](https://github.com/esp8266/Arduino)
-* [ESP32 Arduino 1.0.4](https://github.com/espressif/arduino-esp32)
+* [ESP32 Arduino 1.0.6](https://github.com/espressif/arduino-esp32)
 * [Teensydino 1.53](https://www.pjrc.com/teensy/td_download.html)
 
 This library is *not* compatible with:
@@ -660,10 +652,6 @@ them.
 <a name="FeedbackAndSupport"></a>
 ## Feedback and Support
 
-If you find this library useful, consider starring this project on GitHub. The
-stars will let me prioritize the more popular libraries over the less popular
-ones.
-
 If you have any questions, comments and other support questions about how to
 use this library, please use the
 [GitHub Discussions](https://github.com/bxparks/AceTime/discussions)

docs/benchmarks.md

@@ -3,7 +3,7 @@
 <a name="CPU"></a>
 ## CPU
 
-The [AutoBenchmark.ino](examples/AutoBenchmark/) program measures the
+The [AutoBenchmark.ino](../examples/AutoBenchmark/) program measures the
 amount of CPU cycles taken by some of the more expensive methods. Here is a
 summary of the elapsed time for the `ZonedDateTime::forEpochSeconds()` method
 using a `BasicZoneManager` that already has its cache populated for the given
@@ -25,7 +25,7 @@ Teensy 3.2 96 MHz           |    6.4 |
 ## Memory
 
 Here is a quick summary of the amount of static RAM consumed by various
-classes (more details at [examples/AutoBenchmark](examples/AutoBenchmark):
+classes (more details at [examples/AutoBenchmark](../examples/AutoBenchmark):
 
 **8-bit processors**
 
@@ -66,7 +66,7 @@ sizeof(SystemClockLoop): 56
 sizeof(SystemClockCoroutine): 80
 ```
 
-The [MemoryBenchmark](examples/MemoryBenchmark) program gives a more
+The [MemoryBenchmark](../examples/MemoryBenchmark) program gives a more
 comprehensive answer to the amount of memory taken by this library.
 Here is a short summary for an 8-bit microcontroller (e.g. Arduino Nano):
 

docs/clock_system_clock.md

@@ -12,7 +12,7 @@ sense for these classes to be in a separate library because the other parts of
 AceTime library are not dependent of the Clock classes. But for now, these
 classes live within the AceTime library.
 
-**Version**: 1.7.2 (2021-06-02, TZ DB version 2021a)
+**Version**: 1.7.3 (2021-08-25, TZ DB version 2021a)
 
 ## Table of Contents
 
@@ -39,9 +39,9 @@ classes live within the AceTime library.
 
 **Related Documents**:
 
-* [README.md](README.md): introductory background.
-* [docs/installation.md](docs/installation.md): how to install the library
-* [docs/date_time_timezone.md](docs/date_time_timezone.md): the
+* [README.md](../README.md): introductory background.
+* [docs/installation.md](../docs/installation.md): how to install the library
+* [docs/date_time_timezone.md](../docs/date_time_timezone.md): the
   Date, Time and TimeZone classes
 * [Doxygen docs](https://bxparks.github.io/AceTime/html) hosted on GitHub Pages
 

docs/comparisons.md

@@ -15,13 +15,13 @@
 
 The AceTime library can be substantially faster than the equivalent methods in
 the [Arduino Time Library](https://github.com/PaulStoffregen/Time). The
-[ComparisonBenchmark.ino](examples/ComparisonBenchmark/) program compares the
+[ComparisonBenchmark.ino](../examples/ComparisonBenchmark/) program compares the
 CPU run time of `LocalDateTime::forEpochSeconds()` and
 `LocalDateTime::toEpochSeconds()` with the equivalent `breakTime()` and
 `makeTime()` functions of the Arduino Time Library. Details are given in the
-[ComparisonBenchmark/README.md](examples/ComparisonBenchmark/README.md) file in
-that folder, but here is a summary of the roundtrip times for various boards (in
-microseconds):
+[ComparisonBenchmark/README.md](../examples/ComparisonBenchmark/README.md) file
+in that folder, but here is a summary of the roundtrip times for various boards
+(in microseconds):
 
 ```
 ----------------------------+---------+----------+
@@ -141,9 +141,9 @@ environment because:
   library.
 
 The Hinnant date libraries were invaluable for writing the
-[BasicHinnantDateTest](tests/validation/BasicHinnantDateTest/)
+[BasicHinnantDateTest](../tests/validation/BasicHinnantDateTest/)
 and
-[ExtendedHinnantDateTest](tests/validation/ExtendedHinnantDateTest/)
+[ExtendedHinnantDateTest](../tests/validation/ExtendedHinnantDateTest/)
 validation tests which compare the AceTime algorithms to the Hinnant Date
 algorithms. For all times zones between the years 2000 until 2050, the AceTime
 UTC offsets (`TimeZone::getUtcOffset()`), timezone abbreviations