diff --git a/docs/source/install.md b/docs/source/install.md index c91d1bd59..55cf483fb 100644 --- a/docs/source/install.md +++ b/docs/source/install.md @@ -88,7 +88,7 @@ This is a simple wrapper around running `python manage.py` in the container, all Manual setup ------------ -First, install [PostgreSQL](https://www.postgresql.org/download/) on your machine and run it. *pythondotorg* currently uses Postgres 15.x. +First, install [PostgreSQL](https://www.postgresql.org/download/) on your machine and run it. *pythondotorg* currently uses Postgres 15.x. Then clone the repository: @@ -102,13 +102,13 @@ Then create a virtual environment: $ python3 -m venv venv ``` -And then you'll need to install dependencies. You don't need to use `pip3` inside a Python 3 virtual environment: +And then you'll need to install dependencies. You don't need to use `pip3` inside a Python 3 virtual environment: ``` $ pip install -r dev-requirements.txt ``` -*pythondotorg* will look for a PostgreSQL database named `pythondotorg` by default. Run the following command to create a new database: +*pythondotorg* will look for a PostgreSQL database named `pythondotorg` by default. Run the following command to create a new database: ``` $ createdb pythondotorg -E utf-8 -l en_US.UTF-8 @@ -121,7 +121,7 @@ If the above command fails to create a database and you see an error message sim createdb: database creation failed: ERROR: permission denied to create database ``` -Use the following command to create a database with *postgres* user as the owner: +Use the following command to create a database with *postgres* user as the owner: ``` $ sudo -u postgres createdb pythondotorg -E utf-8 -l en_US.UTF-8 @@ -135,10 +135,10 @@ If you get an error like this: createdb: database creation failed: ERROR: new collation (en_US.UTF-8) is incompatible with the collation of the template database (en_GB.UTF-8) ``` -Then you will have to change the value of the `-l` option to what your database was set up with initially. +Then you will have to change the value of the `-l` option to what your database was set up with initially. ```` -To change database configuration, you can add the following setting to `pydotorg/settings/local.py` (or you can use the `DATABASE_URL` environment variable): +To change database configuration, you can add the following setting to `pydotorg/settings/local.py` (or you can use the `DATABASE_URL` environment variable): ``` DATABASES = { @@ -146,14 +146,14 @@ DATABASES = { } ``` -If you prefer to use a simpler setup for your database you can use SQLite. Set the `DATABASE_URL` environment variable for the current terminal session: +If you prefer to use a simpler setup for your database you can use SQLite. Set the `DATABASE_URL` environment variable for the current terminal session: ``` $ export DATABASE_URL="sqlite:///pythondotorg.db" ``` ```{note} -If you prefer to set this variable in a more permanent way add the above line in your `.bashrc` file. Then it will be set for all terminal sessions in your system. +If you prefer to set this variable in a more permanent way add the above line in your `.bashrc` file. Then it will be set for all terminal sessions in your system. ``` Whichever database type you chose, now it's time to run migrations: @@ -162,7 +162,7 @@ Whichever database type you chose, now it's time to run migrations: $ ./manage.py migrate ``` -To compile and compress static media, you will need *compass* and *yui-compressor*: +To compile and compress static media, you will need *compass* and *yui-compressor*: ``` $ gem install bundler @@ -170,7 +170,7 @@ $ bundle install ``` ```{note} -To install *yui-compressor*, use your OS's package manager or download it directly then add the executable to your `PATH`. +To install *yui-compressor*, use your OS's package manager or download it directly then add the executable to your `PATH`. ``` To create initial data for the most used applications, run: @@ -179,7 +179,7 @@ To create initial data for the most used applications, run: $ ./manage.py create_initial_data ``` -See [create_initial_data](https://pythondotorg.readthedocs.io/commands.html#command-create-initial-data) for the command options to specify while creating initial data. +See `pythondotorg`[create_initial_data](https://pythondotorg.readthedocs.io/commands.html#command-create-initial-data) for the command options to specify while creating initial data. Finally, start the development server: @@ -190,19 +190,24 @@ $ ./manage.py runserver Optional: Install Elasticsearch ------------------------------- -The search feature in Python.org uses Elasticsearch engine. If you want to test out this feature, you will need to install [Elasticsearch](https://www.elastic.co/downloads/elasticsearch). +The search feature in Python.org uses Elasticsearch engine. If you want to test out this feature, you will need to install [Elasticsearch](https://www.elastic.co/downloads/elasticsearch). -Once you have it installed, update the URL value of `HAYSTACK_CONNECTIONS` settings in `pydotorg/settings/local.py` to your local ElasticSearch server. +Once you have it installed, update the URL value of `HAYSTACK_CONNECTIONS` settings in `pydotorg/settings/local.py` to your local ElasticSearch server. Generating CSS files automatically ---------------------------------- -Due to performance issues of [django-pipeline](https://github.com/jazzband/django-pipeline/issues/313), we are using a dummy compiler `pydotorg.compilers.DummySASSCompiler` in development mode. To generate CSS files, use `sass` itself in a separate terminal window: +```{warning} +When editing frontend styles, ensure you ONLY edit the `.scss` files. +These will then be compiled into `.css` files automatically. ``` -$ cd static -$ sass --compass --scss -I $(dirname $(dirname $(gem which susy))) --trace --watch sass/style.scss:sass/style.css -``` + +Static files are automatically compiled inside the [Docker Compose `static` container](../../docker-compose.yml) +when running `make serve`. + +When your pull request has stylesheet changes, commit the `.scss` files and the compiled `.css` files. +Otherwise, ignore committing and pushing the `.css` files. Running tests ------------- @@ -220,7 +225,7 @@ $ coverage run manage.py test $ coverage report ``` -Generate an HTML report with `coverage html` if you like. +Generate an HTML report with `coverage html` if you like. Useful commands ---------------