Confusion about Docs, PIP and Releases
daryltucker opened this issue · comments
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.
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.
@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
.
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.
Awesome. I'll try to work on the docs over the next week or so.