Package: armstrong.dev
Tools and such for handling development of Armstrong applicationsThis package contains some of the various helpers needed to do development work
on the Armstrong packages. If you’re not actively developing, or working with
development versions of Armstrong, you probably don’t need this package.Installation & ConfigurationIf you are just running tests for a component, Tox will grab everything it
needs including ArmDev.pip install toxand runtoxOtherwise:pip install armstrong.dev invokeInvokeis not strictly required. ArmDev is as lean as possible to support
fast virtualenv creation so multi-environment testing tools like TravisCI
and Tox will complete ASAP.Many of the Invoke tasks have their own package requirements and they will
nicely notify you if something they require needs to be installed.This component supports Django 1.3, 1.4, 1.5, 1.6, 1.7 on Python 2.6 and 2.7.UsageMost Armstrong components already have the necessary configuration to use these
Dev tools. Specifically, components needtasks.pyandenv_settings.pyfiles. Assuming these are present:invoke--listto see a list of all available commandsinvoke--help<cmd>for help on a specific commandSeveral of the tasks take an optional--extraargument that is used as a
catch-all way of passing arbitrary arguments to the underlying command. Invoke
cannot handle arbitrary args (like Fabric 1.x could) so this is our workaround.
Two general rules: 1) enclose multiple args in quotes 2) kwargs need to use
“=” with no spaces (our limitation, not Invoke’s). Example:invoke test--extra"--verbosity=2<path.to.app.test1> <path.to.app.test2>"invoke install[--editable]to “pip install” the component, by default as aneditableinstall. For
a regular install, use--no-editableor--editable=False.invoke test[--extra...]to run tests where –extra handles anything the normal Django
“manage.py test” command accepts.invoke coverage[--reportdir=<directory>][--extra...]for running test coverage. –extra works the same as in “invoke test” passing
arbitrary args to the underlying test command. –reportdir is where the HTML
report will be created; by default this directory is named “htmlcov” or
whatever is set in the.coveragercfile.invoke managepy <cmd>[--extra...]to run any Django “manage.py” command where –extra handles any arbitrary
args. Example:invoke managepy shellorinvoke managepy runserver--extra9001invoke create_migration[--initial]to create a South migration for the component (in Django <1.7).
An “auto” migration is default if the –initial flag is not used.There are other commands as well, but these are the most useful. Remember
that individual components may provide additional Invoke tasks as well. So
runinvoke--listto discover them all.Component SetupIf you are creating a new Armstrong component or updating one that uses the
pre-2.0 ArmDev, you’ll need to create (or port to) these two files:Create atasks.pyand add the following:from armstrong.dev.tasks import *

# any additional Invoke commands
# ...Create anenv_settings.pyand add the following:from armstrong.dev.default_settings import *

# any additional settings
# it's likely you'll need to extend the list of INSTALLED_APPS
# ...Not required but as long as you are reviewing the general state of things,
take care of these too!Review therequirementsfilesReview the TravisCI configurationDrop Lettuce tests and requirementsAdd atox.inifileReview the README text and setup.py metadataUse Setuptools and fix any improper namespacingStop shipping tests by moving tests/ to the root directoryIf the component uses logging, consider namespacing it withlogger = logging.getLogger(__name__).Add aCHANGES.rstfile and include it in the MANIFESTReview.gitignore. You might want to ignore these:.tox/
coverage*/
*.egg-infoNotable changes in 2.0Setuptools is now explicitly used/required instead of Distutils.Invoke replaces Fabric for a leaner install without the SSH and crypto
stuff. Invoke is still pre-1.0 release so we might have some adjustment
to do later.This version offers an easier and more standard way to run a Django
environment with a component’s specific settings, either from the
commandline or via import.It provides an “a la carte” requirements approach. Meaning that if you run an
Invoke command that needs a package that isn’t installed, it will prompt you
to install it instead of requiring everything up-front. This allows for much
faster virtualenv creation (which saves considerable time in testing) and
doesn’t pollute your virtualenv with packages for features you don’t use.testandcoveragewill work better with automated test tools like
TravisCI and Tox. These commands also now work like Django’s native test
command so that you can pass arguments for running selective tests or
changing the output verbosity.Settings are now defined in the normal Django style in anenv_settings.pyfile instead of as a dict within the tasks file. It’s not called “settings.py”
to make it clearer that these are settings for the development and testing
of this component, not necessarily values to copy/paste for incorporating
the component into other projects.The full list of changes and backward incompatibilties is available
inCHANGES.rst.ContributingDevelopment occurs on Github. Participation is welcome!Found a bug? File it onGithub Issues. Include as much detail as you
can and make sure to list the specific component since we use a centralized,
project-wide issue tracker.Have code to submit? Fork the repo, consolidate your changes on a topic
branch and create apull request.Questions, need help, discussion? Use ourGoogle Groupmailing list.State of ProjectArmstrongis an open-source news platform that is freely available to any
organization. It is the result of a collaboration between theTexas TribuneandThe Center for Investigative Reportingand a grant from theJohn S. and James L. Knight Foundation. Armstrong is available as a
complete bundle and as individual, stand-alone components.