rox_on(pkg = ".")rox_off(pkg = ".")
as.package for more informationDocumentation, if generated automatically by, e.g., roxygen2,
is a build artifact that ideally should not be added to a version
control system. On the other hand, it seems necessary to
version-control the documentation:
INSTALL and others)
and building a source archive
requires fully built documentation
roxygen2 and perhaps
other packages that are used in the generation process.
These functions attempt to work around this dilemma.
It is assumed that Git is used to version-control the package.
The functions switch between two states: ignoring and versioning
documentation, abbreviated by ``off'' and ``on'' mode.
(This affects only the man directory, the NAMESPACE
and DESCRIPTION files are always version-controlled.)
Currently, this is an all-or-nothing decision:
It is not possible to keep only selected files version-controlled.
Even in ``off'' mode, it can be built like usual -- only that
the changes in the generated files are not tracked by the version control
system. Moreover, in ``off'' mode a file that contains the body of
autoroxy is written to a special file in the R directory;
this has the effect that documentation is available even with
R CMD INSTALL but is harmless otherwise. (This special file is
removed again in ``on'' mode.)
The Git repository must be in a clean state, i.e., the command
git status shows no changes.
On success, the changes are committed to Git.
When repeatedly calling the same function twice, the second call should have
no effect.
Repeatedly turning documentation on an off in the same branch clutters the history. Hence, it is recommended to perform development in a dedicated development branch and keep the documentation only in a release branch.
One way to achieve this is to use the git flow command line tool.
By default, git flow uses develop as development and
master as release branch; I recommend using master for
development and production for releases, the description below follows
this convention. Documentation should be turned
off in the master branch (and hence all feature branches derived from
there), turned on as soon as a release is started, and turned off again
after merging a released version back to master.
Hooks can help automating this process.
As the history in the production branch contains
only merges from release branches, even repeated turning off and on
of documentation in development branches doesn't show in the mainline
history of production. Remember to run at least
git diff --name-status master.. before finishing a release.
Vincent Driessen: Git Flow: A successful branching model, blog post
Git Flow, AVH edition