From 7028a03f5c916e6c92ada430e8a85947985b8b45 Mon Sep 17 00:00:00 2001 From: bronsen <kontakt+gitcommit@nrrd.de> Date: Tue, 18 Mar 2025 18:32:38 +0100 Subject: [PATCH] [readme] rebuild TOC --- README.md | 70 +++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 52 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index fbfbaac..5283c1b 100644 --- a/README.md +++ b/README.md @@ -8,17 +8,21 @@  <!--toc:start--> - -- [Development](#development) - - [Getting started](#getting-started) - - [Python](#python) - - [PostgreSQL](#postgresql) - - [Get the code](#get-the-code) - - [Making changes](#making-changes) - - [Using the App](#using-the-app) -- [Dependency management](#dependency-management) - - [Installing dependencies](#installing-dependencies) - +- [Teilchensammler: Collect parts in a list](#teilchensammler-collect-parts-in-a-list) + - [Badges](#badges) + - [Development](#development) + - [Getting started](#getting-started) + - [Python](#python) + - [PostgreSQL](#postgresql) + - [Get the code](#get-the-code) + - [Making changes](#making-changes) + - [Using the App](#using-the-app) + - [Dependency management](#dependency-management) + - [Installing dependencies](#installing-dependencies) + - [More on tools that are used](#more-on-tools-that-are-used) + - [Direnv (automatic venv)](#direnv-automatic-venv) + - [Subshells or Shells started from Editors](#subshells-or-shells-started-from-editors) + - [just](#just) <!--toc:end--> ## Development @@ -46,9 +50,11 @@ installed by [homebrew]). #### PostgreSQL -Set up PostgreSQL, a role and a schema. I have it on localhost, using the -project name for role and schema name, and password. See `.env.test` for -providing connection information. +Set up PostgreSQL, a role and a schema. + +I have it on localhost, using the project name for role and schema name, and +password. Using a VM, docker or even a remote instance is possible: See +`.env.test` for providing connection information. #### Get the code @@ -62,19 +68,20 @@ don't have just). ### Making changes Change code, settings, templates, dependencies as you see fit. Run `just lint` -repeatedly. Don't forget migrations. Commit often. +repeatedly. Don't forget migrations. Commit often. Please add tests. ### Using the App `just serve` and open -[localhost:8000/collector](http://localhost:8000/collector/) in your browser. +[localhost:8000/](http://localhost:8000/collector/) in your browser. Start +entering Teile. ## Dependency management This project uses [pip-compile-multi] for hard-pinning dependencies versions. Please see its documentation for usage instructions. In short, -`requirements/base.in` contains the list of direct requirements with occasional -version constraints (like `Django<2`) and `requirements/base.txt` is +`requirements/prod.in` contains the list of direct requirements with occasional +version constraints (like `Django<2`) and `requirements/prod.txt` is automatically generated from it by adding recursive tree of dependencies with fixed versions. The same goes for `test` and `dev`. @@ -102,6 +109,33 @@ testing requirements and development tools. A useful command is `pip-sync requirements/dev.txt`, it uninstalls packages from your virtualenv that aren't explicitly specified as dependencies. +## More on tools that are used + +These are not strictly necessary but very convenient. + +### Direnv (automatic venv) + +When direnv is [integrated into the shell](https://direnv.net/docs/hook.html) +entering the project directory for the first time will cause direnv to create a +hidden directory for the virtual environment. + +It will also activate that existing virtualenv automatically upon entering the +project directory. + +#### Subshells or Shells started from Editors + +If your editor spawns a shell window or new terminal, it might be necessary to +`direnv reload` before running any commands. This will make sure direnv has +things set up. neovim's terminal requires this. + +### just + +[just] is used as a task runner. Think "makefile" but less confusing. (make is +a build tool and task runner and much more, just intends to be a task runner.) + +If you don't want to install just, you can still look at its `justfile` to see +how test runners, linters, dev servers and such are to be executed. + ---- [pip-compile-multi]: https://pypi.org/project/pip-compile-multi/