Readable command line output is just as important as readable documentation! It is the first interaction that a developer will have with a tool like this, so we want to leave a good impression with nicely formatted and readable command line output.
In keeping with our console beautification project, make sure that our output isn‘t getting too comfortable with the user’s next shell line.
We use Optimist to parse our command line arguments in a sane manner, and manage the myriad of options.
Readable command line output is just as important as readable documentation! It is the first interaction that a developer will have with a tool like this, so we want to leave a good impression with nicely formatted and readable output.
We treat the values within the current project's .citare.json
as defaults, so that you can
easily override the persisted configuration when testing and tweaking.
For example, if you have configured your .citare.json
to include "github": true
, it is
extremely helpful to use citare --no-github
until you are satisfied with the generated output.
In compatability with groc, if .groc.json
is present, configuration will be taken from there
and processed same way as .citare.json
.
We rely on CLIHelpers.configureOptimist to provide the extra options behavior that we require.
If we're in tracing mode, the parsed options are extremely helpful.
Version checks short circuit before our pretty printing begins, since it is one of those things that you might want to reference from other scripts.
In keeping with our stance on readable output, we don't want it bumping up against the shell execution lines and blurring together; use that whitespace with great gusto!
A Project is just a handy way to configure the generation process, and is in charge of kicking that off.
--silent
, --verbose
and --very-verbose
just impact the logging level of the project.
Set up project-specific options as we get them.
configure marked
automatically highlight brief definitions
hack to disable mangling of e-mail URLs
We expand the --glob
expressions into a poor-man's set, so that we can easily remove
exclusions defined by --except
before we add the result to the project's file list.
There are several properties that we need to configure on a project before we can go ahead and generate its documentation.
Project#generate
can take some options, such as which style to use. Since we‘re generating
differently depending on whether or not github is enabled, let’s set those up now:
Good to go!
We want to be able to annotate generated documentation with the project‘s GitHub URL. This is handy for things like generating links directly to each file’s source.
We hide the docs inside .git/citare-tmp
so that we can switch branches without losing the
generated output. It also keeps us out of the business of finding an OS-sanctioned
temporary path.
Dealing with generation for github pages is pretty involved, and requires a lot of back and forth with git. Rather than descend into callback hell in Node, we farm the logic out to a shell script.
Roughly, the publishing script:
gh-pages
branch (creating it if necessary).git/citare-tmp
over any existing files in the branch.
Command Line Interface