search

enkore / i3pystatus

A complete replacement for i3status
https://i3pystatus.readthedocs.io/
MIT License
445 stars 188 forks source link

Confusion about Docs, PIP and Releases #782

Closed daryltucker closed 4 years ago

daryltucker commented 4 years ago

Thanks for taking time to build something such as i3pystatus. It's improved my every day use of i3. When trying to create configurations, I often pull up the ReadTheDocs documentation to help me get things correct. Confusingly to me, the latest version does not reflect/match the 3.35 documentation. My expectation is that these would match up, as 3.35 is the latest release, while the master branch might be used to document an unstable/beta version. This could be a misunderstanding on my part, but I think this will at least make sense as confusing.

As a concrete example, I am trying to use the pulseaudio module:

The latest docs suggest I can define which sink to show.

status.register(
    "pulseaudio",
    sink="alsa_output.pci-0000_00_1b.0.analog-surround-21",
    format=" {volume}%",
    format_muted=" MUTED"
)

But actually, the latest version, 3.35 errors saying "Module 'PulseAudio': invalid option 'sink'". Documentation for both 3.35 and stable both show the correct documentation, which omits the unavailable sink option.

Personally, I'd like to see a version 3.36 available in PIP, but I understand that'd require proving it stable and maybe there are issues that are preventing such a release. The README does provide instructions on how to install via pip + git, but I wanted to bring this up as there are some people who prefer to rely on pip without additional repos, etc.

Regardless of source (pip repos, or github), when the user installs i3pystatus or performs an upgrade, they should be then be on the latest version, and when going to ReadTheDocs, the default, latest version documentation should match this installed version. This way, when a user upgrades, and i3pystatus reports an error, they can read the documentation and make fixes.

Thank you again for this project and your consideration.

enkore commented 4 years ago

Hi, as you found out, i3pystatus used to make regular releases, but we eventually stopped doing that. There's nothing wrong about using one of the older releases (if things work for you), but the "default version" is the rolling-release "current" branch directly from git. On readthedocs you can switch to the 3.35 documentation using the version select in the bottom right corner (needs Javascript), or this link. It's still there, just hasn't been the default for a while.

terminalmage commented 4 years ago

@enkore How and how often do the docs get updated? I'd be happy to help add some docs that help people with installing from current.

enkore commented 4 years ago

It should've been automated, but looks like that broke. Investigating...

Edit: Turns out somewhere along the way (maybe OAuth/API changes) the rtfd <-> github integration got deleted. It's back now and the docs should stay up-to-date by themselves.

terminalmage commented 4 years ago

Awesome. I'll try to work on the docs over the next week or so.