Skip to content

Commit

Permalink
More improvements to documentation, re #11
Browse files Browse the repository at this point in the history
* 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
mrmachine committed Feb 25, 2018
1 parent 347a26c commit 96e5882
Showing 1 changed file with 321 additions and 177 deletions.
Loading

0 comments on commit 96e5882

Please sign in to comment.