Notes on Dallinger installation docs (and other docs too)

Here are some notes on my getting bootstrapped process. Hopefully we can integrate these into the docs. Created an issue first to invite comments as to the best way to update the docs, after which I can create a PR.

This is feedback on http://docs.dallinger.io/en/latest/developing_dallinger_setup_guide.html

I’m on Ubuntu 16.04, using a relatively fresh VM, which means it is likely similar to someone out there who has not yet installed extra development libraries in the their system etc.

I installed python3.6 using the deadsnakes repo: https://launchpad.net/~deadsnakes/+archive/ubuntu/ppa as per https://askubuntu.com/questions/865554/how-do-i-install-python-3-6-using-apt-get

sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt-get update
sudo apt-get install python3.6

---

The following sections have been addressed and incorporated into https://github.com/Dallinger/Dallinger/pull/1110

**Notes on **Install Postgres** section:**

As I saw that _NB: If you have installed an older version of Postgres (e.g., < 10.3)_ was referring to version 10.3 as an old version and Ubuntu 16.04 comes with version 9.5, and I wasn't sure what is the minimum version I need to get dallinger working, I decided to get the latest version of Postgres 10 by following the instructions here: https://www.postgresql.org/download/linux/ubuntu/

* Create the file /etc/apt/sources.list.d/pgdg.list and add a line for the repository
deb http://apt.postgresql.org/pub/repos/apt/ xenial-pgdg main
* Import the repository signing key, and update the package lists
```sudo apt-get update ```
* Ubuntu includes PostgreSQL by default. To install PostgreSQL on Ubuntu, use the apt-get (or other apt-driving) command:
``` sudo apt-get install postgresql-10 ```

Thinking back 9.5 would probably have been fine?? but this was not clear to me at the time.

After installing postgres, ``` Check using psql –version ``` does not work:
I got: 
```witek@ubuntu:~/dev/jazkarta/Dallinger$ psql
psql: FATAL: role "witek" does not exist
```
The solution from the Create the Databases section did not make sense to me, namely:
_If you get a fatal error that your ROLE does not exist, run these commands:
createuser dallinger
dropdb dallinger
createdb -O dallinger dallinger
createdb -O dallinger dallinger-import_

Seems the solution to the fatal role error is to create a user
``` sudo -u postgres createuser --superuser $USER ``` 
as per:  https://stackoverflow.com/questions/15301826/psql-fatal-role-postgres-does-not-exist/31712520#31712520

However this was not required for me to progess on as I manged to ```sudo -u postgres -i``` and use the postgres user to create the necessary user and databases.

At the end of the Install Postgres section:
_After that you’ll need to run the following commands_
```
runuser -l postgres -c "createuser -ds root"
createuser dallinger
createdb -O dallinger dallinger
sed /etc/postgresql/10.3/main/pg_hba.conf -e 's/md5/trust/g' --in-place
sed -e "s/[#]\?listen_addresses = .*/listen_addresses = '*'/g" -i '/etc/postgresql/10.3/main/postgresql.conf'
service postgresql reload
```
This is confusing to me, since it seems here we create the dallinger user and the dallinger database, then do some config adjustments, and the in the next section (Create the Databases) we tell the user to create the dallinger user again and the 2 databases?

Perhaps we can also update the Known Postgres Issues section here http://dallinger.readthedocs.io/en/latest/troubleshooting.html with regards what to do when one gets the fatal role error?

**Notes on **Set up a virtual environment** section:**

I found this section confusing. I did not use pip as I wasn't sure if I had to use pip3 or not? and if there would be issues later with some things installed via pip and others via pip3?? Not sure if that is a valid concern? Nevertheless, I recommend adding a Ubuntu specific mention to this section in the docs:
My process was the following: 
```
sudo aptitude install virtualenv virtualenvwrapper
export WORKON_HOME=$HOME/.virtualenvs
mkdir -p $WORKON_HOME
```
This line was not working in Ubuntu  ``` source $(which virtualenvwrapper.sh) ```
I had to find the location of virtualenvwrapper.sh manually:
``` sudo find / -name virtualenvwrapper.sh ```
which in my case turned out to be in: ``` /usr/share/virtualenvwrapper/virtualenvwrapper.sh ```

After which: ``` source /usr/share/virtualenvwrapper/virtualenvwrapper.sh ```

The rest of the steps worked fine:
```
clone Dallinger repo
mkvirtualenv Dallinger --python /usr/local/bin/python3.6
cd Dallinger
source bin/activate
```

**Notes on **Install prerequisites for building documentation** section:**

_To be able to build the documentation, you will need:_
It is not clear to me if this is an optional step or not? Will most users be building documentation during their interactions with dallinger, or is a special kind of user that will want to create documentation?

The link specified for the Enchant Library is bad as https://pythonhosted.org/pyenchant/download.html no longer exists? I found some information here instead: https://github.com/rfk/pyenchant

What was strange to me is that after running pip install -r dev-requirements.txt both import pyenchant and import pypandoc work inside of python3.6. Before pip install, they both returned ModuleNotFoundError.

**Update**: I propose removing this section entirely as all the requirements for creating documentations are included in the dev-requirements.txt file that is used for installing dallinger for developers.

**Notes on **Install Dallinger** section:**~~

I ran into an issue when running pip install -r dev-requirements.txt.
Namely I was missing python3.6 development files which I explicitly need to get:
``` sudo aptitude install python3.6-dev ```
Running ``` sudo apt-get install python3-dev ``` was not enough since ubuntu 16.04 comes with Python 3.5, it would get the development headers for Python 3.5 instead by default.
~~

[witekdev]

@vlall there are still notes here that have not made it into any docs. Should we keep this issue open or open another?

[vlall]

I still need to test the Mac installation process, however, the instructions @witekdev made are merged.