Add API reference - Githubissues

sdispater / pendulum

Python datetimes made easy

https://pendulum.eustace.io

MIT License

6.25k stars 387 forks source link

Add API reference #199

Open xmo-odoo opened 6 years ago

xmo-odoo commented 6 years ago

The current documentation is basically a guide, showing examples of a bunch of methods but not actually documenting many (any?) of them. For instance Pendulum.next is mentioned/used several times but never actually explained/documented.

Now technically Pendulum kinda sorta has a reference but:

it's not linked anywhere on the website
if one thinks of visiting /docs/api, only the date object is linked (incidentally the overall API surface looks small enough that all objects could probably be documented together, especially if the apidoc skipped a few useless methods like Pendulum.copy)
the theme used on the website basically breaks autodoc
some docstrings are present where unnecessary (e.g. "seconds: the number of seconds") but missing where they'd be useful (e.g. what is fold in the Pendulum constructor, is tzinfo UTC or whatever the machine's timezone — which just happens to be UTC on the one building the official doc, …)

sdispater commented 6 years ago

The next() method and all its parameters are displayed in the doc. It's not an API reference but it displays what to expect from the method.

The API reference on the website is not to be used. This is just some leftovers of a previous attempt.

austinbutler commented 5 years ago

Another one that seems undocumented is replace, which also has a fold argument. Aside from the support for the fold argument and tz argument replaced with tzinfo, replace seems largely similar to set.

As for fold itself, I do see it in the Using the timezone library directly section of the documentation, which says it's actually from Python's native datetime in 3.6+. That lead me to this helpful Stack Overflow answer, which finally leads to PEP 495.

wsw70 commented 5 years ago

@xmo-odoo: the link to the kinda sorta reference is broken.

xmo-odoo commented 5 years ago

@wsw70 I expect it was removed following

The API reference on the website is not to be used. This is just some leftovers of a previous attempt.

wsw70 commented 5 years ago

@xmo-odoo : thanks. I found your question after raising mine (https://github.com/sdispater/pendulum/issues/399) as they are quite related

metatooling commented 4 years ago

Added an auto-updating doc using sphinx-apidoc, hosted at https://pendulum.readthedocs.io/. Let me know if there's an official API reference that should be hosted there.

sdispater commented 4 years ago

@metatooling Thanks for taking the time to do that but I would prefer not to have a documentation that is not official on RTD since that can confuse users. The only reference for the documentation should only be on the official website.

metatooling commented 4 years ago

Sure, I don't want to confuse anybody. I've cleaned it up a bit, moved it it to pendulum-unofficial and added a more prominent disclaimer at the top of every page.

The reason I made it is that I find Sphinx API reference easier to use than help(pendulum.DateTime) while I'm working. I believe I have it configured to update after every change to sdispater/pendulum's master branch.

If you'd rather there be no API reference until an official one is released, I'll take it down and only use it locally.

gwerbin commented 4 years ago

Is there any technical obstacle to releasing an API reference? I'd be happy to help make this possible. I think this is the only major Python library I've used without any kind of API reference at all.