search

LilSpazJoekp / docstrfmt

A formatter for reStructuredText
MIT License
23 stars 13 forks source link

Confusing caching issue #74

Open nemesifier opened 1 month ago

nemesifier commented 1 month ago

I ran the checks locally and all seemed fine, but in the Github Actions CI build I got errors.

So I tried to run checks locally on the specific files triggering the check to fail and at that point the check failed:

docstrfmt --check --line-length 74 README.rst
File '/home/nemesis/Code/openwisp/openwisp-utils/README.rst' could be reformatted.
1 out of 1 file could be reformatted.
Done! 🎉

Running the check normally doesn't bring up any issue:

docstrfmt --check --line-length 74 .
144 files were checked.
Done! 🎉

I figured out it must be because of some caching issue, so I found out the --ignore-cache flag, after adding this flag I finally replicated the same errors I had in the CI build.

I see the code mentions this feature is inherited from black, but I don't remember having had such an issue with black.

Looking at the README, this caching mechanism is not mentioned, cleaning the cache is also not explained and it's not clear to me how to do it.

Therefore, I will resort to using --ignore-cache by default. I am not sure if this is an bug or a misunderstanding I have about how the tool works which may be cleared out with a bit more documentation, so I wanted to report this here to clarify and help others who may stumble on the same issue.

Bytheway, Thank You!

I tried looking for your contact details in your profile but couldn't find any so I'll write this here if you don't mind.

First of all, Thank you very much for publishing and maintaining docstrfmt! I've been working heavily with ReStructuredText files in the @openwisp project as part of a 5 month effort to rewrite and unify all our documentation and this tool has proved to be very useful. Before trying this tool, we had some half-baked solutions, then I tried other tools but this was the only one which produced good output and seems to be the best for our use case.

I really think the community needs a great tool like black for automatically formatting and checking sphinx documentation files and IMHO this tool is a good candidate. I am now integrating it in our QA checks and in the CI builds of the @openwisp modules, that explains why I have been opening issues and PRs often here every time I stumble on an issue.

LilSpazJoekp commented 1 month ago

That is weird that you're facing an issue with caching. I agree it should be mentioned in the docs and how to disable it.

Also, thank you for the kind words! Feel free to open issues and PRs as you need and I'll take a look!