Documentation update (JuliaTime#189)

* Add API documentation

* Docs deploy script uses make.jl

* Update to Documenter 0.22

* Add docs/Manifest.toml

.gitignore

@@ -10,7 +10,12 @@ deps/local
 !deps/local/windowsZones.xml
 deps/active_version
 test/tzsource
+docs/build
 
 # PkgBenchmark
 benchmark/.results
 benchmark/.tune.jld
+
+# Pkg
+deps/build.log
+/Manifest.toml

docs/Manifest.toml

@@ -0,0 +1,134 @@
+[[Base64]]
+uuid = "2a0f44e3-6c83-55bd-87e4-b1978d98bd5f"
+
+[[BinaryProvider]]
+deps = ["Libdl", "Pkg", "SHA", "Test"]
+git-tree-sha1 = "055eb2690182ebc31087859c3dd8598371d3ef9e"
+uuid = "b99e7846-7c00-51b0-8f62-c81ae34c0232"
+version = "0.5.3"
+
+[[Compat]]
+deps = ["Base64", "Dates", "DelimitedFiles", "Distributed", "InteractiveUtils", "LibGit2", "Libdl", "LinearAlgebra", "Markdown", "Mmap", "Pkg", "Printf", "REPL", "Random", "Serialization", "SharedArrays", "Sockets", "SparseArrays", "Statistics", "Test", "UUIDs", "Unicode"]
+git-tree-sha1 = "84aa74986c5b9b898b0d1acaf3258741ee64754f"
+uuid = "34da2185-b29b-5c13-b0c7-acf172513d20"
+version = "2.1.0"
+
+[[Dates]]
+deps = ["Printf"]
+uuid = "ade2ca70-3891-5945-98fb-dc099432e06a"
+
+[[DelimitedFiles]]
+deps = ["Mmap"]
+uuid = "8bb1440f-4735-579b-a4ab-409b98df4dab"
+
+[[Distributed]]
+deps = ["LinearAlgebra", "Random", "Serialization", "Sockets"]
+uuid = "8ba89e20-285c-5b6f-9357-94700520ee1b"
+
+[[DocStringExtensions]]
+deps = ["LibGit2", "Markdown", "Pkg", "Test"]
+git-tree-sha1 = "4d30e889c9f106a51ffa4791a88ffd4765bf20c3"
+uuid = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
+version = "0.7.0"
+
+[[Documenter]]
+deps = ["Base64", "DocStringExtensions", "InteractiveUtils", "JSON", "LibGit2", "Logging", "Markdown", "Pkg", "REPL", "Random", "Test", "Unicode"]
+git-tree-sha1 = "e09c7cbf0192113723bc3ba2e736652ede46d516"
+uuid = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+version = "0.22.0"
+
+[[EzXML]]
+deps = ["BinaryProvider", "Libdl", "Pkg", "Printf", "Test"]
+git-tree-sha1 = "ad00b79cca4bb3eabb4209217859c553af4401f5"
+uuid = "8f5d6c58-4d21-5cfd-889c-e3ad7ee6a615"
+version = "0.9.1"
+
+[[InteractiveUtils]]
+deps = ["LinearAlgebra", "Markdown"]
+uuid = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
+
+[[JSON]]
+deps = ["Dates", "Distributed", "Mmap", "Sockets", "Test", "Unicode"]
+git-tree-sha1 = "1f7a25b53ec67f5e9422f1f551ee216503f4a0fa"
+uuid = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
+version = "0.20.0"
+
+[[LibGit2]]
+uuid = "76f85450-5226-5b5a-8eaa-529ad045b433"
+
+[[Libdl]]
+uuid = "8f399da3-3557-5675-b5ff-fb832c97cbdb"
+
+[[LinearAlgebra]]
+deps = ["Libdl"]
+uuid = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+
+[[Logging]]
+uuid = "56ddb016-857b-54e1-b83d-db4d58db5568"
+
+[[Markdown]]
+deps = ["Base64"]
+uuid = "d6f4376e-aef5-505a-96c1-9c027394607a"
+
+[[Mmap]]
+uuid = "a63ad114-7e13-5084-954f-fe012c677804"
+
+[[Mocking]]
+deps = ["Compat", "Dates"]
+git-tree-sha1 = "4bf69aaf823b119b034e091e16b18311aa191663"
+uuid = "78c3b35d-d492-501b-9361-3d52fe80e533"
+version = "0.5.7"
+
+[[Pkg]]
+deps = ["Dates", "LibGit2", "Markdown", "Printf", "REPL", "Random", "SHA", "UUIDs"]
+uuid = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"
+
+[[Printf]]
+deps = ["Unicode"]
+uuid = "de0858da-6303-5e67-8744-51eddeeeb8d7"
+
+[[REPL]]
+deps = ["InteractiveUtils", "Markdown", "Sockets"]
+uuid = "3fa0cd96-eef1-5676-8a61-b3b8758bbffb"
+
+[[Random]]
+deps = ["Serialization"]
+uuid = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
+
+[[SHA]]
+uuid = "ea8e919c-243c-51af-8825-aaa63cd721ce"
+
+[[Serialization]]
+uuid = "9e88b42a-f829-5b0c-bbe9-9e923198166b"
+
+[[SharedArrays]]
+deps = ["Distributed", "Mmap", "Random", "Serialization"]
+uuid = "1a1011a3-84de-559e-8e89-a11a2f7dc383"
+
+[[Sockets]]
+uuid = "6462fe0b-24de-5631-8697-dd941f90decc"
+
+[[SparseArrays]]
+deps = ["LinearAlgebra", "Random"]
+uuid = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
+
+[[Statistics]]
+deps = ["LinearAlgebra", "SparseArrays"]
+uuid = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
+
+[[Test]]
+deps = ["Distributed", "InteractiveUtils", "Logging", "Random"]
+uuid = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+
+[[TimeZones]]
+deps = ["Dates", "EzXML", "Mocking", "Printf", "Serialization", "Unicode"]
+path = ".."
+uuid = "f269a46b-ccf7-5d73-abea-4c690281aa53"
+version = "0.8.5+"
+
+[[UUIDs]]
+deps = ["Random"]
+uuid = "cf7118a7-6976-5b1a-9a39-7adc72f591a4"
+
+[[Unicode]]
+uuid = "4ec0a83e-493e-50e2-b9ac-8f72acf5a8f5"

docs/Project.toml

@@ -1,5 +1,6 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+TimeZones = "f269a46b-ccf7-5d73-abea-4c690281aa53"
 
 [compat]
-Documenter = "~0.20"
+Documenter = "~0.22"

docs/deploy.jl

@@ -1,17 +1,5 @@
-using Documenter, TimeZones
+using Documenter
 
-makedocs(
-    sitename="TimeZones.jl",
-    pages = [
-        "Introduction" => "index.md",
-        "Types" => "types.md",
-        "Converting" => "conversions.md",
-        "Arithmetic" => "arithmetic.md",
-        "Rounding" => "rounding.md",
-        "Current Time" => "current.md",
-        "Frequently Asked Questions" => "faq.md",
-    ],
-    doctest=false,
-)
+include("make.jl")
 
 deploydocs(repo="github.com/JuliaTime/TimeZones.jl.git")

docs/make.jl

@@ -1,7 +1,8 @@
-using Documenter, TimeZones
+using Dates, Documenter, TimeZones
 
 makedocs(
-    sitename="TimeZones.jl",
+    modules=[TimeZones],
+    format = Documenter.HTML(prettyurls = get(ENV, "CI", nothing) == "true"),
     pages = [
         "Introduction" => "index.md",
         "Types" => "types.md",
@@ -10,9 +11,11 @@ makedocs(
         "Rounding" => "rounding.md",
         "Current Time" => "current.md",
         "Frequently Asked Questions" => "faq.md",
+        "API – Public" => "api-public.md",
+        "API – Private" => "api-private.md",
     ],
-    html_prettyurls=false,  # makes local builds work
+    sitename="TimeZones.jl",
+    checkdocs=:exports,
     linkcheck=true,
-    linkcheck_ignore=[r"^ftp://.*"],
     strict=true,
 )

docs/src/api-private.md

@@ -0,0 +1,44 @@
+# TimeZones Internal API
+
+```@meta
+DocTestSetup = quote
+    using TimeZones
+end
+```
+
+## TZData
+
+```@docs
+TimeZones.TZData.tzdata_url
+TimeZones.TZData.tzdata_download
+TimeZones.TZData.isarchive
+TimeZones.TZData.readarchive
+TimeZones.TZData.extract
+TimeZones.TZData.tzdata_version_dir
+TimeZones.TZData.tzdata_version_archive
+TimeZones.TZData.read_news
+TimeZones.TZData.compile!
+TimeZones.TZData.tryparse_dayofmonth
+TimeZones.TZData.order_rules
+```
+
+## Interpretation
+
+```@docs
+TimeZones.transition_range
+TimeZones.interpret
+TimeZones.shift_gap
+TimeZones.first_valid
+TimeZones.last_valid
+```
+
+## Etc.
+
+```@docs
+TimeZones.UTCOffset
+TimeZones.@optional
+TimeZones.read_tzfile
+TimeZones.parse_tz_format
+hash(::ZonedDateTime, ::UInt)
+Dates.guess(::ZonedDateTime, ::ZonedDateTime, ::Any)
+```

docs/src/api-public.md

@@ -0,0 +1,75 @@
+# TimeZones Public API
+
+```@meta
+DocTestSetup = quote
+    using TimeZones
+end
+```
+
+## TimeZone
+
+```@docs
+TimeZone(::AbstractString)
+@tz_str
+localzone
+FixedTimeZone
+VariableTimeZone
+TimeZones.build
+```
+
+## Legacy Time Zones
+
+```@docs
+TimeZone(::AbstractString, ::TimeZones.Class)
+TimeZones.Class
+istimezone
+```
+
+## ZonedDateTime
+
+```@docs
+ZonedDateTime
+ZonedDateTime(::DateTime, ::VariableTimeZone)
+ZonedDateTime(::DateTime, ::VariableTimeZone, ::Integer)
+ZonedDateTime(::DateTime, ::VariableTimeZone, ::Bool)
+astimezone
+TimeZones.timezone(::ZonedDateTime)
+TimeZones.utc
+TimeZones.localtime
+DateTime(::ZonedDateTime)
+```
+
+## Current Time
+
+```@docs
+now(::TimeZone)
+today(::TimeZone)
+todayat
+```
+
+## Rounding
+
+```@docs
+round(::ZonedDateTime, ::Period)
+floor(::ZonedDateTime, ::Period)
+ceil(::ZonedDateTime, ::Period)
+```
+
+## Exceptions
+
+```@docs
+NonExistentTimeError
+AmbiguousTimeError
+UnhandledTimeError
+```
+
+## Discovery
+
+```@docs
+timezone_names
+all_timezones
+timezones_from_abbr
+timezone_abbrs
+next_transition_instant
+show_next_transition
+```

docs/src/conversions.md

@@ -53,7 +53,7 @@ julia> ZonedDateTime("2015-03-30+02:00", df)
 
 ## Formatting strings
 
-Formatting a `ZonedDateTime` as a string also extends the functionality provided by `Base.Dates`. The `TimeZones` package adds the new formatting character codes `z` and `Z` to the list of available [formatting character codes](https://docs.julialang.org/en/v1/stdlib/Dates/#Dates.format-Tuple{TimeType,AbstractString}):
+Formatting a `ZonedDateTime` as a string also extends the functionality provided by `Base.Dates`. The `TimeZones` package adds the new formatting character codes `z` and `Z` to the list of available [formatting character codes](https://docs.julialang.org/en/v1/stdlib/Dates/#Dates.DateFormat):
 
 | Code | Examples             | Comment                                          |
 |:-----|:---------------------|:-------------------------------------------------|

src/local.jl

@@ -155,7 +155,8 @@ const TZ_REGEX = r"""
     parse_tz_format(str) -> TimeZone
 
 Parse the time zone format typically provided via the "TZ" environment variable. Details on
-the format can be found under the [tzset man page](http://linux.die.net/man/3/tzset).
+the format can be found under the man page for
+[tzset](http://man7.org/linux/man-pages/man3/tzset.3.html).
 
 Currently this function handles only the first format which is a fixed time zone without
 daylight saving time.

src/tzfile.jl

@@ -19,7 +19,7 @@ end
 
 Read the content of an I/O stream and process it as a
 [POSIX tzfile](http://man7.org/linux/man-pages/man5/tzfile.5.html). The returned
-`TimeZone` will be given the suppiled name `name` unless a `FixedTimeZone` is returned.
+`TimeZone` will be given the supplied name `name` unless a `FixedTimeZone` is returned.
 """
 function read_tzfile(io::IO, name::AbstractString)
     version, tz = read_tzfile_internal(io, name)