Auto generated doc strings are computed during precompilation.

[haberdashPI]

Description

This changes how docstrings get computed from the README. They occur at precompilation and we use Base.include_dependency to ensure that a change to the README invalidates the precompilation cache.

[codecov[bot]]

Codecov Report

Merging #33 (2da26c4) into main (9def809) will decrease coverage by 0.13%. The diff coverage is n/a.

@@            Coverage Diff             @@
##             main      #33      +/-   ##
==========================================
- Coverage   95.98%   95.86%   -0.13%     
==========================================
  Files           1        1              
  Lines         274      266       -8     
==========================================
- Hits          263      255       -8     
  Misses         11       11              

Files	Coverage Δ
src/StableHashTraits.jl	95.86% <ø> (-0.13%)	:arrow_down:

:mega: We’re building smart automated test selection to slash your CI/CD build times. Learn more

[glennmoy]

Can I ask why we don't just write this information directly into the docstring and then direct people to the docs rather than doing it this way?

[haberdashPI]

Can I ask why we don't just write this information directly into the docstring and then direct people to the docs rather than doing it this way?

My personal preference is that a README provide a good bird's eye view of the purpose of the package, and an intro to basic usage. For small pacakages with minimal API surface I think it's nice if the README contents are the docs.

I'm on the fence in this case. StableHashTraits feels like it is approaching the point of needing full-out docs rather than just a thorough README.

That said, even if it had docs setup, I would want some section of the README to be included in the docs. I think it's helpful if you assume a reader looking through the docs has not read the README, and that a reader of the README may not bother looking thorough the docs before trying out the package. So there is always at least some amount of information that should be redundant across the two, and I currently favor a situation where both are made consistent with one another programmatically.