This guide presents the tools and projects used for the Poireau project. If you want to quickly install the project for development on Ubuntu 14.04 LTS, please see the ubuntu_install.sh script.
This guide should be enough for you to understand everything on this script before running it, and adapt it to your needs.
Learn how to use Git in a fun way here
Once this is good, you can create a GitHub account, fork this repo to your GitHub account, clone it and start coding. Don't forget GitHub has a nice graphical user interface to install on your machine to manage your local git repositery, for Windows and Mac. For linux, I highy recommand Git-cola.
This project uses Python 3.
There is a really good introduction on programming with Python at intropython.org. Even if you already code in another language, I advise running through the course, as it explains a lot of the Python philosophy and good practices.
There's also a quick python introduction in the Django Tutorial linked in the django section.
I'm going to list the (as far as I can tell) best tools to have to ease development. I'm mainly refering to command line tools. The explanations below will mainly focus on Linux and OSX environment. For windows, there's also a lot of material, including this.
-
Use pip. Pip is a python package manager that will allow instantaneous installation of all needed and unneeded python dependencies. Find information on how to install pip (along with its documentation) here but the simplest way on Linux and OSX is :
curl -L https://bootstrap.pypa.io/get-pip.py | python
On the latest versions of Python (2.7.9, 3.4), if pip is not already installed, the standard python library contains a module, ensurepip that eases the installation of pip. Pip can be added as simply as
python -m ensurepip
With pip, you can install any package by its name by doing
pip install [name]
where name can be a package name on PyPI, a github link, a path to a folder containing a setup.py etc.
Note that when installing to a local path, you can use pip install -e [path] to install in editable mode, which means the modifications made in the folder will be take into account. Otherwise, the package will be copied to the python internal folders and will not have the subsequent modifications.
Another option pip takes is -r to point to a requirements file, a text file with the names and versions of the packages we want to install. There's such a file in the repositery, so you will be able to install all the dependecies automatically.
- A virtual environment is a folder containing a copy of python. Especially, this python has it's own installed packages, independent from the system
python. This allows to install and uninstall packages for a specific project with no interaction with otherspythonprojects you may have on the side, and without the need forsudo.
VirtualEnvs have been added as a standard feature of python3.
Create a virtualenv with
python -m venv ~/Envs/poireau
If you have both python2 and python3 installed on your system, you may need to use explicitely python3 :
python3 -m venv ~/Envs/poireau
This will create a virtual environment folder named poireau in the "Envs" directory in your home. Activate it by calling
source ~/Envs/poireau/bin/activate
on Linux / OSX, see instructions here for Windows.
To deactivate the virtualenv, simply use the command
deactivate
which will be available only when you are "in" a virtualenv. The name of the virtualenv (the name of the folder in which it was created, here "poireau") will be displayed in your prompt once activated.
On Ubuntu 14.04 LTS (Trusty Tahr), a bug renders ensurepip unavailable. The workaround is to create the virtualenv without pip and to install pip manually in the virtual environment :
python3 -m venv --without-pip ~/Envs/poireau
curl -L https://bootstrap.pypa.io/get-pip.py | ~/Envs/poireau/bin/python
Note that once you are in a python3 venv, whatever your system python is, the python command refers to python3.
After making sure the virtualenv is activated, install all the depencies for the project by doing
pip install -r requirements/base.txt
Python is great for, among other things, its live shell that allows trying one's code right away. IPython is a better shell that allows lots of things like memorizing the commands you used to call them again, handle the indentation right etc. Even better, it comes with a nice Web interface named "IPython Notebook" that allows you to run code from your browser.
There are several ways to intall ipython with Notebook. One simple way is :
sudo apt-get install ipython3 ipython3-notebook
Another way is to install it via pip, system wide or just in your environment :
[sudo] pip install "ipython[all]"
but it assumes you have the correct libraries installed for compilation.
Third way, which is like the second way : use the requirements file for local development :
pip install -r requirements/development.txt
If you have any doubts, check the installation instructions.
Finally, note that the Notebook project is about to become "independant" of IPython, and be called Jupyter
As far as I know, the best Django tutorial up to date is the one created by Django Girls, an organization aiming at helping more girls to learn Django. And more boys too. And everyone.
Configure your database (for now with sqlite3, which means you don't need a server or anything) by doing
./manage.py migrate
Once your base is created, with the User table, you'll probably want to have an user that can connect to the site. Create it with :
./manage.py createsuperuser
Another thing you'll need to try the project on the Web is for Django to prepare the static files (js, css, ...) :
./manage.py collectstatic
This command will copy all the static from various location to one dir, that will be accessed when using runserver (see below)
Lilypond is a LaTeX module for creating scores. It's a very powerful tool that can do a lot of things and, as of now, it's the best tool we've found to transform a musicxml file to PDF and sound file. As of now, lilypond notation is generated automatically so for now, there's no real need to learn the lilypond syntax, but it may prove helpful later. Though, you will need to have lilypond installed on your machine if you plan to work on the PDF or Music generation parts.
GetText is a standard opensource tool to manage internationalization. It's used by Django and you'll need to install it if you want to see the Poireau project in your language (and that language is not English)
There's a script that compiles the translations in the script repo. Call it every time you have written new translations to test them. Note : the Git repository does not contain the compiled translations so you'll need to call this script once if you want to see translated text :
./scripts/compilemessages.sh
Now that you master all the tools, you can use it all to navigate to your local git repo, activate your virtual env, and ask django to open an IPython Notebook to launch some code :
./manage.py shell_plus --notebook
You'll find a notebook (Poireau Notebook) that shows how to use some methods in the Django models.
And try the project itself :
./manage.py runserver
And go to http://localhost:8000
You've learned a bunch of modern nice shiny tools that will definitely help you for your coding and python projects. Congratz, you're a python developer now !