Review and revise documentation language

This commit is contained in:
Christopher C. Wells 2021-10-31 15:11:07 -07:00 committed by Christopher Charbonneau Wells
parent 650d864c64
commit 04d191fe7c
5 changed files with 75 additions and 75 deletions

View File

@ -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 <user-key>`. 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 <user-key>`. 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

View File

@ -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 Buddys security. Ensure you fully understand your setup before changing it.
:warning: Modifying this setting can compromise Baby Buddys 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.

View File

@ -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

View File

@ -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

View File

@ -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.