From 52fa3b1049cdb13078241cb95008cd2f072c808e Mon Sep 17 00:00:00 2001 From: Jacob Coffee Date: Mon, 30 Sep 2024 14:14:25 -0500 Subject: [PATCH 1/3] docs: add details to CSS generation --- docs/source/install.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/docs/source/install.md b/docs/source/install.md index c91d1bd59..0b10c6800 100644 --- a/docs/source/install.md +++ b/docs/source/install.md @@ -197,7 +197,23 @@ Once you have it installed, update the URL value of `HAYSTACK_CONNECTIONS` set 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: +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: + +````{note} +To get up an running with SASS, +you need to [install Ruby 2 (>= 2.0.0, < 3.0.0)](https://www.ruby-lang.org/en/documentation/installation/), +the `sussy` gem, and the `sass` gem. + +The gems are defined in the `Gemfile` and can be installed by running the following command: +```bash +bundle install +``` +```` + +Then run the following command to generate CSS files: ``` $ cd static From fe231e4e01945922162d143f6b5adb4ebeee06da Mon Sep 17 00:00:00 2001 From: Jacob Coffee Date: Mon, 30 Sep 2024 14:15:25 -0500 Subject: [PATCH 2/3] docs: no NBSP --- docs/source/install.md | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/docs/source/install.md b/docs/source/install.md index 0b10c6800..7f13f2dc0 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,17 +190,17 @@ $ ./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. +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: +To generate CSS files, use `sass` itself in a separate terminal window: ````{note} To get up an running with SASS, @@ -236,7 +236,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 --------------- From 04b031beaaeb43d7e5be974a4269bd57237b64fc Mon Sep 17 00:00:00 2001 From: Jacob Coffee Date: Mon, 30 Sep 2024 15:18:36 -0500 Subject: [PATCH 3/3] docs: note automatic compiles --- docs/source/install.md | 25 +++++++------------------ 1 file changed, 7 insertions(+), 18 deletions(-) diff --git a/docs/source/install.md b/docs/source/install.md index 7f13f2dc0..55cf483fb 100644 --- a/docs/source/install.md +++ b/docs/source/install.md @@ -197,28 +197,17 @@ Once you have it installed, update the URL value of `HAYSTACK_CONNECTIONS` setti 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. +```{warning} +When editing frontend styles, ensure you ONLY edit the `.scss` files. -To generate CSS files, use `sass` itself in a separate terminal window: - -````{note} -To get up an running with SASS, -you need to [install Ruby 2 (>= 2.0.0, < 3.0.0)](https://www.ruby-lang.org/en/documentation/installation/), -the `sussy` gem, and the `sass` gem. - -The gems are defined in the `Gemfile` and can be installed by running the following command: -```bash -bundle install +These will then be compiled into `.css` files automatically. ``` -```` -Then run the following command to generate CSS files: +Static files are automatically compiled inside the [Docker Compose `static` container](../../docker-compose.yml) +when running `make serve`. -``` -$ cd static -$ sass --compass --scss -I $(dirname $(dirname $(gem which susy))) --trace --watch sass/style.scss:sass/style.css -``` +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 -------------