Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: add details to CSS generation #2623

Merged
merged 3 commits into from
Sep 30, 2024
Merged

docs: add details to CSS generation #2623

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
52fa3b1
docs: add details to CSS generation
JacobCoffee Sep 30, 2024
fe231e4
docs: no NBSP
JacobCoffee Sep 30, 2024
04b031b
docs: note automatic compiles
JacobCoffee Sep 30, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 23 additions & 18 deletions docs/source/install.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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
Expand All @@ -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
Expand All @@ -135,25 +135,25 @@ 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 = {
'default': dj_database_url.parse('postgres:///your_database_name'),
}
```

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:
Expand All @@ -162,15 +162,15 @@ 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
$ 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:
Expand All @@ -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:

Expand All @@ -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
-------------
Expand All @@ -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
---------------
Expand Down