Setting up your work environment

What is a project?

We use the word project for quite a lot of things. But for Lino developers they all have one thing in common: each project is a directory on your file system. You "activate" a project by opening a terminal and changing to its directory. That's all. Almost all. Read on.

There are different types of "projects". A Django project is where you can invoke a runserver. It contains at least a settings.py and usually a file manage.py. For Atelier, a project must contain at least a file tasks.py. An Atelier project can contain one or more Django projects.

  • An atelier project usually corresponds to a public code repository (using Git or Mercurial). But you can have unpublished projects which have no repo at all.

  • An atelier project usually corresponds to a given Python package to be published on PyPI.

  • An atelier project can have a number of Sphinx document trees (default is one tree named docs).

You will have different root directories containing projects. You don't want to have them all under a single top-level directory. We suggest the following naming conventions.

~/repositories

The ~/repositories directory is your collection of code repositories of projects for which you cloned a copy. We created this directory in Installing a Lino developer environment.

~/projects

~/projects/ is the base directory for every new project of which you are the author. You created this directory in Your first local Lino project, and hello is your first local project.

~/repositories/book/lino_book/projects

The Lino Book comes with a set of Django demo projects maintained by the Lino team. For example, min1 is one of the Django projects included in the book project.

Configuring atelier

To get a full Lino contributor environment, you must tell atelier the list of your projects. That's done in your ~/.atelier/config.py file. Create the directory and the file, with the following content:

add_project("/home/john/projects/hello")
names = 'lino xl book noi voga presto welfare avanti vilma tera extjs6'
for p in names.split():
    add_project("/home/john/repositories/" + p)

Note our use of a syntactical trick to avoid typing lots of apostrophes: we put the names into a single string, separated just by spaces. And then we call the split() method on that string which splits our string on every whitspace:

>>> 'foo bar  baz'.split()
['foo', 'bar', 'baz']

Letting atelier know where your projects are has the following advantages:

  • You can run the per_project script (or its alias pp) to run a given command over many projects.

  • You can use atelier.sphinxconf.interproject to create Intersphinx links from one project's docs to the docs of another project.

Some more shell aliases

Here are some useful aliases and functions for your ~/.bash_aliases:

alias pp='per_project'
alias runserver='python manage.py runserver'
alias ci='inv ci'
alias p3='. ~/pythonenvs/py3/bin/activate'
alias p2='. ~/pythonenvs/py2/bin/activate'

function pywhich() {
  python -c "import $1; print($1.__file__)"
}
pywhich

Shortcut to quickly show where the source code of a Python module is coming from.

This is useful e.g. when you are having troubles with your virtual environments.

Usage examples

You can now play around in your development environment.

See a list of your atelier projects:

$ pp -l
========= ========= ========================================== ========================
 Project   Status    URL                                        doctrees
--------- --------- ------------------------------------------ ------------------------
 lino      master!   http://www.lino-framework.org              docs
 xl        master    http://www.lino-framework.org              docs
 noi       master    http://noi.lino-framework.org              docs
 cosi      master    http://cosi.lino-framework.org             docs
 avanti    master    http://avanti.lino-framework.org/          docs
 vilma     master    http://vilma.lino-framework.org            docs
 care      master    http://care.lino-framework.org             docs
 tera      master    http://tera.lino-framework.org             docs
 book      master!   http://www.lino-framework.org              docs
 voga      master    http://voga.lino-framework.org             docs
 welfare   master    http://welfare.lino-framework.org          docs, docs_de, docs_fr
 amici     master    http://amici.lino-framework.org            docs
========= ========= ========================================== ========================

Change to ~/repositories/lino and download the latest version of Lino:

$ go lino
$ git pull

Run the full test suite in The lino-book package:

$ go book
$ inv prep test

It happens that I type the following before leaving my computer for getting a cup of coffee:

$ pp -v inv prep test bd pd

Commit all my changes in all my projects before going to bed:

$ pp inv ci

If that happens after midnight:

$ pp inv ci --today 20161222

Footnotes

1

In case you also use the Go programming language on your computer, you should obviously pick another name than "go".

Have LibreOffice server running on your machine

Some of the demo examples use lino_xl.lib.appypod for producing printable pdf files. To have this running, you should install the LibreOffice server on your system as described in Running a LibreOffice server.

Quickly installing the Lino SDK into a new virtualenv

install_dev_projects.sh

Not much tested. Read and follow at your own risk.

Here is how to quickly install the Lino SDK into a new virtualenv:

$ cd ~/repositories
$ sh book/docs/dev/install_dev_projects.sh

Automated way for cloning and installing the code repositories:

$ cd ~/repositories
$ wget https://raw.githubusercontent.com/lino-framework/book/master/docs/dev/install_dev_projects.sh
$ sh install_dev_projects.sh

How to switch to the development version of Atelier

Not much tested. Read and follow at your own risk.

The atelier package had been automatically installed together with lino. That is, you are using the PyPI version of Atelier. That's usually okay because Atelier is more or less stable. But one day we might decide that you should rather switch to the development version.

Doing this is easy:

  1. uninstall the PyPI version and then install the development version:

    $ pip uninstall atelier
    
    $ cd ~/repositories
    $ git clone https://github.com/lino-framework/atelier.git
    $ pip install -e atelier
    
  2. Open your ~/.atelier/config.py file and insert atelier to the list of projects:

    ...
    names = 'atelier lino xl book noi voga presto welfare avanti extjs6'
    ...