mirror of https://github.com/snachodog/mybuddy.git
Review and revise documentation language
This commit is contained in:
Christopher C. Wells
Christopher Charbonneau Wells
parent
650d864c64
commit
04d191fe7c
55
docs/API.md
55
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 <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
|
||||
|
||||
|
|
|
|||
|
|
@ -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`
|
||||
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
@ -137,9 +136,10 @@ user name 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
|
||||
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
[Back to Table of Contents](/docs/TOC.md)
|
||||
|
||||
The default username and password for Baby Buddy is `admin`/`admin`. For any
|
||||
deployment, **log in and change the default admin password immediately**.
|
||||
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
|
|||
|
||||
[](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
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue