Improve documentation, especially for new developers #11
Comments
jmurty
added a commit
that referenced
this issue
Feb 20, 2018
jmurty
added a commit
that referenced
this issue
Feb 22, 2018
- add more explanation about what ixc-django-docker is and does - more explanation for how we think of settings - basic description of the DOTENV envvar - full listing and summary of settings module files included in project - re-ordered secret-handling tools to put preferred Transcrypt first - improved internal linking - a more rigorous document heading hierarchy.
mrmachine
added a commit
that referenced
this issue
Feb 25, 2018
* 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.
jmurty
added a commit
that referenced
this issue
Mar 6, 2018
More improvements to documentation, re #11
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
In #10 we discussed whether there was a way to reduce the complexity and black magic for defining and loading settings for projects based on
ixc-django-docker, but alternative approaches were not promising.Let's try improving the documentation for settings, and usage in general, to see if this will be enough to solve at least the common issues to
The text was updated successfully, but these errors were encountered: