search

lark-parser / lark

Lark is a parsing toolkit for Python, built with a focus on ergonomics, performance and modularity.
MIT License
4.75k stars 401 forks source link

Docs are ahead of stable release #1301

Closed nat-n closed 1 year ago

nat-n commented 1 year ago

Hello, firstly thanks for for maintaining this fantastic library.

I've just spent some time trying to work out how to get the strict mode to work as described in the docs, until I realised it hasn't been released yet! Now maybe I should have noticed that latest != stable, but this is easy to miss.

Of course now I know I can get what I want by running: pip install pip install git+https://github.com/lark-parser/lark interegular, but 15 minutes ago I was starting to suspect a regression in lark was to blame.

May I suggest that it would be preferable to avoid this kind of situation (especially for new users like me), by only publishing docs for releases?

One approach would be to only publish docs from the main branch, and do development on a separate development branch which only merges to main for releases. Another approach would be to keep development on main, but only build docs from tagged commits (releases). There are various similar approaches and tradeoffs to consider, but I think it's worth thinking about.

Also, it looks like this project is quite active, but the last release was more than 6 months ago. I suspect getting features out more regularly would be valuable to users, and this is another a reason to consider improving the branching/automation model.

I may be able to help implement a solution if there's agreement on the direction :)

erezsh commented 1 year ago

Hello,

Thanks for the compliments!

First of all, you're right that it's been too long without a release! I just released 1.1.6.

I also agree that ideally the docs should be synced to the right version. I'm okay with moving development to a "dev" branch, and merging it only on release. Especially if the dev branch will build to its own branch of documentation, so we can point early adopters there for the latest docs.

erezsh commented 1 year ago

So, turns out all I had to do is change the default build from latest to stable: https://docs.readthedocs.io/en/stable/versions.html

Things should now work as expected, without having to change our merging process.