tedana
tedana copied to clipboard
Add CI for documentation style-checking
Summary
The tedana devs often go back and forth about proper formatting for our documentation. We could address this by adopting the style guidelines used by doc8 and adding a doc8 test to the CI.
Related to https://github.com/ME-ICA/tedana/pull/446#issuecomment-553438417 (from @jbteves).
Next Steps
- Agree on standard to adopt (what about doc8 default?)
- Fix docs to match standard in PR
- Write config for doc8
- Add doc8 to test requirements
- Add CircleCI test for doc8
We have to agree on the config. For example, if we want the text to be wrapped at 100 lines. It will also require a PR just to bring things in line with the doc8
settings, since I think there are decent-sized chunks of documentation that won't adhere even with the adjusted line length.
Agreed. I've added your points to the checklist.
It looks like doc8 is pretty straightforward. The only real content check I came across running on tedana's docs was D000 Unknown target name: "XX"
for bad links (this actually caught #480, which is cool).
Mostly it ends up catching lines that are too long, trailing whitespace, and "No newline at end of file". All of these are pretty simple, so the only parameters I think we need to discuss for the configuration is the number of characters per line. Personally, I like @jbteves' example of 100 characters.
This issue has been automatically marked as stale because it has not had any activity in 90 days. It will be closed in 600 days if no further activity occurs. Thank you for your contributions to tedana:tada: !