The core thesis of this package is that full on deployed documentation websites (e.g. done with Documenter.jl) is overkill for many packages; and that a good read me is all you need. People often only look at the readme on github, they don't want to click through to the docs. However, one feature that is missing from that is automatically including docstrings into the read-me. This package aims to solve that.
Rather than working with the README.md directly, you work on a README.template.md,
from which the README.md is generated.
You then check that file into the the git-repo and it will be displayed by github etc.
When you update it
This package has one function:
generate_readme([outfile], [template_file], [module_name])
Generates the readme from template_file storing the result in template*file. it automatically load the module of module*nameIf none of the options are provided, they are defaulted for the current directory. i.e. if in the top level project directory can just rungenerate_readme().
generate_readme(IOBuffer, template_file)
Generates the readme from the templace file, returning the result in an IOBuffer which can be read.
generate_readme(String, template_file)
Generates the readme from the templace file, returning the result as a String
You can use a github action (like this repo does) that automatically adds a commit to regenerate the README.md.
You can just copy the file from .github/workflows/regenerate.yml into your repo.
You could alternatively do it will a similar git precommit hook script locally.
Arguably, but better done than perfect.
Its much easier to check in a file than sort out deploy keys etc.
And github etc only render the checked in README.md.
Don't do that. It will be deleted the next time it is regenerated. A warning is at the top of the generated file to remind people not to.
It is the assumption of the aforementioned github actions script that this is installed to /docs/Project.toml (potentially along side Documenter.jl etc).
But really you can install it anywhere.