Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
More improvements to documentation, re #11
* Expand on the purpose of this repository with a short bullet point list of goals, and the two major components. * Make a clear distinction between the `ixc_django_docker` Python package, which is an actual Django "project" (settings, URLs, etc.), which is expected to "wrap" minimal client projects, and the `project_template` directory, which is an example of a "wrapped" minimal project template. * Only capitalise the first word and proper nouns in section headings, as per Django guidelines. Long sentences in "Title Case" are often inconsistently or incorrectly capitalised and visually heavy. See: https://docs.djangoproject.com/en/dev/internals/contributing/writing-documentation/#guidelines-for-restructuredtext-files * Simplify hierarchy of nested sections to be max 3 levels deep. Any more than this is difficult to differentiate when reading as plain text as we need more and more different but seemingly equally weighted syntax. * Add dedicated sections to the `ixc_django_docker` project wrapper and the wrapped `project_template`, each with a fairly complete bullet point list of included features. Some of these features were previously listed in the general overview, as features of the `ixc-django-docker` repository. * Rename `environment` settings as `override` settings to match the corresponding `OVERRIDE_SETTINGS` environment variable, and avoid confusion with actual environment variables from *dotenv* files. * Add fourth "*dotenv* environment variables" bullet point to the composable settings hierarchy. * Note where base, project, override and dotenv settings and environment variables are *actually* included from. * Liberal use of **NOTE:** and **WARNING:** throughout for important and potentially dangerous information. * Include more links to 3rd party projects and docs, e.g. anything enabled by optional settings modules. * List bundled base settings before bundled override settings, in two separate sections. * Describe `go.sh` environment not as "simulated Docker". It's really just configuring PATH etc. so we can use the same shell scripts. * Explain that even when running without Docker, you can use Docker for required services. WIP: A few documentation changes that don't have actual corresponding code changes: * Move the client project hooks all into an `ixcproject` package to avoid unnecessary clutter in the project root directory and avoid any namespace conflicts with 3rd party packages. E.g. `ixcproject.settings`, `ixcproject.urls`, `ixcproject.context_processors`, etc. * A one-liner to download and execute a `startproject.sh` script to actually create a new client project from the project template. * A management command to copy files from the project template (to be bundled within the `ixc_django_docker` Python package) to your project root directory, so you can just upgrade `ixc-django-docker`, run the management command, then use your merge tool to undo or commit changes as required. * Add some **TODO:** sections.
- Loading branch information