Documentation reflects the current git head, not the latest release (and that's confusing)

[Thompsonmina]

I inspected the source for the notion client i installed and only the pick function is contained in the helpers module even though the documentation says that get_id and get_url are supposed to be included

[ramnes]

Yeah, we should probably deploy the documentation of the latest released version and the one of the current git head in two different places. PR welcome!

Pinging this. Docs are still behind latest version.

[ramnes]

What? The issue here is the exact opposite, i.e. the documentation is always ahead of the latest version, not behind. Did you see something that's actually released but not part of the documentation?

[wangdong2023]

Hi, I'm new here. For me the document is missing as here, where can I find more docs?

[ramnes]

https://ramnes.github.io/notion-sdk-py/

[nat-n]

Yeah, we should probably deploy the documentation of the latest released version and the one of the current git head in two different places. PR welcome!

I'd suggest two alternate approaches that might be neater than managing multiple documentation deployments:

1. maintain a development branch separate from main. So documentation changes for existing features or urgent bug fixes can merge straight to main, but everything else merges to the development branch, which is only merged to main as part of the release process.
2. Enforce conventional commits to main and automate creating a new release for every functional change.

WDYT?

[ramnes]

Do you suggest the two together specifically or one or the other works in your mind?

I'm not too keen on conventional commits, but I don't really mind a develop branch. Actually, I used to have one in many of my projects at some point, but with the advent of CI/CD, I found it to be a useless step, so I'm not too sure I want to come back to such a setup.

I do agree that deploying in two different places is probably overkill thought. I just took a quick look, and implementing versions within the docs is a very common use case. Material for MkDocs even has a documentation page about it: https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/

This is most likely what I'd like to see in a PR. :)