User Documentation

A Brief Intro

DevAssistant - start developing with ease

DevAssistant (http://devassistant.org) can help you with creating and setting up basic projects in various languages, installing dependencies, setting up environment etc.

It is based on idea of per-{language/framework/...} “assistants” (plugins) with hierarchical structure.

Note: prior to version 0.10.0, DevAssistant has been shipped with a default set of assistants that only worked on Fedora. We decided to drop this default set and create DAPI, DevAssistant Package Index, https://dapi.devassistant.org/ - an upstream PyPI/Rubygems-like repository of packaged assistants. DAPI’s main aim is to create a community around DevAssistant and provide various assistants with good support for various platforms - a task that DevAssistant core team alone is not able to achieve for a large set of assistants.

This all means that if you get DevAssistant from upstream repo or from PyPI, you will have no assistants installed by default. To get assistants, search DAPI through web browser or run da pkg search <term> and da pkg install <assistant package> . This will install one or more DAPs (DevAssistant Packages) with the desired assistants.

If you want to create your own assistants and upload them to DAPI, see http://docs.devassistant.org/en/latest/developer_documentation/create_assistant.html and http://docs.devassistant.org/en/latest/developer_documentation/create_assistant/packaging_and_distributing.html.

There are four main modes of DevAssistant execution. Explanations are provided to better illustrate what each mode is supposed to do:

create
Create new projects - scaffold source code, install dependencies, initialize SCM repos ...
tweak
Work with existing projects - add source files, import to IDEs, push to GitHub, ...
prepare
Prepare environment for working with existing upstream projects - install dependencies, set up services, ...
extras
Tasks not related to a specific project, e.g. enabling services, setting up IDEs, ...

These are some examples of what you can do:

# search for assistants that have "Django" in their description
$ da pkg search django
python - Python assistants (library, Django, Flask, GTK3)

# install the found "python" DAP, assuming it supports your OS/distro
$ da pkg install python

# find out if the installed package has documentation
$ da doc python
INFO: DAP "python" has these docs:
...
INFO: usage.txt
...
# show help
$ da doc python usage.txt

# if the documentation doesn't say it specifically, find out if there is a "create"
#  assistant in the installed "python" DAP
$ da create -h
...
{..., python, ...}
...

# there is, so let's find out if it has any subassistants
$ da create python -h
...
{..., django, ...}
...

# we found out that there is "django" subassistant, let's find out how to use it
$ da create python django -h
<help text with commandline options>

# help text tells us that django assistant doesn't have subassistants and is runnable, let's do it
$ da create python django -n ~/myproject # sets up Django project named "myproject" inside your home dir

# using the same approach with "pkg search", "pkg install" and "da tweak -h",
#  we find, install and read help for "tweak" assistant that imports projects to eclipse
$ da tweak eclipse -p ~/myproject # run in project dir or use -p to specify path

# using the same approach, we find, install and read help for assistant
#  that tries to prepare environment for a custom upstream project, possibly utilizing
#  its ".devassistant" file
$ da prepare custom -u scm_url -p directory_to_save_to

# sometimes, DevAssistant can really do a very special thing for you ...
$ da extras make-coffee

Should you have some questions, feel free to ask us at Freenode channel #devassistant or on our mailing list (https://lists.fedoraproject.org/mailman/listinfo/devassistant). You can also join our G+ community (https://plus.google.com/u/0/communities/112692240128429771916) or follow us on Twitter (https://twitter.com/dev_assistant).

So What is an Assistant?

In short, assistant is a recipe for creating/tweaking a project or setting up the environment in a certain way. DevAssistant is in fact just a core that “runs” assistants according to certain rules.

Each assistant specifies a way to achieve a single task, e.g. create a new project in framework X of language Y.

If you want to know more about how this all works, consult Create Your Own Assistant.

Assistant Roles

There are four assistant roles:

creator (create or crt on command line)
creates new projects
tweak (tweak or twk on command line)
works with existing projects
preparer (prepare or prep on command line)
prepares environment for development of upstream projects
extras (extras or extra on command line)
performs arbitrary tasks not related to a specific project

The main purpose of having roles is separating different types of tasks. It would be confusing to have e.g. python django assistant (that creates new project) side-by-side with eclipse assistant (that registers existing project into Eclipse).

You can learn about how to invoke the respective roles below in Creating New Projects, Working with Existing Projects, Preparing Environment and Extras.

Using Commandline Interface

Creating New Projects

DevAssistant can help you create your projects with one line in a terminal. For example:

$ da create python django -n foo -e -g

da is the short form of devassistant. You can use either of them, but da is preferred.

What this line does precisely depends on the author of the assistant. You can always display help by using da create python django -h. Running the above command line may do something like this:

  • Install Django and all needed dependencies.
  • Create a Django project named foo in the current working directory.
  • Make any necessary adjustments so that you can run the project and start developing right away.
  • The -e switch will make DevAssistant register the newly created projects into Eclipse. This will also cause installation of Eclipse and PyDev, unless already installed.
  • The -g switch will make DevAssistant register the project on Github and push sources there.

Working with Existing Projects

DevAssistant allows you to work with previously created projects. You can do this by using da tweak, as opposed to da create for creating:

$ da tweak eclipse

As noted above, what an assistant does depends on its author. In this case, it seems that the assistant will import an existing project into Eclipse, possibly installing missing dependencies - to find out if this assumption is correct, run da tweak eclipse -h and read the help.

Preparing Environment

DevAssistant can set up the environment and install dependencies for development of an already existing project located in a remote SCM (e.g. Github). There is, for example, the so-called custom prepare assistant, that is supposed to prepare environment for arbitrary upstream projects. This means that it will checkout the source code from given git repo and if there is a .devassistant file in the repo, it’ll install dependencies and prepare environment according to it:

$ da prepare custom -u scm_url

Warning: The custom assistant executes custom pieces of code from a .devassistant file, so use this only for projects whose upstreams you trust.

We hope that existance of DAPI will attract people from various upstreams to create prepare assistants for their specific projects, so that people could do something like:

$ da prepare openstack

To get development environment prepared for development of OpenStack, etc...

Extras

The last piece of functionality is performing arbitrary tasks that are not related to a specific projects. E.g.:

$ da extras make-coffee

Custom Actions

There are also some custom actions besides create, tweak, prepare and extras.

  • doc - Displays documentation for given DAP. Uses less as pager, if available.:

    # finds out if "python" DAP has documentation, lists documents if yes
    $ da doc python
    ...
    INFO: LICENSE
    INFO: somedoc.txt
    INFO: docsubdir/someotherdoc.txt
    ...
    
    # displays specific document for "python" DAP
    $ da doc python docsubdir/someotherdoc.txt
    
  • help- Displays help :)

  • pkg - Manipulate dap packages, communicate with DAPI. Has several subactions:

    • info - prints information about packages from DAPI
    • install - installs packages from DAPI
    • lint - runs sanity checks on local DAP package
    • list - lists installed DAPs
    • search - searches DAPs on DAPI for given term
    • uninstall - uninstalls given package(s)
    • update - updates all or given package(s)
  • version- Displays current DevAssistant version.

Using the GUI

The DevAssistant GUI provides the full functionality of Commandline Interface through a Gtk based application.

The GUI provides all assistant of the same type (creating, tweaking, preparing and extras) in one tab to keep things organized.

The GUI workflow is dead simple:

  • Choose the assistant that you want to use, click it and possibly choose a proper subassistant (e.g. django for python).
  • The GUI displays a window where you can modify some settings and choose from various assistant-specific options.
  • Click the “Run” button and then just watch getting the stuff done. If your input is needed (such as confirming dependencies to install), DevAssistant will ask you, so don’t go get your coffee just yet.
  • After all is done, get your coffee and enjoy.