tedana icon indicating copy to clipboard operation
tedana copied to clipboard

Add CI for documentation style-checking

Open tsalo opened this issue 5 years ago • 4 comments

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

  1. Agree on standard to adopt (what about doc8 default?)
  2. Fix docs to match standard in PR
  3. Write config for doc8
  4. Add doc8 to test requirements
  5. Add CircleCI test for doc8

tsalo avatar Feb 09 '20 16:02 tsalo

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.

jbteves avatar Feb 13 '20 15:02 jbteves

Agreed. I've added your points to the checklist.

tsalo avatar Feb 13 '20 19:02 tsalo

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.

tsalo avatar Feb 15 '20 19:02 tsalo

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: !

stale[bot] avatar May 15 '20 20:05 stale[bot]