diff --git a/docs/contributing.rst b/docs/contributing.rst index 8b01b59..6768d59 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -76,59 +76,60 @@ near the top of the docker-compose file; the default set are designed for a local installation, though. -Direct installation +Direct Installation ~~~~~~~~~~~~~~~~~~~ Takahē requires Python 3.10 or above, so you'll need that first. Clone the repo:: git clone https://github.com/jointakahe/takahe/ -Then, ``cd`` into that directory and create and activate a virtual environment -(you can use other options, but this is the basic example):: +The repo comes with a ``Makefile`` that simplifies some of the local development setup: - python3 -m venv .venv - . .venv/bin/activate +*Note: The default* ``make`` *targets use the postgres container from the Docker setup, so once built the db and migrations are already done. See below for instructions on setting up a local PostgreSQL instance for development.* -Then install the development requirements:: +Setup the local python and git environment:: - python3 -m pip install -r requirements-dev.txt + make setup_local -Enable the git commit hooks to do auto-formatting and linting -(if you don't do this, our CI system will reject your PRs until they match):: +Start the postgres db in Docker:: - python3 -m pre_commit install + make startdb -Create a databse in your local PostgreSQL instance:: - - sudo -u postgres createdb takahe - -You will need to set up some (i.e. `TAKAHE_DATABASE_SERVER`) development settings -(you can edit `.env` later):: - - cp development.env .env - -Now you can apply migrations:: - - python3 -m manage migrate +.. _start-web: You can run the web interface to see it at http://localhost:8000:: - python3 -m manage runserver + make runserver You will need to run Stator in order to have background actions work:: - python3 -m manage runstator + make runstator Make yourself a superuser account in order to log in:: - python3 -m manage createsuperuser + make createsuperuser And you can run the tests with pytest:: - python3 -m pytest + make test If you want to edit settings, you can edit the ``.env`` file. +Local PostgreSQL Setup +^^^^^^^^^^^^^^^^^^^^^^ + +Create a database in your local PostgreSQL instance:: + + sudo -u postgres createdb takahe + +Update the ``.env`` file produced by ``make setup_local`` to comment out the Docker-based ``TAKAHE_DATABASE_SERVER`` setting, and uncomment the other one (see the comments in the ``.env`` file). + +Now you can apply migrations:: + + . .venv/bin/activate + python3 -m manage migrate + +With the database connection changed, `the rest <#start-web>`_ of the Direct Installation instructions are the same. Building Documentation ----------------------