Add documentation to source with examples about notion-sdk-py HOT 9 CLOSED

once we have a package installed with docs, we don't need to go to web to browse the docs.

What do you mean by installed? I don't think anyone bundles the docs in PyPI releases.

What I was meaning, initially, is use docstrings in code. But that's ok, what metters is the avaiability and content of docs and examples by themselves and not where they are placed. Well, I'm a bit old and still have this habit of read help () before search the web. :P

So again, I don't really care if it's in the code or not, all I care about is that we end up with some kind of documentation. Any PR (or other form of work!) going in that direction will be considered thoroughly. :)

Sure. I really like your suggestion to start with a Wiki, so I wrote an example here https://github.com/ramnes/notion-sdk-py/wiki/Examples .

A review would appreciated. :)

Regards.

from notion-sdk-py.

Awesome, thanks! I've modified a few bits, like .json() that is not needed anymore with 0.4.0. :)

from notion-sdk-py.

I just enabled the wiki here, does that sound like a reasonable option to you? Do you want to add the examples?

from notion-sdk-py.

gh does not have PRs for wiki. If you allow non-collaborators to edit, then anybody can write anything.

what about a docs/ directory, which is common for all major python wrappers for apis ? the docs could be published to gh pages. (via gh action)

sphinx is too complicated. mkdocs is simple to setup.

from notion-sdk-py.

To be honest I really don't mind one or the other! Feel free to either add examples inside the wiki, or to open a PR that setups mkdocs and adds documentation content, although I'm more interested in the content than the mkdocs setup. And don't worry, I'll rationalize later if you guys end up doing both. :)

from notion-sdk-py.

Whats the eta for #10 ? i think we should write the docs after this is merged

from notion-sdk-py.

I don't have an answer for that, I'm sorry. :)

from notion-sdk-py.

I'm OK with starting with a Wiki with examples. May be after #10 we could starting with some docs.

BTW, one advantage to docs inside code is, once we have a package installed with docs, we don't need to go to web to browse the docs. Another point is that the Wiki could be outdated, while the docs should follow the code behaviour.

from notion-sdk-py.

once we have a package installed with docs, we don't need to go to web to browse the docs.

What do you mean by installed? I don't think anyone bundles the docs in PyPI releases.

Another point is that the Wiki could be outdated, while the docs should follow the code behaviour.

This used to be one of my arguments in favor of having docs in the code as well. But then the real world told me that if developers don't want to write docs, well... they won't, no matter where the documentation is. :) From what I've seen so far, most people are either into documentation, or code, but rarely both. And when people happen to like both, they usually don't mind where the documentation is.

So again, I don't really care if it's in the code or not, all I care about is that we end up with some kind of documentation. Any PR (or other form of work!) going in that direction will be considered thoroughly. :)

from notion-sdk-py.