zwitschi
49bfccc808
Add tools/check_docs.py to require READMEs only in tracked docs directories, validate local links and verify every tracked image is linked. Gitignored generated files such as realism runs are exempt. Document the command and add unit tests. Python 97/97.
53 lines
2.0 KiB
Python
53 lines
2.0 KiB
Python
import tempfile
|
|
import unittest
|
|
from pathlib import Path
|
|
|
|
import check_docs
|
|
|
|
|
|
class CheckDocsTests(unittest.TestCase):
|
|
def setUp(self):
|
|
self.temp = tempfile.TemporaryDirectory()
|
|
self.root = Path(self.temp.name)
|
|
|
|
def tearDown(self):
|
|
self.temp.cleanup()
|
|
|
|
def _file(self, rel, text=""):
|
|
path = self.root / rel
|
|
path.parent.mkdir(parents=True, exist_ok=True)
|
|
path.write_text(text, encoding="utf-8")
|
|
return path
|
|
|
|
def test_accepts_tracked_directory_with_links_and_images(self):
|
|
self._file("docs/README.md", "[x](guide.md)")
|
|
self._file("docs/guide.md", "guide")
|
|
self._file("docs/images/preview.png", "png")
|
|
self._file("docs/images/README.md", "")
|
|
tracked = [Path("docs/README.md"), Path("docs/guide.md"),
|
|
Path("docs/images/preview.png"), Path("docs/images/README.md")]
|
|
self.assertEqual(check_docs.check_docs(self.root, tracked), [])
|
|
|
|
def test_requires_readme_only_in_tracked_dirs(self):
|
|
self._file("docs/README.md")
|
|
self._file("docs/ignored/file.txt")
|
|
tracked = [Path("docs/README.md"), Path("docs/ignored/file.txt")]
|
|
errors = check_docs.check_docs(self.root, tracked)
|
|
self.assertTrue(any("docs/ignored" in e for e in errors))
|
|
# A directory with no tracked files is not required to have a README.
|
|
self._file("docs/generated/file.txt")
|
|
tracked = [Path("docs/README.md")]
|
|
self.assertEqual(check_docs.check_docs(self.root, tracked), [])
|
|
|
|
def test_reports_broken_link_and_unlinked_image(self):
|
|
self._file("docs/README.md", "[broken](missing.md)")
|
|
self._file("docs/image.png", "png")
|
|
tracked = [Path("docs/README.md"), Path("docs/image.png")]
|
|
errors = check_docs.check_docs(self.root, tracked)
|
|
self.assertTrue(any("broken link" in e for e in errors))
|
|
self.assertTrue(any("image not linked" in e for e in errors))
|
|
|
|
|
|
if __name__ == "__main__":
|
|
unittest.main()
|