Learn about your work environment¶

What is a project?¶

As a Lino contributor you are using atelier, a minimalist 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 Lino sites.
An atelier project usually corresponds to a public code repository (using Git or Mercurial). But you can have unpublished projects that 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).

Not all your atelier projects must be under a single top-level directory. You will have different project base directories containing projects. We suggest the following naming conventions.

~/projects¶: The base directory for every project of which you are the author. You created this directory in Create your first Lino site, and hello is your first local project.

~/repositories¶: The base directory for every atelier project you cloned from GitLab.

Navigating between projects using nicknames ¶

The getlino configure command has created a shell function named go [1] in your ~/.bash_aliases, which looks like this:

function go() {
    for BASE in ~/projects ~/repositories ~/repositories/book/lino_book/projects
    do
      if [ -d $BASE/$1 ] ; then
        cd $BASE/$1;
        return;
      fi
    done
    echo Oops: no project $1
    return -1
}

This adds a new shell command go to your terminal:

go¶: Shortcut to cd to one of your local project directories.

Note that the for BASE in of the go command also loops over the directory ~/repositories/book/lino_book/projects. This directory contains our demo projects.

So you should be able to do:

$ go lino   # cd to ~/repositories/lino
$ go hello  # cd to ~/projects/hello
$ go min1   # cd to ~/repositories/book/lino_book/projects/min1

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:

from pathlib import Path
for root in ["~/projects", "~/repositories"]:
    for p in Path(root).expanduser().iterdir():
        if p.is_dir():
            add_project(str(p))

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 rstgen.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    https://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 Developer Guide:

$ go book
$ inv prep test

Build a local copy of the html documentation Developer Guide:

$ 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 docs.

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

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:

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

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 Install your Lino developer environment).