Anyway, here's an early preview of a tiny ldoc alternative I've been working on over the past few days.
Features
- It's a very small single file, currently around 500 lines including the default template.
- It's very configurable, via an optional configuration file and the command line.
- It's simple. It doesn't do any parsing of the source other than looking for docblocks.
- It's extensible. In fact, you can monkeypatch it right in the config file if you want.
Options
Options work like this. Internally there's a thing called a "generator," and that has fields like "input" (a "Reader") and "output" (a "Writer"). Those things in turn have their own fields that can affect their behavior. The configuration file runs with the generator as its environment, so in the configuration file you can write, for example:
Code: Select all
-- rtfmconf.lua
template.title = 'API Docs' -- the main title to show on our docs
template.path = 'stuff/template.html' -- path to our custom template
output.path = 'docs/index.html' -- writes to stdout if not present
tag.field.sort = 'type,name' -- sort field tags by type, then name
Code: Select all
lua rtfm.lua --template.title='Awesome API Docs' --tag.field.sort='type,name' game/foo.lua game/bar.lua
Here's a quick look at part of RTFM's own docs, generated with the built-in template.
Where's the manual?
Well, it can document itself, naturally. I want to get the built-in docs to the point where no other documentation is necessary, but it's not there yet (that's partly what this thread's for; the stuff I'm writing here should end up there eventually).
You can generate the docs like this:
Code: Select all
lua rtfm.lua rtfm.lua > rtfm.html
I'm posting this early because I'd love to get some feedback on it, even though there are still things I still want to add. Please let me know what you think, good or bad.
Download
I'll put it on github under the MIT license when it's more polished, but it can live here for now.