Undocumented core behaviour

[LeXofLeviafan]

As discussed here, some behaviour of buku doesn't seem to be documented for users (in the mentioned case it's rejecting duplicate URLs, both on creation and on edit).

It'd be a good idea to double-check which core behaviour is undocumented and rectify said lack of documentation.

[jarun]

@rachmadaniHaryono please take a call.

[LeXofLeviafan]

…Incidentally, I've been wondering: why does add_rec() (also get_rec_id() etc) return -1 on failure (instead of None)? Python is not C so None is always a valid return value, None is basically meant for this kind of purpose, and the row numbers start with 1 so returning a falsey value on failure would make the success checks more natural (i.e. if buku.add_rec(…))… and even the explicit value comparison becomes more transparent (is None instead of == -1).

[jarun]

I am fine with returning None.

[LeXofLeviafan]

…If there's no objections, I'll create a separate ticket for it. I believe it would be an improvement for the library API.

(…Incidentally, is it documented at all? Seems like a logical thing to do considering it's already usable as a library – that's how it's used in bukuserver :smile:)

[LeXofLeviafan]

…Now that I've looked through the code to check which methods return -1, I have another question :sweat_smile:

Why does the immutable parameter encountered in some methods (which is functionally a boolean) have an integer type? It doesn't seem consistent either – sometimes the "false" value is 0, and sometimes it's -1…

[LeXofLeviafan]

(…Incidentally, is [the library API] documented at all? Seems like a logical thing to do considering it's already usable as a library – that's how it's used in bukuserver smile)

…Oh, it seems to be documented after all. Although, why isn't this API documentation mentioned on either PyPI page, GitHub readme, nor even the respective project wiki page?

[rachmadaniHaryono]

readthedocs page just recently fixed but more non code related docs go to wiki

https://github.com/jarun/buku/pull/579

https://github.com/jarun/buku/pull/575

why isn't this API documentation mentioned on either PyPI page

this should be added as task before release

• mention buku readthedocs to readme
• add buku readthedocs to setup.py
• maybe move from wiki to readthedocs (see below for more)

i think there should be only one place for docs but i'm not good enough with either docs or sphinx

maybe on each wiki page add something like this after DATE this page is not updated, please see RTD_LINK

[LeXofLeviafan]

You can host a static github.io site for the project (a dedicated branch can be made for it if you don't want it to affect master). It can even be generated on commit (so automatically generated documentation is not out of the question).

Still, regardless of readthedocs state, the PyPI page should always be up-to-date as it's the go-to place for Python package information (though I'm guessing it's updated directly from the readme). And wherever you decide the API docs should be hosted, they still should be visibly linked to for the information about using buku as a library to be accessible for potential users.