readthedocs.org
readthedocs.org copied to clipboard
readthedocs
Add blacken-docs to pre-commit hooks (and blacken docs)
While waiting for pre-commit hooks and Black to be added (and indeed run for the entire code base to be blackened), we can test out this pre-commit hook:
https://github.com/asottile/blacken-docs
To fix the issue:
- Add the hook to the pre-commit config over in https://github.com/readthedocs/common/blob/main/pre-commit-config.yaml
- Run blacken-docs on all files (but please don't run all hooks on all files)
Hi I am starting my open source journey! Would love to be able to contribute on this.
Can you assign me this issue?
- repo: https://github.com/asottile/blacken-docs rev: v1.12.1 hooks: - id: blacken-docs additional_dependencies: [black==22.6.0]
Also, will adding this over in https://github.com/readthedocs/common/blob/main/pre-commit-config.yaml solve the issue?
Hi @ArhyaSaha - great choice to start the journey :)
This issue should ideally be solved in the two steps outlined above. I would recommend opening up a PR on the common repo and then link it to a PR on the readthedocs.org repo (this one) that shows the results of running --all-files (should only affect docs/ of course).
One more thing: The common repository is shared as a git submodule by several repositories (hence the name). I think that you can assume that documentation always lives in a docs/ folder.. in case it's possible to limit the scope of the hook to just one folder, which will make it run faster and avoid unintended effects on other locations in a repository.
Hi @benjaoming. I tried setting up my environment as mentioned in the docs. I am not able to build docker image for the servers as it gives me an error when I run the given command. The error might be because I am on a windows platform. Is there any other way i can set up my local environment for this issue?
Hi @ArhyaSaha - you strictly speaking won't need this environment to contribute this change. It is only affecting docs/, so you should be able to change the pre-commit configuration and run that without ever running Read the Docs itself...
@benjaoming So i cloned the readthedocs.org repo and installed the requirements from the common submodule. Then i added the lines in .pre-commit-config.yaml and it gives me an error.
An error has occurred: InvalidConfigError: ==> File .pre-commit-config.yaml =====> Expected a Config map but got a str
Please guide me on how to solve this issue.
You'd have to figure that one out by carefully reading your config file and comparing it to what pre-commit expects.
Hi @benjaoming While the team is reviewing the PRs, is it possible to redirect me to some other issue?
@benjaoming Can you also help me with hacktoberfest-accepted badges on the PRs.
Yes, I think that we can add a "hacktoberfest-accepted" label and that should be enough :+1: https://blog.shahednasser.com/hacktoberfest-2022-everything-you-need-to-know-to-participate/