Package: dvci
dvciInstallationLike most Python projects, dvci usessetuptools, so installation
is what you might expect:pipinstalldvciOnce you've installed dvci, you might also want to set up shell-completion for
it. If you haveshtabinstalled, you can do this withdvci generate-completion, which will print the shell-completion code for your
shell. For more details on how to set this up, consult shtab'sdocumentation.UsageInitializationBefore using dvci for the first time, you may want to add the dvci plugin
to yourdocums.ymlfile. This plugin is added by default when building your
documentation with dvci, but by adding it explicitly, you can configure how it
works. The plugin adds a version selector to supported themes as well as
updating thesite_url(if you set it) to point to the version of the docs that
are being built:plugins:-dvci:# these fields are all optional; the defaults are as below...version_selector:true# set to false to leave out the version selectorcss_dir:css# the directory to put the version selector's CSSjavascript_dir:js# the directory to put the version selector's JScanonical_version:null# the version for <link rel="canonical">; `null`# uses the version specified via `dvci deploy`Note: If you have existing documentation on yourgh-pagesbranch, you may also
want to delete the old documentation before building your new versioned docs viadvci delete --all.)Building Your Docsdvci is designed to produce one version of your docs at a time. That way, you
can easily deploy a new version without touching any older versions of your
docs; this can be especially important if your old docs are no longer buildable
with the newest version of Docums (or if they weren't built with Docums at
all!). To deploy the current version of your docs, simply run:dvcideploy[version]Where[version]is the current version of your project, represented however
you like (I recommend using[major].[minor]and excluding the patch
number). You can also pass aliases to thedeploycommand to host a
particularly-relevant version of your docs somewhere special (e.g.latest):dvcideploy[version][alias]...If[version]already exists, this command willalsoupdate all of the
pre-existing aliases for it. Normally, if an alias specified on the command line
is already associated with another version, this will return an error. If youdowant to move an alias from another version to this version (e.g. when
releasing a new version and updating thelatestalias to point to this new
version), you can pass-u/--update-aliasesto allow this.By default, aliases create a simple HTML redirect to the real version of the
docs; to create a copy of the docs for each alias, you can pass--no-redirect.
If you're using redirects, you can customize the redirect template with-T/--template; this takes a path to aJinjatemplate that accepts
an{{href}}variable.If you'd like to specify a title for this version that doesn't match the version
string, you can pass-t TITLE/--title=TITLEas well.In addition, you can specify where to deploy your docs via-b/--branch,-r/--remote, and--prefix, specifying the branch, remote, and directory
prefix within the branch, respectively. Finally, to push your docs to a remote
branch, simply add-p/--pushto your command.Viewing Your DocsTo test that your docs have been built as expected, you can serve them locally
from a dev server:dvciserveBy default, this serves the docs onhttp://localhost:8000, but you can
change this with-a/--dev-addr. Remember though,this is for testing only.
To host your docs for real, you should use a real web server.Deleting DocsSometimes you need to delete an old version of your docs, either because you
made a mistake or you're pruning unsupported versions. You can do this via thedeletesubcommand:dvcidelete[version-or-alias]...Ifversion-or-aliasis a version, this will delete the version and all its
aliases from the branch; if it's an alias, it will only delete that alias.If you'd like tocompletelywipe the contents of your docs branch, just rundvci delete --all. Likedeployabove, you can specify--branch,--push,
etc to control how the commit is handled.Listing DocsIf you ever need to see the list of all currently-deployed doc versions, you can
run:dvcilistTo list the info for a particular version, you can just pass the version or
alias:dvcilist[version-or-alias]Sometimes, you need this information to be consumed by another tool. In that
case, pass-j/--jsonto return the list of doc versions as JSON.Setting the Default VersionWith all the versions of docs you have, you may want to set adefaultversion
so that people going to the root of your site are redirected to the latest
version of the docs:dvciset-default[version-or-alias]If you want to use a different template from the default, you can pass-T/--template; this takes a path to aJinjatemplate that accepts
an{{href}}variable.Likedeployanddeleteabove, you can specify--branch,--push,
etc to control how the commit is handled.Changing a Version's TitleAs you update your docs, you may want to change the title of a particular
version. For example, your1.0docs might have the title1.0.0, and when you
release a new patch, you want to update the title to1.0.1. You can do this
with theretitlecommand:dvciretitle[version-or-alias][title]As with other commands that change your docs, you can specify--branch,--push, etc to control how the commit is handled.Adding a New Version AliasSometimes, you might need to add a new alias for a version without rebuilding
your documentation. You can use thealiascommand for this:dvcialias[version-or-alias][alias]...As withdeploy, you can pass-u/--update-aliasesto change where an
existing alias points to.Once again, you can specify--branch,--push, etc to control how the commit
is handled.More DetailsFor more details on the available options, consult the--helpcommand for
dvci.Staying in Syncdvci will do its best to stay in-sync with your remote repository and will
automatically update your local branch to match the remote's if possible (note
that dvciwon'tautomaticallygit fetchanything). If your local branch has
diverged from your remote, dvci will leave it as-is and ask you what to do. To
ignore the remote's state, just pass--ignore; to update to the remote's
state, pass--rebase.CNAME(and Other Special Files)Some special files that you'd like to deploy along with your documentation (such
asCNAME) aren't related to a particular version of the docs, and instead need
to go in the root directory of your site. There's no special handling for this
in dvci, but since your built docs live on a Git branch, it's still easy to
manage: check out yourgh-pagesbranch (or wherever your built docs
live), and commit the necessary files to the root directory.Deploying via CISince dvci just generates commits to an ordinary Git branch, it should work
smoothly with your favorite CI system. However, you should keep in mind that
some CI systems make shallow clones of your repository, meaning that the CI job
won't have a local instance of your documentation branch to commit to. This will
naturally cause issues when trying to push the commit. This is easy to resolve
though; just manually fetch yourgh-pagesbranch (or whichever you deploy to)
before running dvci:gitfetchorigingh-pages--depth=1You may also need toconfigure a Git userso that dvci can
make commits:gitconfiguser.nameci-bot
gitconfiguser.emailci-bot@example.comFor Theme AuthorsIf you'd like to provide support for dvci in your theme, you just need to
fetchversions.jsonand build a version selector.versions.jsonlooks like
this:[{"version":"1.0","title":"1.0.1","aliases":["latest"]},{"version":"0.9","title":"0.9","aliases":[]}]If you're creating a third-party extension to an existing theme, you add a
setuptools entry point fordvci.themespointing to a Python submodule that
containscss/andjs/subdirectories containing the extra code to be
installed into the user's documentation. This will then automatically be
included via thedvciplugin in the user'sdocums.ymlfile.To see some examples of how to work with this, check thedvci/themes/documsdirectory.LicenseThis project is licensed under theBSD 3-clause license.