Setting up your work environment

What is a project?

The word project is used for quite a lot of things. There are many types of "projects". For example a Django project is a directory where you can invoke a runserver. It contains at least a settings.py and usually a file manage.py.

But as a Lino contributor you are using atelier, a minimalistic command-line project management tool. Atelier projects have only 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.

Almost every atelier project also contains at least a file tasks.py.

  • One 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 project base directories containing projects. You might not want to have all your projects under a single top-level directory. We suggest the following naming conventions.

~/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.

~/lino/env/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.

Some more shell aliases

The .lino_bash_aliases file (created by getlino and which you should source from your ~/.bash_aliases or ~/.bashrc file) contains some useful aliases and functions. One of them is pywhich:

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.

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. You must create this file yourself, manually:

$ mkdir ~/.atelier
$ nano ~/.atelier/config.py

Add 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 whitespace:

>>> '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.

Usage examples

You can now play around in your "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

Do the same for all your cloned repositories:

$ pp git pull

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

$ go book
$ inv prep test

Build a local copy of the html documentation The lino-book package:

$ go book
$ inv bd

Afterwards you can start your browser on the generated output:

$ firefox docs/.build/index.html

Building the docs might not work out of the box, it is a topic of its own. See Building the Lino Book.

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

$ pp inv prep test bd

This runs in every

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'
    ...
    

Where to store repositories

repositories

A repositories directory is a collection of code repositories of projects for which we cloned a copy.

In a developer environment, this is ~/lino/env/repositories (created by getlino in Installing a Lino developer environment).