Uncategorized

The Dexy Command

September 26, 2010   ·   By   ·   Comments Off   ·   Posted in Uncategorized

The dexy command-line tool is the primary way of interacting with Dexy. Let’s take a look at the options which are available by calling:

dexy -h

Here’s the output:

usage: dexy [-h] [-x EXCLUDE_DIR [EXCLUDE_DIR ...]] [-v] [-n] [-u] [-p]
            [--cleanup] [--filters] [-a ARTIFACTS_DIR] [-l LOGS_DIR]
            [-c CACHE_DIR] [--local] [-s] [--setup] [-g CONFIG] [-d]
            [dir]

positional arguments:
  dir                   directory of files to process with dexy

optional arguments:
  -h, --help            show this help message and exit
  -x EXCLUDE_DIR [EXCLUDE_DIR ...], --exclude-dir EXCLUDE_DIR [EXCLUDE_DIR ...]
                        Exclude directories from processing by dexy, only
                        relevant if recursing. The directories designated for
                        artifacts, logs and cache are automatically excluded,
                        as are .bzr, .hg, .git, .svn, ignore, filters.
  -v, --version         show program's version number and exit
  -n, --no-recurse      do not recurse into subdirectories (default: recurse)
  -u, --utf8            switch encoding to UTF-8 (default: don't change
                        encoding)
  -p, --purge           purge the artifacts and cache directories before
                        running dexy
  --cleanup             delete all dexy-generated directories and files (does
                        not run dexy)
  --filters             list all available filters (does not run dexy)
  -a ARTIFACTS_DIR, --artifacts-dir ARTIFACTS_DIR
                        location of artifacts directory (default: artifacts)
  -l LOGS_DIR, --logs-dir LOGS_DIR
                        location of logs directory (default: logs) dexy will
                        create a dexy.log file in this directory
  -c CACHE_DIR, --cache-dir CACHE_DIR
                        location of cache directory (default: cache)
  --local               Use cached local copies of remote urls - faster but
                        might not be up to date
  -s, --short           Use short names in cache
  --setup               Create artifacts and logs directory and generic .dexy
                        file
  -g CONFIG, --config CONFIG
                        name of configuration file
  -d, --dangerous       Allow running remote URLs which may execute dangerous
                        code, use with care.

Only the directory argument is actually necessary to run dexy, you can simply type

dexy .

to run dexy on the directory you are currently in.

Dexy will look for a directory called artifacts in which it will place cached generated files, and it will complain if you don’t have one. Similarly Dexy wants you to create a logs/ directory. Dexy will create its own cache/ directory and will write the final output of each processed file to a canonical filename here. You can tell Dexy to use a different name for any of these directories should you want to.

By default, dexy will recurse into subdirectories and process files in those subdirectories. You can avoid this by passing the -n flag. Alternatively if you want to tell dexy not to recurse into certain directories, then use the -x flag for this. If you are using Python 2.7, then you can separate multiple directories with spaces. Because of this you need to use — after the last excluded directory, or use another flag after -x before giving the directory you want dexy to operate on.

dexy -x installing-dexy hello-world -- 2010/09
dexy -x installing-dexy hello-world -u 2010/09

If you are using Python 2.6 or lower, then you will need to separate multiple directories with commas.

If you call dexy -h it will give you instructions appropriate for your environment.

It’s a good idea to organize your documentation files into projects. You should run dexy from the root directory of each project. For example, here’s the root of the dexy-examples repository:

ls -a -1 /Users/ana/code/dexy-examples
.
..
.DS_Store
.dexy
.hg
.hgignore
.swp
README
artifacts
asciidoc
assets
c
cache
cards
clojure
cpp
devchix-ragel
erlang
garlicsim
garlicsim-code
garlicsim-new
hello-world
ignore
logs
min-copy
minimal
minimal.tgz
misc
newspaper
php
riak-python
scraperwiki
times.csv

You can see the artifacts/, cache/ and logs/ directories there. You could run all the examples by typing “dexy .”, or just one subdirectory (and its children) by typing “dexy c” or “dexy garlicsim”. The important thing is that you call dexy from the project root.

Dexy writes to a log file in logs/dexy.log, which you should follow with tail -f as this will explain what Dexy is doing as it runs, and tell you where you can find your processed files.

You will need to have a .dexy configuration file too. You can place a generic configuration file in your project root directory, and add more specific instructions in subdirectories if you need to. For example, here is the default .dexy configuration file for this blog:

{
  "*.sh|bash" : {},
  "../../../.dexy|dexy" : {}
}

I’ll write more about configuration files soon.

These instructions are current as of:

dexy --version