Add documentation

[pganssle]

This is a first draft of the module documentation.

Minimum requirements:

• Documentation for the warning in Add further validation to keys #46
• Documentation of the pickling behavior
• Documentation of the string representations

Deferred for later expansion:

• A section on the cache behavior and how it affects the semantics of datetimes
• Documentation of the behavior during data updates (though that may be subsumed into the section on the cache behavior).
• Set up some sort of docs-building CI

I've set up RTD to render the documentation here; the main documentation is in the module documentation.

Closes #35.

[webknjaz]

This renders as \* which is probably not what you want.

Suggested change

	.. classmethod:: ZoneInfo.clear_cache(\*, only_keys=None)
	.. classmethod:: ZoneInfo.clear_cache(*, only_keys=None)

[pganssle]

Good catch.

This is actually a temporary measure to work around this issue in my local editor: marshallward/vim-restructuredtext#14

I planned to remove it before merging, but I would probably forget, so I'm going to leave this unresolved as a reminder 😃

[pganssle]

Thanks for the reviews @webknjaz and @dereksantibanez!

[pganssle]

Good catch.

This is actually a temporary measure to work around this issue in my local editor: marshallward/vim-restructuredtext#14

I planned to remove it before merging, but I would probably forget, so I'm going to leave this unresolved as a reminder 😃

[Zac-HD]

Consider adding a link to e.g. http://cldr.unicode.org/translation/timezones ?

[pganssle]

I'm mildly concerned that there's no https version of that.

I think I'm going to wait until the second pass to add in third-party links. I'd also like to add links to relevant and/or interesting documentation about the IANA zones themselves, but I consider that stuff "nice to have".

[Zac-HD]

For Hypothesis we've used the extlinks extension to create a :pypi: role:

# A dictionary of external sites, mapping aliases to a base URL and a prefix.  
# See http://sphinx-doc.org/ext/extlinks.html and use as e.g. :pypi:`tzdata`
extlinks = {
    "pypi": ("https://pypi.org/project/%s", ""),
    "bpo": ("https://bugs.python.org/issue%s", "bpo-"),
}

Which is a pattern that might also be useful for CPython docs.

[webknjaz]

+1 we also use this in CherryPy/Cheroot for GitHub links. But I guess it's fine for this specific repo to not be ideal.

[pganssle]

Yeah, I like this a lot. Maybe we should open a bpo for it? I'd have to replace all the :pypi: links manually when moving this into the standard library if I did that here.

[mahmoud]

Nice work! Had a couple thoughts/questions, above. Excited to see this in the stdlib!

[tmontes]

(following up on @pganssle's tweet, calling for more eyes)

I read this a few times and it is still not 100% clear to me:

• First it states that "It must consist of only absolute rather than relative paths".
• Then adds "Relative components (...) will not be used," which I found confusing and in conflict with the previous statement.
• On top of than it continues with "but otherwise the behavior when a relative path is specified is implementation-defined". Isn't this zoneinfo a single-implementation for CPython's Standard Library? Or does it refer to 3rd party implementations that may interpret PYTHONTZPATH differently?

I have no particular suggestions other than sharing my difficulty in getting a clear picture.

[pganssle]

The idea is that you're only supposed to put absolute paths in there, and this section is answering the question of "what happens if you put something that is not an absolute path there"? The answer is that you'll either get a warning, an exception or no message, but in no cases will zoneinfo.TZPATH contain a relative path.

Yeah, there's really only one implementation here, but CPython is the reference implementation for the standard library, and other implementations like PyPy may have different behavior. Though practically speaking "implementation-defined" may also mean "we could change this later, since you weren't supposed to be counting on it anyway."

[tmontes]

(my last 2c)

The complementary statement on constructing ZoneInfo objects felt a bit alien and, to me, is not totally clear. What is meant by the "join" verb? My mind takes me to a SQL-esque join, where the key is matched/looked-up against each TZPATH entry. Is that it?

(parting words: thanks for you work on this!)

[mahmoud]

I'd assumed os.path.join was the inspiration.

[pganssle]

Yeah, it's basically, "We'll treat the key as a relative path in each of the TZPATH entries." I don't know of a better term for this other than "join".

[tmontes]

Ok, I now undertand it -- but had to go looking at the contents of the "tzdata dirs". The "join" is in the sense of os.path.join, thus! :-) Thanks.

[pganssle]

OK, I think this is as good as it needs to be for the moment. Thanks for the reviews everyone!