search

0xERR0R / blocky

Fast and lightweight DNS proxy as ad-blocker for local network with many features
https://0xERR0R.github.io/blocky/
Apache License 2.0
4.68k stars 208 forks source link

Documentation pages at index (`/*`) are outdated #1329

Open garfieldairlines opened 9 months ago

garfieldairlines commented 9 months ago

Hello, I started blocky and I got a few warnings that my yaml configuration is deprecated :

WARN config option "upstream" is deprecated, please use "upstreams.groups" instead
WARN config option "blocking.downloadTimeout" is deprecated, please use "blocking.loading.downloads.timeout" instead
WARN config option "blocking.refreshPeriod" is deprecated, please use "blocking.loading.refreshPeriod" instead
WARN config option "hostsFile.refreshPeriod" is deprecated, please use "hostsFile.loading.refreshPeriod" instead
WARN config option "hostsFile.filePath" is deprecated, please use "hostsFile.sources" instead

The problem is : the documentation of the "reference file" ( https://0xerr0r.github.io/blocky/configuration/ ) hasn't been updated, could you update your documentation please ?

ThinkChaos commented 9 months ago

Hi, thanks for the report. The issue is actually that the main docs link still points to an older version. You can see the correct docs here: https://0xerr0r.github.io/blocky/v0.23/configuration/

I'm looking into why the latest version was not updated.

ThinkChaos commented 9 months ago

I manually pushed 2 commits to the gh-pages branch so the existing URLs start working again without a new release.

3c75f9aa76ff3cb3d0a1b0afa15cc7f3a5b13bb2 fixes https://0xerr0r.github.io/blocky/latest/ and a proper fix is described in https://github.com/jimporter/mike/issues/188 which I have implemented in a branch already.
Though my "default" version is not "latest" so my pages site is different. and I could not get mike to update that properly.

a65bb21710b1642acd6f9a270f5ba3dac94cfd40 fixes https://0xerr0r.github.io/blocky/configuration/ I pushed the result of cp -a ./v0.23/* . as a temp fix, so a proper solution is still needed for this.
@0xERR0R and @kwitsch do you know how the files at the index used to be updated?

I can dig more into mike code to figure out the default and index issues later, but for now the manual fixes will do cause I'm frustrated with it. Creating an issue upstream will also wait for the same reason.

0xERR0R commented 9 months ago

The docs job will run on each commit and override your manual fix. Since it is a bug in mike, I think we should downgrade to 1.x as suggested by this comment.

We can also try this solution.

garfieldairlines commented 9 months ago

Thanks for explaining (and the link to the up to date docs) !

ThinkChaos commented 9 months ago

After a bit more digging, I noticed /configuration hasn't been updated since the initial gh-pages commit (89bd8eed08d163724b2ef04107bd977ebcf5180e). So it's been out of date for a while!
I also don't see how mike can generate those as based on its docs I only see a way to generate docs for a version, so IIUC in a subdir. I didn't dig into mike v1.0 to see if that could've done it.
Anyways, the best solution I can come up with given that mike v2 is not designed to generate those files is to make them redirect to /latest/* (e.g. /configuration -> /latest/configuration). That way we never have to update them again, and any existing links just redirect to the URL that does get updated.
I made #1331 with that.

For the latest not working I made a mistake when testing yesterday, and https://github.com/jimporter/mike/issues/188 is actually unrelated (only relevant if you use Netlify in front of GH pages). So no need to change the mike usage at all*.

* I made #1332 with some changes, but it's not related to fixing the docs, just changes I did while investigating.