rrm workspace: TRM/HRM/SRM code, Maze dataset, dynamical-analysis pipelineHEADmain

Curated export for clone-and-run Maze training (2x A6000) + diagnostics.
trm/hrm pretrain.py carry trajectory-augmentation code (backward-compatible).
Heavy artifacts (checkpoints/wandb/npz) gitignored; see PROVENANCE.md.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

1 files changed, 826 insertions, 0 deletions

diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Dates/docs/src/index.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Dates/docs/src/index.md
new file mode 100644
index 0000000..975c087
--- /dev/null
+++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Dates/docs/src/index.md
@@ -0,0 +1,826 @@
+# Dates
+
+```@meta
+DocTestSetup = :(using Dates)
+```
+
+The `Dates` module provides two types for working with dates: [`Date`](@ref) and [`DateTime`](@ref),
+representing day and millisecond precision, respectively; both are subtypes of the abstract [`TimeType`](@ref).
+The motivation for distinct types is simple: some operations are much simpler, both in terms of
+code and mental reasoning, when the complexities of greater precision don't have to be dealt with.
+For example, since the [`Date`](@ref) type only resolves to the precision of a single date (i.e.
+no hours, minutes, or seconds), normal considerations for time zones, daylight savings/summer
+time, and leap seconds are unnecessary and avoided.
+
+Both [`Date`](@ref) and [`DateTime`](@ref) are basically immutable [`Int64`](@ref) wrappers.
+The single `instant` field of either type is actually a `UTInstant{P}` type, which
+represents a continuously increasing machine timeline based on the UT second [^1]. The
+[`DateTime`](@ref) type is not aware of time zones (*naive*, in Python parlance),
+analogous to a *LocalDateTime* in Java 8. Additional time zone functionality
+can be added through the [TimeZones.jl package](https://github.com/JuliaTime/TimeZones.jl/), which
+compiles the [IANA time zone database](http://www.iana.org/time-zones). Both [`Date`](@ref) and
+[`DateTime`](@ref) are based on the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard, which follows the proleptic Gregorian calendar.
+One note is that the ISO 8601 standard is particular about BC/BCE dates. In general, the last
+day of the BC/BCE era, 1-12-31 BC/BCE, was followed by 1-1-1 AD/CE, thus no year zero exists.
+The ISO standard, however, states that 1 BC/BCE is year zero, so `0000-12-31` is the day before
+`0001-01-01`, and year `-0001` (yes, negative one for the year) is 2 BC/BCE, year `-0002` is 3
+BC/BCE, etc.
+
+[^1]:
+    The notion of the UT second is actually quite fundamental. There are basically two different notions
+    of time generally accepted, one based on the physical rotation of the earth (one full rotation
+    = 1 day), the other based on the SI second (a fixed, constant value). These are radically different!
+    Think about it, a "UT second", as defined relative to the rotation of the earth, may have a different
+    absolute length depending on the day! Anyway, the fact that [`Date`](@ref) and [`DateTime`](@ref)
+    are based on UT seconds is a simplifying, yet honest assumption so that things like leap seconds
+    and all their complexity can be avoided. This basis of time is formally called [UT](https://en.wikipedia.org/wiki/Universal_Time)
+    or UT1. Basing types on the UT second basically means that every minute has 60 seconds and every
+    day has 24 hours and leads to more natural calculations when working with calendar dates.
+
+## Constructors
+
+[`Date`](@ref) and [`DateTime`](@ref) types can be constructed by integer or [`Period`](@ref)
+types, by parsing, or through adjusters (more on those later):
+
+```jldoctest
+julia> DateTime(2013)
+2013-01-01T00:00:00
+
+julia> DateTime(2013,7)
+2013-07-01T00:00:00
+
+julia> DateTime(2013,7,1)
+2013-07-01T00:00:00
+
+julia> DateTime(2013,7,1,12)
+2013-07-01T12:00:00
+
+julia> DateTime(2013,7,1,12,30)
+2013-07-01T12:30:00
+
+julia> DateTime(2013,7,1,12,30,59)
+2013-07-01T12:30:59
+
+julia> DateTime(2013,7,1,12,30,59,1)
+2013-07-01T12:30:59.001
+
+julia> Date(2013)
+2013-01-01
+
+julia> Date(2013,7)
+2013-07-01
+
+julia> Date(2013,7,1)
+2013-07-01
+
+julia> Date(Dates.Year(2013),Dates.Month(7),Dates.Day(1))
+2013-07-01
+
+julia> Date(Dates.Month(7),Dates.Year(2013))
+2013-07-01
+```
+
+[`Date`](@ref) or [`DateTime`](@ref) parsing is accomplished by the use of format strings. Format
+strings work by the notion of defining *delimited* or *fixed-width* "slots" that contain a period
+to parse and passing the text to parse and format string to a [`Date`](@ref) or [`DateTime`](@ref)
+constructor, of the form `Date("2015-01-01","y-m-d")` or `DateTime("20150101","yyyymmdd")`.
+
+Delimited slots are marked by specifying the delimiter the parser should expect between two subsequent
+periods; so `"y-m-d"` lets the parser know that between the first and second slots in a date string
+like `"2014-07-16"`, it should find the `-` character. The `y`, `m`, and `d` characters let the
+parser know which periods to parse in each slot.
+
+Fixed-width slots are specified by repeating the period character the number of times corresponding
+to the width with no delimiter between characters. So `"yyyymmdd"` would correspond to a date
+string like `"20140716"`. The parser distinguishes a fixed-width slot by the absence of a delimiter,
+noting the transition `"yyyymm"` from one period character to the next.
+
+Support for text-form month parsing is also supported through the `u` and `U` characters, for
+abbreviated and full-length month names, respectively. By default, only English month names are
+supported, so `u` corresponds to "Jan", "Feb", "Mar", etc. And `U` corresponds to "January", "February",
+"March", etc. Similar to other name=>value mapping functions [`dayname`](@ref) and [`monthname`](@ref),
+custom locales can be loaded by passing in the `locale=>Dict{String,Int}` mapping to the `MONTHTOVALUEABBR`
+and `MONTHTOVALUE` dicts for abbreviated and full-name month names, respectively.
+
+One note on parsing performance: using the `Date(date_string,format_string)` function is fine
+if only called a few times. If there are many similarly formatted date strings to parse however,
+it is much more efficient to first create a [`Dates.DateFormat`](@ref), and pass it instead of
+a raw format string.
+
+```jldoctest
+julia> df = DateFormat("y-m-d");
+
+julia> dt = Date("2015-01-01",df)
+2015-01-01
+
+julia> dt2 = Date("2015-01-02",df)
+2015-01-02
+```
+
+You can also use the `dateformat""` string macro. This macro creates the `DateFormat` object once when the macro is expanded and uses the same `DateFormat` object even if a code snippet is run multiple times.
+
+```jldoctest
+julia> for i = 1:10^5
+           Date("2015-01-01", dateformat"y-m-d")
+       end
+```
+
+A full suite of parsing and formatting tests and examples is available in [`stdlib/Dates/test/io.jl`](https://github.com/JuliaLang/julia/blob/master/stdlib/Dates/test/io.jl).
+
+## Durations/Comparisons
+
+Finding the length of time between two [`Date`](@ref) or [`DateTime`](@ref) is straightforward
+given their underlying representation as `UTInstant{Day}` and `UTInstant{Millisecond}`, respectively.
+The difference between [`Date`](@ref) is returned in the number of [`Day`](@ref), and [`DateTime`](@ref)
+in the number of [`Millisecond`](@ref). Similarly, comparing [`TimeType`](@ref) is a simple matter
+of comparing the underlying machine instants (which in turn compares the internal [`Int64`](@ref) values).
+
+```jldoctest
+julia> dt = Date(2012,2,29)
+2012-02-29
+
+julia> dt2 = Date(2000,2,1)
+2000-02-01
+
+julia> dump(dt)
+Date
+  instant: Dates.UTInstant{Day}
+    periods: Day
+      value: Int64 734562
+
+julia> dump(dt2)
+Date
+  instant: Dates.UTInstant{Day}
+    periods: Day
+      value: Int64 730151
+
+julia> dt > dt2
+true
+
+julia> dt != dt2
+true
+
+julia> dt + dt2
+ERROR: MethodError: no method matching +(::Date, ::Date)
+[...]
+
+julia> dt * dt2
+ERROR: MethodError: no method matching *(::Date, ::Date)
+[...]
+
+julia> dt / dt2
+ERROR: MethodError: no method matching /(::Date, ::Date)
+
+julia> dt - dt2
+4411 days
+
+julia> dt2 - dt
+-4411 days
+
+julia> dt = DateTime(2012,2,29)
+2012-02-29T00:00:00
+
+julia> dt2 = DateTime(2000,2,1)
+2000-02-01T00:00:00
+
+julia> dt - dt2
+381110400000 milliseconds
+```
+
+## Accessor Functions
+
+Because the [`Date`](@ref) and [`DateTime`](@ref) types are stored as single [`Int64`](@ref) values, date
+parts or fields can be retrieved through accessor functions. The lowercase accessors return the
+field as an integer:
+
+```jldoctest tdate
+julia> t = Date(2014, 1, 31)
+2014-01-31
+
+julia> Dates.year(t)
+2014
+
+julia> Dates.month(t)
+1
+
+julia> Dates.week(t)
+5
+
+julia> Dates.day(t)
+31
+```
+
+While propercase return the same value in the corresponding [`Period`](@ref) type:
+
+```jldoctest tdate
+julia> Dates.Year(t)
+2014 years
+
+julia> Dates.Day(t)
+31 days
+```
+
+Compound methods are provided because it is more efficient to access multiple fields at the same time than individually:
+
+```jldoctest tdate
+julia> Dates.yearmonth(t)
+(2014, 1)
+
+julia> Dates.monthday(t)
+(1, 31)
+
+julia> Dates.yearmonthday(t)
+(2014, 1, 31)
+```
+
+One may also access the underlying `UTInstant` or integer value:
+
+```jldoctest tdate
+julia> dump(t)
+Date
+  instant: Dates.UTInstant{Day}
+    periods: Day
+      value: Int64 735264
+
+julia> t.instant
+Dates.UTInstant{Day}(Day(735264))
+
+julia> Dates.value(t)
+735264
+```
+
+## Query Functions
+
+Query functions provide calendrical information about a [`TimeType`](@ref). They include information
+about the day of the week:
+
+```jldoctest tdate2
+julia> t = Date(2014, 1, 31)
+2014-01-31
+
+julia> Dates.dayofweek(t)
+5
+
+julia> Dates.dayname(t)
+"Friday"
+
+julia> Dates.dayofweekofmonth(t) # 5th Friday of January
+5
+```
+
+Month of the year:
+
+```jldoctest tdate2
+julia> Dates.monthname(t)
+"January"
+
+julia> Dates.daysinmonth(t)
+31
+```
+
+As well as information about the [`TimeType`](@ref)'s year and quarter:
+
+```jldoctest tdate2
+julia> Dates.isleapyear(t)
+false
+
+julia> Dates.dayofyear(t)
+31
+
+julia> Dates.quarterofyear(t)
+1
+
+julia> Dates.dayofquarter(t)
+31
+```
+
+The [`dayname`](@ref) and [`monthname`](@ref) methods can also take an optional `locale` keyword
+that can be used to return the name of the day or month of the year for other languages/locales.
+There are also versions of these functions returning the abbreviated names, namely
+[`dayabbr`](@ref) and [`monthabbr`](@ref).
+First the mapping is loaded into the `LOCALES` variable:
+
+```jldoctest tdate2
+julia> french_months = ["janvier", "février", "mars", "avril", "mai", "juin",
+                        "juillet", "août", "septembre", "octobre", "novembre", "décembre"];
+
+julia> french_monts_abbrev = ["janv","févr","mars","avril","mai","juin",
+                              "juil","août","sept","oct","nov","déc"];
+
+julia> french_days = ["lundi","mardi","mercredi","jeudi","vendredi","samedi","dimanche"];
+
+julia> Dates.LOCALES["french"] = Dates.DateLocale(french_months, french_monts_abbrev, french_days, [""]);
+```
+
+ The above mentioned functions can then be used to perform the queries:
+
+```jldoctest tdate2
+julia> Dates.dayname(t;locale="french")
+"vendredi"
+
+julia> Dates.monthname(t;locale="french")
+"janvier"
+
+julia> Dates.monthabbr(t;locale="french")
+"janv"
+```
+
+Since the abbreviated versions of the days are not loaded, trying to use the
+function `dayabbr` will error.
+
+```jldoctest tdate2
+julia> Dates.dayabbr(t;locale="french")
+ERROR: BoundsError: attempt to access 1-element Vector{String} at index [5]
+Stacktrace:
+[...]
+```
+
+
+## TimeType-Period Arithmetic
+
+It's good practice when using any language/date framework to be familiar with how date-period
+arithmetic is handled as there are some [tricky issues](https://codeblog.jonskeet.uk/2010/12/01/the-joys-of-date-time-arithmetic/)
+to deal with (though much less so for day-precision types).
+
+The `Dates` module approach tries to follow the simple principle of trying to change as
+little as possible when doing [`Period`](@ref) arithmetic. This approach is also often known as
+*calendrical* arithmetic or what you would probably guess if someone were to ask you the same
+calculation in a conversation. Why all the fuss about this? Let's take a classic example: add
+1 month to January 31st, 2014. What's the answer? Javascript will say [March 3](https://markhneedham.com/blog/2009/01/07/javascript-add-a-month-to-a-date/)
+(assumes 31 days). PHP says [March 2](https://stackoverflow.com/questions/5760262/php-adding-months-to-a-date-while-not-exceeding-the-last-day-of-the-month)
+(assumes 30 days). The fact is, there is no right answer. In the `Dates` module, it gives
+the result of February 28th. How does it figure that out? Consider the classic 7-7-7
+gambling game in casinos.
+
+Now just imagine that instead of 7-7-7, the slots are Year-Month-Day, or in our example, 2014-01-31.
+When you ask to add 1 month to this date, the month slot is incremented, so now we have 2014-02-31.
+Then the day number is checked if it is greater than the last valid day of the new month; if it
+is (as in the case above), the day number is adjusted down to the last valid day (28). What are
+the ramifications with this approach? Go ahead and add another month to our date, `2014-02-28 + Month(1) == 2014-03-28`.
+What? Were you expecting the last day of March? Nope, sorry, remember the 7-7-7 slots. As few
+slots as possible are going to change, so we first increment the month slot by 1, 2014-03-28,
+and boom, we're done because that's a valid date. On the other hand, if we were to add 2 months
+to our original date, 2014-01-31, then we end up with 2014-03-31, as expected. The other ramification
+of this approach is a loss in associativity when a specific ordering is forced (i.e. adding things
+in different orders results in different outcomes). For example:
+
+```jldoctest
+julia> (Date(2014,1,29)+Dates.Day(1)) + Dates.Month(1)
+2014-02-28
+
+julia> (Date(2014,1,29)+Dates.Month(1)) + Dates.Day(1)
+2014-03-01
+```
+
+What's going on there? In the first line, we're adding 1 day to January 29th, which results in
+2014-01-30; then we add 1 month, so we get 2014-02-30, which then adjusts down to 2014-02-28.
+In the second example, we add 1 month *first*, where we get 2014-02-29, which adjusts down to
+2014-02-28, and *then* add 1 day, which results in 2014-03-01. One design principle that helps
+in this case is that, in the presence of multiple Periods, the operations will be ordered by the
+Periods' *types*, not their value or positional order; this means `Year` will always be added
+first, then `Month`, then `Week`, etc. Hence the following *does* result in associativity and
+Just Works:
+
+```jldoctest
+julia> Date(2014,1,29) + Dates.Day(1) + Dates.Month(1)
+2014-03-01
+
+julia> Date(2014,1,29) + Dates.Month(1) + Dates.Day(1)
+2014-03-01
+```
+
+Tricky? Perhaps. What is an innocent `Dates` user to do? The bottom line is to be aware
+that explicitly forcing a certain associativity, when dealing with months, may lead to some unexpected
+results, but otherwise, everything should work as expected. Thankfully, that's pretty much the
+extent of the odd cases in date-period arithmetic when dealing with time in UT (avoiding the "joys"
+of dealing with daylight savings, leap seconds, etc.).
+
+As a bonus, all period arithmetic objects work directly with ranges:
+
+```jldoctest
+julia> dr = Date(2014,1,29):Day(1):Date(2014,2,3)
+Date("2014-01-29"):Day(1):Date("2014-02-03")
+
+julia> collect(dr)
+6-element Vector{Date}:
+ 2014-01-29
+ 2014-01-30
+ 2014-01-31
+ 2014-02-01
+ 2014-02-02
+ 2014-02-03
+
+julia> dr = Date(2014,1,29):Dates.Month(1):Date(2014,07,29)
+Date("2014-01-29"):Month(1):Date("2014-07-29")
+
+julia> collect(dr)
+7-element Vector{Date}:
+ 2014-01-29
+ 2014-02-28
+ 2014-03-29
+ 2014-04-29
+ 2014-05-29
+ 2014-06-29
+ 2014-07-29
+```
+
+## Adjuster Functions
+
+As convenient as date-period arithmetic is, often the kinds of calculations needed on dates
+take on a *calendrical* or *temporal* nature rather than a fixed number of periods. Holidays are
+a perfect example; most follow rules such as "Memorial Day = Last Monday of May", or "Thanksgiving
+= 4th Thursday of November". These kinds of temporal expressions deal with rules relative to the
+calendar, like first or last of the month, next Tuesday, or the first and third Wednesdays, etc.
+
+The `Dates` module provides the *adjuster* API through several convenient methods that
+aid in simply and succinctly expressing temporal rules. The first group of adjuster methods deal
+with the first and last of weeks, months, quarters, and years. They each take a single [`TimeType`](@ref)
+as input and return or *adjust to* the first or last of the desired period relative to the input.
+
+```jldoctest
+julia> Dates.firstdayofweek(Date(2014,7,16)) # Adjusts the input to the Monday of the input's week
+2014-07-14
+
+julia> Dates.lastdayofmonth(Date(2014,7,16)) # Adjusts to the last day of the input's month
+2014-07-31
+
+julia> Dates.lastdayofquarter(Date(2014,7,16)) # Adjusts to the last day of the input's quarter
+2014-09-30
+```
+
+The next two higher-order methods, [`tonext`](@ref), and [`toprev`](@ref), generalize working
+with temporal expressions by taking a `DateFunction` as first argument, along with a starting
+[`TimeType`](@ref). A `DateFunction` is just a function, usually anonymous, that takes a single
+[`TimeType`](@ref) as input and returns a [`Bool`](@ref), `true` indicating a satisfied
+adjustment criterion.
+For example:
+
+```jldoctest
+julia> istuesday = x->Dates.dayofweek(x) == Dates.Tuesday; # Returns true if the day of the week of x is Tuesday
+
+julia> Dates.tonext(istuesday, Date(2014,7,13)) # 2014-07-13 is a Sunday
+2014-07-15
+
+julia> Dates.tonext(Date(2014,7,13), Dates.Tuesday) # Convenience method provided for day of the week adjustments
+2014-07-15
+```
+
+This is useful with the do-block syntax for more complex temporal expressions:
+
+```jldoctest
+julia> Dates.tonext(Date(2014,7,13)) do x
+           # Return true on the 4th Thursday of November (Thanksgiving)
+           Dates.dayofweek(x) == Dates.Thursday &&
+           Dates.dayofweekofmonth(x) == 4 &&
+           Dates.month(x) == Dates.November
+       end
+2014-11-27
+```
+
+The [`Base.filter`](@ref) method can be used to obtain all valid dates/moments in a specified
+range:
+
+```jldoctest
+# Pittsburgh street cleaning; Every 2nd Tuesday from April to November
+# Date range from January 1st, 2014 to January 1st, 2015
+julia> dr = Dates.Date(2014):Day(1):Dates.Date(2015);
+
+julia> filter(dr) do x
+           Dates.dayofweek(x) == Dates.Tue &&
+           Dates.April <= Dates.month(x) <= Dates.Nov &&
+           Dates.dayofweekofmonth(x) == 2
+       end
+8-element Vector{Date}:
+ 2014-04-08
+ 2014-05-13
+ 2014-06-10
+ 2014-07-08
+ 2014-08-12
+ 2014-09-09
+ 2014-10-14
+ 2014-11-11
+```
+
+Additional examples and tests are available in [`stdlib/Dates/test/adjusters.jl`](https://github.com/JuliaLang/julia/blob/master/stdlib/Dates/test/adjusters.jl).
+
+## Period Types
+
+Periods are a human view of discrete, sometimes irregular durations of time. Consider 1 month;
+it could represent, in days, a value of 28, 29, 30, or 31 depending on the year and month context.
+Or a year could represent 365 or 366 days in the case of a leap year. [`Period`](@ref) types are
+simple [`Int64`](@ref) wrappers and are constructed by wrapping any `Int64` convertible type, i.e. `Year(1)`
+or `Month(3.0)`. Arithmetic between [`Period`](@ref) of the same type behave like integers, and
+limited `Period-Real` arithmetic is available.  You can extract the underlying integer with
+[`Dates.value`](@ref).
+
+```jldoctest
+julia> y1 = Dates.Year(1)
+1 year
+
+julia> y2 = Dates.Year(2)
+2 years
+
+julia> y3 = Dates.Year(10)
+10 years
+
+julia> y1 + y2
+3 years
+
+julia> div(y3,y2)
+5
+
+julia> y3 - y2
+8 years
+
+julia> y3 % y2
+0 years
+
+julia> div(y3,3) # mirrors integer division
+3 years
+
+julia> Dates.value(Dates.Millisecond(10))
+10
+```
+
+## Rounding
+
+[`Date`](@ref) and [`DateTime`](@ref) values can be rounded to a specified resolution (e.g., 1
+month or 15 minutes) with [`floor`](@ref), [`ceil`](@ref), or [`round`](@ref):
+
+```jldoctest
+julia> floor(Date(1985, 8, 16), Dates.Month)
+1985-08-01
+
+julia> ceil(DateTime(2013, 2, 13, 0, 31, 20), Dates.Minute(15))
+2013-02-13T00:45:00
+
+julia> round(DateTime(2016, 8, 6, 20, 15), Dates.Day)
+2016-08-07T00:00:00
+```
+
+Unlike the numeric [`round`](@ref) method, which breaks ties toward the even number by default,
+the [`TimeType`](@ref)[`round`](@ref) method uses the `RoundNearestTiesUp` rounding mode. (It's
+difficult to guess what breaking ties to nearest "even" [`TimeType`](@ref) would entail.) Further
+details on the available `RoundingMode` s can be found in the [API reference](@ref stdlib-dates-api).
+
+Rounding should generally behave as expected, but there are a few cases in which the expected
+behaviour is not obvious.
+
+### Rounding Epoch
+
+In many cases, the resolution specified for rounding (e.g., `Dates.Second(30)`) divides evenly
+into the next largest period (in this case, `Dates.Minute(1)`). But rounding behaviour in cases
+in which this is not true may lead to confusion. What is the expected result of rounding a [`DateTime`](@ref)
+to the nearest 10 hours?
+
+```jldoctest
+julia> round(DateTime(2016, 7, 17, 11, 55), Dates.Hour(10))
+2016-07-17T12:00:00
+```
+
+That may seem confusing, given that the hour (12) is not divisible by 10. The reason that `2016-07-17T12:00:00`
+was chosen is that it is 17,676,660 hours after `0000-01-01T00:00:00`, and 17,676,660 is divisible
+by 10.
+
+As Julia [`Date`](@ref) and [`DateTime`](@ref) values are represented according to the ISO 8601
+standard, `0000-01-01T00:00:00` was chosen as base (or "rounding epoch") from which to begin the
+count of days (and milliseconds) used in rounding calculations. (Note that this differs slightly
+from Julia's internal representation of [`Date`](@ref) s using Rata Die notation; but since the
+ISO 8601 standard is most visible to the end user, `0000-01-01T00:00:00` was chosen as the rounding
+epoch instead of the `0000-12-31T00:00:00` used internally to minimize confusion.)
+
+The only exception to the use of `0000-01-01T00:00:00` as the rounding epoch is when rounding
+to weeks. Rounding to the nearest week will always return a Monday (the first day of the week
+as specified by ISO 8601). For this reason, we use `0000-01-03T00:00:00` (the first day of the
+first week of year 0000, as defined by ISO 8601) as the base when rounding to a number of weeks.
+
+Here is a related case in which the expected behaviour is not necessarily obvious: What happens
+when we round to the nearest `P(2)`, where `P` is a [`Period`](@ref) type? In some cases (specifically,
+when `P <: Dates.TimePeriod`) the answer is clear:
+
+```jldoctest
+julia> round(DateTime(2016, 7, 17, 8, 55, 30), Dates.Hour(2))
+2016-07-17T08:00:00
+
+julia> round(DateTime(2016, 7, 17, 8, 55, 30), Dates.Minute(2))
+2016-07-17T08:56:00
+```
+
+This seems obvious, because two of each of these periods still divides evenly into the next larger
+order period. But in the case of two months (which still divides evenly into one year), the answer
+may be surprising:
+
+```jldoctest
+julia> round(DateTime(2016, 7, 17, 8, 55, 30), Dates.Month(2))
+2016-07-01T00:00:00
+```
+
+Why round to the first day in July, even though it is month 7 (an odd number)? The key is that
+months are 1-indexed (the first month is assigned 1), unlike hours, minutes, seconds, and milliseconds
+(the first of which are assigned 0).
+
+This means that rounding a [`DateTime`](@ref) to an even multiple of seconds, minutes, hours,
+or years (because the ISO 8601 specification includes a year zero) will result in a [`DateTime`](@ref)
+with an even value in that field, while rounding a [`DateTime`](@ref) to an even multiple of months
+will result in the months field having an odd value. Because both months and years may contain
+an irregular number of days, whether rounding to an even number of days will result in an even
+value in the days field is uncertain.
+
+See the [API reference](@ref stdlib-dates-api) for additional information
+on methods exported from the `Dates` module.
+
+# [API reference](@id stdlib-dates-api)
+
+## Dates and Time Types
+
+```@docs
+Dates.Period
+Dates.CompoundPeriod
+Dates.Instant
+Dates.UTInstant
+Dates.TimeType
+Dates.DateTime
+Dates.Date
+Dates.Time
+Dates.TimeZone
+Dates.UTC
+```
+
+## Dates Functions
+
+```@docs
+Dates.DateTime(::Int64, ::Int64, ::Int64, ::Int64, ::Int64, ::Int64, ::Int64)
+Dates.DateTime(::Dates.Period)
+Dates.DateTime(::Function, ::Any...)
+Dates.DateTime(::Dates.TimeType)
+Dates.DateTime(::AbstractString, ::AbstractString)
+Dates.format(::Dates.TimeType, ::AbstractString)
+Dates.DateFormat
+Dates.@dateformat_str
+Dates.DateTime(::AbstractString, ::Dates.DateFormat)
+Dates.Date(::Int64, ::Int64, ::Int64)
+Dates.Date(::Dates.Period)
+Dates.Date(::Function, ::Any, ::Any, ::Any)
+Dates.Date(::Dates.TimeType)
+Dates.Date(::AbstractString, ::AbstractString)
+Dates.Date(::AbstractString, ::Dates.DateFormat)
+Dates.Time(::Int64::Int64, ::Int64, ::Int64, ::Int64, ::Int64)
+Dates.Time(::Dates.TimePeriod)
+Dates.Time(::Function, ::Any...)
+Dates.Time(::Dates.DateTime)
+Dates.now()
+Dates.now(::Type{Dates.UTC})
+Base.eps(::Union{Type{DateTime}, Type{Date}, Type{Time}, TimeType})
+```
+
+### Accessor Functions
+
+```@docs
+Dates.year
+Dates.month
+Dates.week
+Dates.day
+Dates.hour
+Dates.minute
+Dates.second
+Dates.millisecond
+Dates.microsecond
+Dates.nanosecond
+Dates.Year(::Dates.TimeType)
+Dates.Month(::Dates.TimeType)
+Dates.Week(::Dates.TimeType)
+Dates.Day(::Dates.TimeType)
+Dates.Hour(::DateTime)
+Dates.Minute(::DateTime)
+Dates.Second(::DateTime)
+Dates.Millisecond(::DateTime)
+Dates.Microsecond(::Dates.Time)
+Dates.Nanosecond(::Dates.Time)
+Dates.yearmonth
+Dates.monthday
+Dates.yearmonthday
+```
+
+### Query Functions
+
+```@docs
+Dates.dayname
+Dates.dayabbr
+Dates.dayofweek
+Dates.dayofmonth
+Dates.dayofweekofmonth
+Dates.daysofweekinmonth
+Dates.monthname
+Dates.monthabbr
+Dates.daysinmonth
+Dates.isleapyear
+Dates.dayofyear
+Dates.daysinyear
+Dates.quarterofyear
+Dates.dayofquarter
+```
+
+### Adjuster Functions
+
+```@docs
+Base.trunc(::Dates.TimeType, ::Type{Dates.Period})
+Dates.firstdayofweek
+Dates.lastdayofweek
+Dates.firstdayofmonth
+Dates.lastdayofmonth
+Dates.firstdayofyear
+Dates.lastdayofyear
+Dates.firstdayofquarter
+Dates.lastdayofquarter
+Dates.tonext(::Dates.TimeType, ::Int)
+Dates.toprev(::Dates.TimeType, ::Int)
+Dates.tofirst
+Dates.tolast
+Dates.tonext(::Function, ::Dates.TimeType)
+Dates.toprev(::Function, ::Dates.TimeType)
+```
+
+### Periods
+
+```@docs
+Dates.Period(::Any)
+Dates.CompoundPeriod(::Vector{<:Dates.Period})
+Dates.value
+Dates.default
+```
+
+### Rounding Functions
+
+`Date` and `DateTime` values can be rounded to a specified resolution (e.g., 1 month or 15 minutes)
+with `floor`, `ceil`, or `round`.
+
+```@docs
+Base.floor(::Dates.TimeType, ::Dates.Period)
+Base.ceil(::Dates.TimeType, ::Dates.Period)
+Base.round(::Dates.TimeType, ::Dates.Period, ::RoundingMode{:NearestTiesUp})
+```
+
+Most `Period` values can also be rounded to a specified resolution:
+
+```@docs
+Base.floor(::Dates.ConvertiblePeriod, ::T) where T <: Dates.ConvertiblePeriod
+Base.ceil(::Dates.ConvertiblePeriod, ::Dates.ConvertiblePeriod)
+Base.round(::Dates.ConvertiblePeriod, ::Dates.ConvertiblePeriod, ::RoundingMode{:NearestTiesUp})
+```
+
+The following functions are not exported:
+
+```@docs
+Dates.floorceil
+Dates.epochdays2date
+Dates.epochms2datetime
+Dates.date2epochdays
+Dates.datetime2epochms
+```
+
+### Conversion Functions
+
+```@docs
+Dates.today
+Dates.unix2datetime
+Dates.datetime2unix
+Dates.julian2datetime
+Dates.datetime2julian
+Dates.rata2datetime
+Dates.datetime2rata
+```
+
+### Constants
+
+Days of the Week:
+
+| Variable    | Abbr. | Value (Int) |
+|:----------- |:----- |:----------- |
+| `Monday`    | `Mon` | 1           |
+| `Tuesday`   | `Tue` | 2           |
+| `Wednesday` | `Wed` | 3           |
+| `Thursday`  | `Thu` | 4           |
+| `Friday`    | `Fri` | 5           |
+| `Saturday`  | `Sat` | 6           |
+| `Sunday`    | `Sun` | 7           |
+
+Months of the Year:
+
+| Variable    | Abbr. | Value (Int) |
+|:----------- |:----- |:----------- |
+| `January`   | `Jan` | 1           |
+| `February`  | `Feb` | 2           |
+| `March`     | `Mar` | 3           |
+| `April`     | `Apr` | 4           |
+| `May`       | `May` | 5           |
+| `June`      | `Jun` | 6           |
+| `July`      | `Jul` | 7           |
+| `August`    | `Aug` | 8           |
+| `September` | `Sep` | 9           |
+| `October`   | `Oct` | 10          |
+| `November`  | `Nov` | 11          |
+| `December`  | `Dec` | 12          |
+
+```@meta
+DocTestSetup = nothing
+```