Skip to content

Improving JLL READMEs with example usage #647

@staticfloat

Description

@staticfloat

It would be good to provide easy ways for users to showcase how to use JLLs. Right now we spit out a pretty bland example usage with fake products, but this can be improved upon if authors so desire. I'm thinking there should be a per-Product optional field that takes in a usage example. I'm thinking perhaps what we can do here is to give the opportunity to provide something like a little "doctest" for JLLs; not only can we use this as a way to provide documentation, but we can also run it to ensure that the JLL itself is working.

So now the question is, what is the API? Perhaps something as simple as the following:

products = Product[
    FileProduct("src/data.txt", :data_txt; usage="""
		str = read(open(data_txt, "r"))
	"""),
    LibraryProduct("libdataproc", :libdataproc, usage="""
        data_lines = "this is a test\nline two of my test!"
		ccall((libdataproc, :count_characters), Cint, (Cstring, Cint), data_lines, length(data_lines))
	"""),
    ExecutableProduct("mungify", :mungify_exe, usage="""
		mungify_exe() do exe_path
			run(`$exe_path --input=$(data_txt) --find-all=jlbuildbot`)
		end
	"""),
]

These would get integrated into the README.md generation, and they would also get run when building a platform that is compatible with the host platform, to ensure that the products work at least as well as the author is claiming they should. We wouldn't check that output matches or anything like that like a normal doctest (although we would do a using Test beforehand, in case someone wanted to do that) but the idea here is just to give some guidelines to what someone can do with this package.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions