ibex
ibex copied to clipboard
lowRISC
[docs] Clean up line breaks
The source files for the documentation have a mix of styles for when lines should be broken, the verification page is a notable example: https://raw.githubusercontent.com/lowRISC/ibex/master/doc/03_reference/verification.rst which contains wrapping lines at different lengths as well as the one line for one sentence style.
Line breaking style should be checked and made consistent across all documentation files (ensuring all files comply with one line for one sentence).
We could consider a CI check to ensure documentation files are correctly formatted.
The general idea is either you have one sentence per line or wrap to 80 characters.
For README's you can argue for the 80 character wrapper to make them easy to read outside of github's markdown rendering. However for the top-level README at least the style is more one sentence per line, plus it's more of a project introduce README rather than a how you do things README so less likely someone will need read it off github.
So for the top-level README I'd say one sentence per line is the best style but other READMEs would be better left as 80 characters per line.
I want to work on it for starting my open source contribution. Can anyone guide me through the process? I'll appreciate it.
Hi there. Thanks for the offer of help. I'd suggest you start with a single file (verification.rst, mentioned above, maybe). Reformat to ensure everything is 1 sentence per line, then push up a PR.
@rswarbrick I have started with a single file, verification.rst, and pushed up a PR. Can you take a look?
