From 04d191fe7c7ba4922d15cb5276cff0dfa274e388 Mon Sep 17 00:00:00 2001 From: "Christopher C. Wells" Date: Sun, 31 Oct 2021 15:11:07 -0700 Subject: [PATCH] Review and revise documentation language --- docs/API.md | 55 ++++++++++++++++++++----------------------- docs/CONFIGURATION.md | 39 ++++++++++++++++-------------- docs/CONTRIBUTING.md | 36 ++++++++++++++-------------- docs/DEPLOYMENT.md | 14 +++++------ docs/IMPORT_EXPORT.md | 6 ++--- 5 files changed, 75 insertions(+), 75 deletions(-) diff --git a/docs/API.md b/docs/API.md index 40440ba6..1749862d 100644 --- a/docs/API.md +++ b/docs/API.md @@ -4,9 +4,10 @@ Baby Buddy uses the [Django REST Framework](https://www.django-rest-framework.org/) (DRF) to provide a REST API. -The only requirement for (most) requests is that the `Authorization` header is -set as described in the [Authentication](#authentication) section. The one -exception is the `/api` endpoint, which lists all available endpoints. +The only requirement for (most) requests is to set the `Authorization` header as +described in the [Authentication](#authentication) section. The one exception is +the `/api` endpoint, which lists all available endpoints and does not require +authorization. Currently, the following endpoints are available for `GET`, `OPTIONS`, and `POST` requests: @@ -23,29 +24,28 @@ Currently, the following endpoints are available for `GET`, `OPTIONS`, and ## Authentication -By default, the [TokenAuthentication](https://www.django-rest-framework.org/api-guide/authentication/#tokenauthentication) +The [TokenAuthentication](https://www.django-rest-framework.org/api-guide/authentication/#tokenauthentication) and [SessionAuthentication](https://www.django-rest-framework.org/api-guide/authentication/#sessionauthentication) -classes are enabled. Session authentication covers local API requests made by +are enabled by default. Session authentication covers local API requests made by the application itself. Token authentication allows external requests to be made. :exclamation: **In a production environment, token authentication should only be used for API calls to an `https` endpoint.** :exclamation: -Each user is automatically assigned an API key that can be used for token -authentication. This key can be found on the User Settings page for the logged -in the user. To use a key for an API request, set the request `Authorization` -header to `Token `. E.g. +Each user has an API key that can be used for token authentication. This key can +be found on the User Settings page for the logged in the user. To use a key for +an API request, set the request `Authorization` header to `Token `. E.g. Authorization: Token 2h23807gd72h7hop382p98hd823dw3g665g56 -If the `Authorization` header is not set or the key is not valid, the API will -return `403 Forbidden` with additional details in the response body. +If no `Authorization` header set, or the key is not valid the API will return +`403 Forbidden` with additional details in the response body. ## Schema -API schema information in the [OpenAPI format](https://swagger.io/specification/) -can be found in the [`openapi-schema.yml`](/openapi-schema.yml) file in the project +The API schema in [OpenAPI format](https://swagger.io/specification/) can be +found in the [`openapi-schema.yml`](/openapi-schema.yml) file in the project root. A live version is also available at the `/api/schema` path of a running instance. @@ -166,27 +166,25 @@ formats. ### Timer Field The "timer" field is a special field available for `POST` operations to model -endpoints supporting duration (Feeding, Sleep, Tummy Time). When the "timer" -field is set in the request, the `start` and `end` fields will be filled in -automatically using the `start` and `end` values *from the Timer* (the Timer -will be stopped if it is currently running). +endpoints supporting duration (Feeding, Sleep, Tummy Time). Se the "timer" +in a request to fill in the `start` and `end` fields automatically using the +`start` and `end` values *from the Timer* (the Timer will be stopped if it is +currently running). Additionally, if the Timer has a Child relationship, the `child` field will be filled in automatically use the `child` value from the Timer. -If the "timer" field is set, it's values will **always override** the relevant -fields in the request. E.g. if a `POST` request is sent with both the `timer` -and `end` fields, the value for the `end` field will be ignored and replaced by -the Timer's `end` value. The same applies for `start` and `child`. These fields -can all be left out of the request when the Timer is provided, otherwise they -are required fields. +The "timer" field will **always override** the relevant fields (`child`, `start`, +and `end`) on the request. E.g., a `POST` request with both the `timer` and `end` +fields will ignore the `end` field value and replace it with the Timer's `end` +value. The same applies for `start` and `child`. These fields are all **required** +if the `timer` field is *not* set. ### Response Returns JSON data in the response body describing the added/updated instance or -error details if errors exist. Errors are keyed by either the field in error or -the general string `non_field_errors` (usually when validation involves -multiple fields). +error details keyed by either the field in error or the general string `non_field_errors` +(e.g., when validation involves multiple fields). ## `PATCH` Method @@ -210,9 +208,8 @@ formats. ### Response Returns JSON data in the response body describing the added/updated instance or -error details if errors exist. Errors are keyed by either the field in error or -the general string `non_field_errors` (usually when validation involves -multiple fields). +error details keyed by either the field in error or the general string `non_field_errors` +(e.g., when validation involves multiple fields). ## `DELETE` Method diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index 8f29383b..22eb87c0 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -29,9 +29,8 @@ take precedence over the contents of an `.env` file.** *Default: * (any)* -This option may be set to a single host or comma-separated list of hosts -(without spaces). This should *always* be set to a specific host or hosts in -production deployments. +Set this variable to a single host or comma-separated list of hosts without spaces. +This should *always* be set to a specific host or hosts in production deployments. See also: [Django's documentation on the ALLOWED_HOSTS setting](https://docs.djangoproject.com/en/3.0/ref/settings/#allowed-hosts) @@ -39,9 +38,8 @@ See also: [Django's documentation on the ALLOWED_HOSTS setting](https://docs.dja *Default: True* -Whether or not to allow uploads (e.g. of Child photos). For some deployments -(AWS, Heroku) this setting will default to False due to the lack of available -persistent storage. +Whether to allow uploads (e.g., of Child photos). For some deployments (Heroku) +this setting will default to False due to the lack of available persistent storage. ## `AWS_ACCESS_KEY_ID` @@ -66,7 +64,7 @@ See also: [`AWS_STORAGE_BUCKET_NAME`](#aws_storage_bucket_name) *Default: None* If you would like to use AWS S3 for storage on ephemeral storage platforms like -Heroku you will need to create a bucket and add it's name. See django-storages' +Heroku you will need to create a bucket and add its name. See django-storages' [Amazon S3 documentation](https://django-storages.readthedocs.io/en/latest/backends/amazon-S3.html). ## `DEBUG` @@ -82,15 +80,15 @@ See also [Django's documentation on the DEBUG setting](https://docs.djangoprojec *Default: 18:00* -The maximum *start* time (in the instance's time zone) before which a sleep -entry is consider a nap. Expects the 24-hour format %H:%M. +The maximum nap *start* time (in the instance's time zone). Expects the 24-hour +format %H:%M. ## `NAP_START_MIN` *Default: 06:00* -The minimum *start* time (in the instance's time zone) after which a sleep -entry is considered a nap. Expects the 24-hour format %H:%M. +The minimum nap *start* time (in the instance's time zone). Expects the 24-hour +format %H:%M. ## `DB_ENGINE` @@ -98,7 +96,7 @@ entry is considered a nap. Expects the 24-hour format %H:%M. The database engine utilized for the deployment. -See also [Django's documentation on the ENGINE setting](https://docs.djangoproject.com/en/3.0/ref/settings/#engine) . +See also [Django's documentation on the ENGINE setting](https://docs.djangoproject.com/en/3.0/ref/settings/#engine). ## `DB_HOST` @@ -116,7 +114,8 @@ The name of the database table utilized for the deployment. *No Default* -The password for the database user for the deployment. In the default example, this is the root PostgreSQL password. +The password for the database user for the deployment. In the default example, +this is the root PostgreSQL password. ## `DB_PORT` @@ -143,9 +142,13 @@ See also [Django's documentation on the SECRET_KEY setting](https://docs.djangop *Default: None* -If Baby Buddy is behind a proxy, you may need to set this to True. This tells Baby Buddy to trust the X-Forwarded-Proto header that comes from your proxy, and any time its value is 'https', then the request is guaranteed to be secure (i.e., it originally came in via HTTPS). +If Baby Buddy is behind a proxy, you may need to set this to `True` in order to +trust the `X-Forwarded-Proto` header that comes from your proxy, and any time +its value is "https". This guarantees the request is secure (i.e., it originally +came in via HTTPS). -:warning: Modifying this setting can compromise Baby Buddy’s security. Ensure you fully understand your setup before changing it. +:warning: Modifying this setting can compromise Baby Buddy’s security. Ensure +you fully understand your setup before changing it. See also [Django's documentation on the SECURE_PROXY_SSL_HEADER setting](https://docs.djangoproject.com/en/3.0/ref/settings/#secure-proxy-ssl-header). @@ -162,12 +165,12 @@ settings form. *Default: False* Whether to force 24-hour time format for locales that do not ordinarily use it -(e.g. `en`). Support for this feature must implemented on a per-locale basis. +(e.g. `en`). Support for this feature must be implemented on a per-locale basis. See format files under [`babybuddy/formats`](/babybuddy/formats) for supported locales. -Note: This value for this setting is interpreted as a boolean from a string +Note: Baby Buddy interprets this value as a boolean from a string using Python's built-in [`strtobool`](https://docs.python.org/3/distutils/apiref.html#distutils.util.strtobool) -tool. Only certain strings are supported (e.g. "True" for `True` and "False" for +tool. Only certain strings will work (e.g., "True" for `True` and "False" for `False`), other unrecognized strings will cause a `ValueError` and prevent Baby Buddy from loading. diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 8092dd59..2cf67caf 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -1,7 +1,7 @@ # Contributing [Back to Table of Contents](/docs/TOC.md) -Contributions are accepted and encouraged via GitHub [Issues](https://github.com/babybuddy/babybuddy/issues) +Baby Buddy's maintainers accept and encourage contributions via GitHub [Issues](https://github.com/babybuddy/babybuddy/issues) and [Pull Requests](https://github.com/babybuddy/babybuddy/pulls). Maintainers and users may also be found at [babybuddy/Lobby](https://gitter.im/babybuddy/Lobby) on Gitter. @@ -12,19 +12,18 @@ on Gitter. 1. Make and commit tests for any new features or major functionality changes. 1. Run `gulp lint` and `gulp test` (see [Gulp Commands](#gulp-commands)) and ensure that all tests pass. -1. If changes are made to assets: build, collect and commit the `/static` - folder (see [`gulp collectstatic`](#collectstatic)). +1. Updated static assets if necessary and commit the `/static` folder (see [`gulp updatestatic`](#updatestatic)). 1. Open a [new pull request](https://github.com/babybuddy/babybuddy/compare) against the `master` branch. -New pull requests will be reviewed by project maintainers as soon as possible -and we will do our best to provide feedback and support potential contributors. +Maintainers will review new pull requests will as soon as possible, and we will +do our best to provide feedback and support potential contributors. ## Translation ### POEditor -Baby Buddy is set up as a project on [POEditor](https://poeditor.com/). +Baby Buddy uses [POEditor](https://poeditor.com/) for translation contributions. Interested contributors can [join translation of Baby Buddy](https://poeditor.com/join/project/QwQqrpTIzn) for access to a simple, web-based frontend for adding/editing translation files to the project. @@ -37,8 +36,8 @@ process will look something like this: 1. Set up a development environment (see [Development](#development) below). 1. Run `gulp makemessages -l xx` where `xx` is a specific locale code in the -[ISO 639-1 format](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) (e.g. -"fr" for French or "es" for Spanish). This creates a new translation file at +[ISO 639-1 format](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) (e.g., +"il" for Italian or "es" for Spanish). This creates a new translation file at `locale/xx/LC_MESSAGES/django.po`, or updates one if it exists. 1. Open the created/updated `django.po` file and update the header template @@ -114,8 +113,8 @@ documentation section: [Translation](https://docs.djangoproject.com/en/3.0/topic export DJANGO_SETTINGS_MODULE=babybuddy.settings.development This process will differ based on the host OS. The above example is for - Linux-based systems. See [Configuration](#configuration) for other settings - and methods for defining them. + Linux-based systems. See [Configuration](/docs/CONFIGURATION.md) for other + settings and methods for defining them. 1. Migrate the database @@ -133,13 +132,14 @@ documentation section: [Translation](https://docs.djangoproject.com/en/3.0/topic restart the server as needed. Open [http://127.0.0.1:8000](http://127.0.0.1:8000) and log in with the default -user name and password (`admin`/`admin`). +username and password (`admin`/`admin`). ### Gulp commands -Baby Buddy's Gulp commands are defined and configured by files in the -[`gulpfile.js`](gulpfile.js) folder. Django's management commands are defined -in the [`babybuddy/management/commands`](babybuddy/management/commands) folder. +[`gulpfile.js`](gulpfile.js) defines Baby Buddy's Gulp commands. + +[`babybuddy/management/commands`](babybuddy/management/commands) defines Baby Buddy's +management commands. - [`gulp`](#gulp) - [`gulp build`](#build) @@ -165,7 +165,7 @@ in the [`babybuddy/management/commands`](babybuddy/management/commands) folder. Executes the `build` and `watch` commands and runs Django's development server. This command also accepts the special parameter `--ip` for setting the -development server IP address. See [`gulp runserver`](#runserver) for details. +server IP address. See [`gulp runserver`](#runserver) for details. #### `build` @@ -248,7 +248,7 @@ Executes Django's `runserver` management task. Gulp passes non-overlapping arguments for this command. A special parameter, `--ip`, is also available to set the IP for the server. -E.g execute `gulp runserver --ip 0.0.0.0:8000` to make the server available to +E.g., execute `gulp runserver --ip 0.0.0.0:8000` to make the server available to other devices on your local network. #### `scripts` @@ -285,8 +285,8 @@ order: - [`build`](#build) - [`collectstatic`](#collectstatic) -This command should be executed, and any changes committed, any time changes -are made to Baby Buddy's frontend code (SASS, JS, etc.). +Execute and commit changes made by this command whenever changing Baby Buddy's +frontend code (SASS, JS, etc.). ### Icon Font diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md index 535d256a..68d42f93 100644 --- a/docs/DEPLOYMENT.md +++ b/docs/DEPLOYMENT.md @@ -1,8 +1,8 @@ # Deployment [Back to Table of Contents](/docs/TOC.md) -The default user name and password for Baby Buddy is `admin`/`admin`. For any -deployment, **log in and change the default admin password immediately**. +The default username and password for Baby Buddy is `admin`/`admin`. For any +deployment, **log in and change the default password immediately**. Many of Baby Buddy's configuration settings can be controlled using environment variables - see [Configuration](/docs/CONFIGURATION.md) for detailed information. @@ -47,7 +47,7 @@ python3 /app/babybuddy/manage.py clearsessions [![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy) -For manual deployments to Heroku without using the deploy button, make sure to +For manual deployments to Heroku without using the "deploy" button, make sure to create the following settings before pushing: heroku config:set DJANGO_SETTINGS_MODULE=babybuddy.settings.heroku @@ -58,7 +58,7 @@ create the following settings before pushing: See [Configuration](/docs/CONFIGURATION.md) for other settings that can be controlled by `heroku config:set`. -And after an initial push, execute the following commands: +After an initial push, execute the following commands: heroku run python manage.py migrate heroku run python manage.py createcachetable @@ -77,9 +77,9 @@ requirements are Python, a web server, an application server, and a database. ### Example deployment -*This example assumes a 512MB VPS instance with Ubuntu 18.04.* It uses -Python 3.6+, nginx, uwsgi and sqlite and should be sufficient for a few users -(e.g. two parents and 1+ child). +*This example assumes a 512 MB VPS instance with Ubuntu 18.04.* It uses Python 3.6+, +nginx, uwsgi and sqlite. It should be sufficient for a few users(e.g., two parents +and 1+ child). 1. Install system packages diff --git a/docs/IMPORT_EXPORT.md b/docs/IMPORT_EXPORT.md index 590296ab..6ff94f54 100644 --- a/docs/IMPORT_EXPORT.md +++ b/docs/IMPORT_EXPORT.md @@ -36,9 +36,9 @@ be present for an import. Multiple file types -- including csv, xlsx, etc. -- are supported for the import. The import pages do not provide *detailed* information about the required data -and formats. When an import is attempted, all rows will be checked for errors -and any issues will be reported on screen and will need to be resolved before -the import can be performed. +and formats. All rows will be checked for errors on import and any issues will +be reported on screen and will need to be resolved before the import can be +performed. See the [example import files](/core/tests/import) used for tests to get an idea of the expected data format.