Skip to content

Commit

Permalink
Merge pull request #2594 from carpentries/feature/eli-docs
Browse files Browse the repository at this point in the history 
Miscellaneous docs updates
  • Loading branch information
@pbanaszkiewicz
pbanaszkiewicz authored Dec 11, 2023
2 parents 47b0e73 + 570cb96 commit d3fde16
Show file tree
Hide file tree
Showing 2 changed files with 61 additions and 52 deletions.
101 changes: 50 additions & 51 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,90 +14,89 @@ who's teaching what, and so on.
AMY is built using [Django][django] with Python 3, with a bit of Javascript and
other things thrown in. If you would like to help, please read:

* the setup instructions below,
* the setup instructions below,

* the [contributor guidelines](.github/CONTRIBUTING.md), and
* the [contributor guidelines](.github/CONTRIBUTING.md), and

* our [contributor code of conduct](.github/CODE_OF_CONDUCT.md).
* our [contributor code of conduct](.github/CODE_OF_CONDUCT.md).

Please [check with us][contact-address] or open an [issue][issues]
before starting work on new features.

## Getting Started

1. Clone the repository:
1. Clone the repository:

~~~
$ git clone https://github.com/carpentries/amy.git
$ cd amy
git clone https://github.com/carpentries/amy.git
cd amy
~~~
1. Configure git to automatically ignore revisions in the `.git-blame-ignore-revs`:
1. Configure git to automatically ignore revisions in the `.git-blame-ignore-revs`:
~~~
$ git config blame.ignoreRevsFile .git-blame-ignore-revs
git config blame.ignoreRevsFile .git-blame-ignore-revs
~~~
1. Install [Pipenv](https://pipenv.pypa.io/en/latest/):
1. Install [Pipenv](https://pipenv.pypa.io/en/latest/):
~~~
$ python -m pip install --user pipenv
python -m pip install --user pipenv
~~~
1. Install Python dependencies:
1. Install Python dependencies:
~~~
$ pipenv sync --dev
pipenv sync --dev
~~~
**Note:**
Pipenv will create a new virtual environment for this installation, so you don't
have to create one yourself.
The `--dev` flag installs development dependencies, required e.g. for testing.
1. Install [node][nodejs] for front-end packages management.
1. Install [node][nodejs] for front-end packages management.
1. Install CSS, JS dependencies with (`npm` was installed in previous step when you
1. Install CSS, JS dependencies with (`npm` was installed in previous step when you
installed `node`):
~~~
$ npm install
npm install
~~~
1. Start running a local instance of Postgres and Redis. This requires Docker to be installed locally. Redis is required to have certain features (like creating a new person and viewing a workshop request) work correctly.
1. Start running a local instance of Postgres and Redis. This requires Docker to be installed locally. Redis is required to have certain features (like creating a new person and viewing a workshop request) work correctly.
~~~
$ docker compose -f docker/docker-compose.yml -p amy up -d database redis
docker compose -f docker/docker-compose.yml -p amy up -d database redis
~~~
1. Set up your local database with fake (development-ready) data. This will create a superuser with "admin" as both the username and password.
1. Set up your local database with fake (development-ready) data. This will create a superuser with "admin" as both the username and password.
~~~
$ pipenv run make dev_database
pipenv run make dev_database
~~~
1. Start a local Django development server by running:
1. Start a local Django development server by running:
~~~
$ pipenv run make serve
pipenv run make serve
~~~
**Note**: this also installs front-end dependencies for AMY, including [jQuery][jquery] and [Bootstrap][bootstrap] ([full list here](https://github.com/carpentries/amy/blob/develop/package.json)).
1. Open <http://127.0.0.1:8000/workshops/> in your browser and start clicking. Use the default "admin" as username and password.
1. Open <http://127.0.0.1:8000/workshops/> in your browser and start clicking. Use the default "admin" as username and password.
1. Shut down the local server by typing `Ctrl-C`. Shut down the Docker Redis instance with:
~~~
$ docker compose -f docker/docker-compose.yml -p amy down
docker compose -f docker/docker-compose.yml -p amy down
~~~
## How to build the docker image?
```shell
$ LAST_COMMIT=`git rev-parse --short HEAD`
$ docker build -t amy:latest -t amy:${LAST_COMMIT} --label commit=${LAST_COMMIT} -f docker/Dockerfile .
LAST_COMMIT=`git rev-parse --short HEAD`
docker build -t amy:latest -t amy:${LAST_COMMIT} --label commit=${LAST_COMMIT} -f docker/Dockerfile .
```
First command sets `LAST_COMMIT` environment variable to short commit hash of the
Expand All @@ -108,79 +107,79 @@ directory) with tags `amy:latest` and `amy:LAST_COMMIT`.
## Upgrading
1. Update the code:
1. Update the code:
1. Get the list of changes:
1. Get the list of changes:
~~~
$ git fetch
git fetch
~~~
1. Look for the newest tag:
1. Look for the newest tag:
~~~~
$ git tag -n
git tag -n
~~~~
1. Get the code from the newest tag:
1. Get the code from the newest tag:
~~~~
$ git checkout tags/<tag_name>
git checkout tags/<tag_name>
~~~~
1. Update dependencies front-end and back-end dependencies:
1. Update dependencies front-end and back-end dependencies:
~~~
$ pipenv run make upgrade
pipenv run make upgrade
~~~
1. (Optional) make fresh development-ready database:
1. (Optional) make fresh development-ready database:
~~~
$ pipenv run make dev_database
pipenv run make dev_database
~~~
**Note**: this command requires removing (by hand) the old database file.
1. Run database migrations:
1. Run database migrations:
~~~~
$ pipenv run python manage.py migrate
pipenv run python manage.py migrate
~~~~
1. Enjoy your new version of AMY:
1. Enjoy your new version of AMY:
~~~
$ pipenv run make serve
pipenv run make serve
~~~
## Start hacking on email automation
1. Make sure you have Redis running. See instructions above.
1. Create dev database (it will add a super user and predefined database entries, too!):
```shell
$ pipenv run make dev_database
pipenv run make dev_database
```
1. Run the server:
```shell
$ pipenv run python manage.py runserver
pipenv run python manage.py runserver
```
1. Run the RQ worker and scheduler (use separate terminals or processes for each
command):
```shell
$ pipenv run python manage.py rqworker
$ pipenv run python manage.py rqscheduler
pipenv run python manage.py rqworker
pipenv run python manage.py rqscheduler
```
## Run accessibility tests locally
Accessibility tests are run with [Google Lighthouse](https://github.com/GoogleChrome/lighthouse) and [Pa11y](https://pa11y.org) as part of the CI process. It's sometimes helpful to run these programs locally to debug or test changes. For more information on the tests, see the [accessibility tests documentation](docs/accessibility_testing.md)
Accessibility tests are run with [Pa11y](https://pa11y.org) and optionally [Google Lighthouse](https://github.com/GoogleChrome/lighthouse) as part of the CI process. It's sometimes helpful to run these programs locally to debug or test changes. For more information on the tests, see the [accessibility tests documentation](docs/accessibility_testing.md)
For both Lighthouse and pa11y tests, Google Chrome or Chromium must be installed. On Ubuntu:
Expand Down Expand Up @@ -217,14 +216,16 @@ Pa11y will exit with a failure code if accessibility failures are found. Reports
## Edit the CSS theme
The AMY theme is primarily based on Bootstrap 4.
The AMY theme is primarily based on Bootstrap 4.
To update the custom CSS that sits on top of the Bootstrap theme, edit `amy/static/css/amy.css`.
To override Bootstrap 4 defaults such as colors, edit the [Sass](https://sass-lang.com/) file `amy/static/scss/custom_bootstrap.scss` as required, then compile it to CSS:
```shell
$ npx sass amy/static/scss/custom_bootstrap.scss amy/static/css/custom_bootstrap.min.css --style compressed
npx sass amy/static/scss/custom_bootstrap.scss amy/static/css/custom_bootstrap.min.css --style compressed
```
See the [Bootstrap documentation](https://getbootstrap.com/docs/4.0/getting-started/theming/) for more guidance on overriding Bootstrap defaults.
[bootstrap]: https://getbootstrap.com/
Expand All @@ -233,6 +234,4 @@ See the [Bootstrap documentation](https://getbootstrap.com/docs/4.0/getting-star
[jquery]: https://jquery.com/
[issues]: https://github.com/carpentries/amy/issues
[tc]: https://carpentries.org/
[virtualenv]: https://virtualenv.pypa.io/en/latest/userguide.html
[venv]: https://docs.python.org/3/library/venv.html
[nodejs]: https://nodejs.org/en/
12 changes: 11 additions & 1 deletion docs/accessibility_testing.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,17 @@

## Automated Testing

The automated tests aim to test one page corresponding to each template in `amy/templates` (including base templates and the `includes` subfolder).
The automated tests aim to test one page corresponding to each template in `amy/templates` (including base templates and the `includes` subfolder). New templates should have a corresponding URL added to the [`.pa11yci`](https://github.com/carpentries/amy/blob/develop/.pa11yci) config file. As such, templates added since the last update to `.pa11yci` are not tested.

### Workflow

The [GitHub Actions workflow](https://github.com/carpentries/amy/blob/develop/.github/workflows/accessibility.yml) includes options for testing with both [pa11y](https://pa11y.org/) and [Google Lighthouse](https://github.com/GoogleChrome/lighthouse). In both cases, the report can be found in the artifacts attached to the workflow run. The report contains one HTML file for each page covered by the tests, plus a summary file (something like `index.html`).

### Local testing

See the [AMY README](https://github.com/carpentries/amy#run-accessibility-tests-locally) for instructions on running the tests on your own machine.

### Limitations

The following pages cannot be effectively tested automatically at the moment. Problems include:

Expand Down

0 comments on commit d3fde16

Please sign in to comment.