Use named code blocks throughout documentation

This commit is contained in:
Christopher C. Wells 2022-05-28 13:47:48 -07:00
parent f95edd8957
commit e4345b03e7
5 changed files with 234 additions and 158 deletions

View File

@ -61,13 +61,18 @@ The `limit` and `offset` request parameters can be used to limit
and offset the results set respectively. For example, the following request
will return five diaper changes starting from the 10th diaper change entry:
```shell
curl -X GET 'https://[...]/api/changes/?limit=5&offset=10' -H 'Authorization: Token [...]'
```
```json
{
"count": <int>,
"count": 20,
"next": "https://[...]/api/changes/?limit=5&offset=15",
"previous": "https://[...]/api/changes/?limit=5&offset=5",
"results": [...]
"results": []
}
```
Field-based filters for specific endpoints can be found the in the `filters`
field of the `OPTIONS` response for specific endpoints.
@ -75,7 +80,11 @@ field of the `OPTIONS` response for specific endpoints.
Single entries can also be retrieved by adding the ID (or in the case of a
Child entry, the slug) of a particular entry:
```shell
curl -X GET https://[...]/api/children/gregory-hill/ -H 'Authorization: Token [...]'
```
```json
{
"id":3,
"first_name":"Gregory",
@ -84,7 +93,13 @@ Child entry, the slug) of a particular entry:
"slug":"gregory-hill",
"picture":null
}
```
```shell
curl -X GET https://[...]/api/sleep/1/ -H 'Authorization: Token [...]'
```
```json
{
"id":480,
"child":3,
@ -93,17 +108,20 @@ Child entry, the slug) of a particular entry:
"duration":"04:09:00",
"nap":false
}
```
### Response
Returns JSON data in the response body in the following format:
```json
{
"count":<int>,
"next":<url>,
"previous":<url>,
"results":[{...}]
}
```
- `count`: Total number of records (*in the database*, not just the response).
- `next`: URL for the next set of results.
@ -126,6 +144,7 @@ Returns JSON data in the response body describing the endpoint, available
options for `POST` requests, and available filters for `GET` requests. The
following example describes the `/api/children` endpoint:
```json
{
"name": "Child List",
"renders": [
@ -154,6 +173,7 @@ following example describes the `/api/children` endpoint:
"slug"
]
}
```
## `POST` Method
@ -267,11 +287,13 @@ for the entry to be updated. The `Content-Type` header for `PATCH` request must
be set to `application/json`. For example, to update a Diaper Change entry with
ID 947 to indicate a "wet" diaper only:
```shell
curl -X PATCH \
-H 'Authorization: Token [...]' \
-H "Content-Type: application/json" \
-d '{"wet":1, "solid":0}' \
https://[...]/api/changes/947/
```
Regular sanity checks will be performed on relevant data. See the `OPTIONS`
response for a particular endpoint for details on required fields and data
@ -291,7 +313,9 @@ To delete an existing entry, send a `DELETE` request to the single entry
endpoint to be deleted. For example, to delete a Diaper Change entry with ID
947:
```shell
curl -X DELETE https://[...]/api/changes/947/ -H 'Authorization: Token [...]'
```
### Response

View File

@ -19,29 +19,41 @@ information and steps below to set up a local development environment for Baby B
1. Install required Python packages, including dev packages
```shell
pipenv install --three --dev
```
- If this fails, install `libpq-dev` (e.g. `sudo apt install libpq-dev`) and try again.
If this fails, install `libpq-dev` (e.g. `sudo apt install libpq-dev`) and try again.
1. Installed Node 14.x (if necessary)
```shell
nvm install 14
```
1. Activate Node 14.x
```shell
nvm use
```
1. Install Gulp CLI
```shell
npm install -g gulp-cli
```
1. Install required Node packages
```shell
npm install
```
1. Set, at least, the `DJANGO_SETTINGS_MODULE` environment variable
```shell
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](../setup/configuration.md) for other
@ -49,15 +61,21 @@ information and steps below to set up a local development environment for Baby B
1. Migrate the database
```shell
gulp migrate
```
1. Create cache table
```shell
gulp createcachetable
```
1. Build assets and run the server
```shell
gulp
```
This command will also watch for file system changes to rebuild assets and
restart the server as needed.

View File

@ -22,7 +22,9 @@ must also be updated to reflect the change. This is necessary because hosting en
do not provide adequate support for pipenv. To update the `requirements.txt` file to be in
sync with the `Pipenv` file run:
pipenv lock -r > requirements.txt
```shell
pipenv requirements > requirements.txt
```
Add and commit the changes to the `requirements.txt` file.

View File

@ -34,7 +34,7 @@ See [HTTPS/SSL configuration](ssl.md) for information on how to secure Baby Budd
For doing administrative work within the LSIO container, setting an environment variable may be necessary.
For example:
```
```shell
docker exec -it babybuddy /bin/bash
export DJANGO_SETTINGS_MODULE="babybuddy.settings.base"
python3 /app/babybuddy/manage.py clearsessions
@ -47,18 +47,22 @@ python3 /app/babybuddy/manage.py clearsessions
For manual deployments to Heroku without using the "deploy" button, make sure to
create the following settings before pushing:
```shell
heroku config:set DISABLE_COLLECTSTATIC=1
heroku config:set DJANGO_SETTINGS_MODULE=babybuddy.settings.heroku
heroku config:set SECRET_KEY=<CHANGE TO SOMETHING RANDOM>
heroku config:set TIME_ZONE=<DESIRED DEFAULT TIMEZONE>
```
See [Configuration](configuration.md) for other settings that can be controlled
by `heroku config:set`.
After an initial push, execute the following commands:
```shell
heroku run python manage.py migrate
heroku run python manage.py createcachetable
```
## Manual
@ -80,53 +84,73 @@ and any number of children).
1. Install system packages
```shell
sudo apt-get install python3 python3-pip nginx uwsgi uwsgi-plugin-python3 git libopenjp2-7-dev libpq-dev
```
2. Default python3 to python for this session
```shell
alias python=python3
```
3. Install pipenv
```shell
sudo -H pip3 install pipenv
```
4. Set up directories and files
```shell
sudo mkdir /var/www/babybuddy
sudo chown $USER:$(id -gn $USER) /var/www/babybuddy
mkdir -p /var/www/babybuddy/data/media
git clone https://github.com/babybuddy/babybuddy.git /var/www/babybuddy/public
```
5. Move in to the application folder
```shell
cd /var/www/babybuddy/public
```
6. Initiate and enter a Python environment with Pipenv locally.
```shell
export PIPENV_VENV_IN_PROJECT=1
pipenv install --three
pipenv shell
```
7. Create a production settings file and set the ``SECRET_KEY`` and ``ALLOWED_HOSTS`` values
```shell
cp babybuddy/settings/production.example.py babybuddy/settings/production.py
editor babybuddy/settings/production.py
```
8. Initiate the application
```shell
export DJANGO_SETTINGS_MODULE=babybuddy.settings.production
python manage.py migrate
python manage.py createcachetable
```
9. Set appropriate permissions on the database and data folder
```shell
sudo chown -R www-data:www-data /var/www/babybuddy/data
sudo chmod 640 /var/www/babybuddy/data/db.sqlite3
sudo chmod 750 /var/www/babybuddy/data
```
10. Create and configure the uwsgi app
```shell
sudo editor /etc/uwsgi/apps-available/babybuddy.ini
```
Example config:
@ -152,12 +176,16 @@ and any number of children).
11. Symlink config and restart uWSGI:
```shell
sudo ln -s /etc/uwsgi/apps-available/babybuddy.ini /etc/uwsgi/apps-enabled/babybuddy.ini
sudo service uwsgi restart
```
12. Create and configure the nginx server
```shell
sudo editor /etc/nginx/sites-available/babybuddy
```
Example config:
@ -189,8 +217,10 @@ and any number of children).
14. Symlink config and restart NGINX:
```shell
sudo ln -s /etc/nginx/sites-available/babybuddy /etc/nginx/sites-enabled/babybuddy
sudo service nginx restart
```
15. That's it (hopefully)!

View File

@ -29,7 +29,9 @@ protected requests to succeed.
Note: multiple origins can be added by separating origins with commas. E.g.:
```shell
CSRF_TRUSTED_ORIGINS=https://baby.example.com,https://baby.example.org
```
### [`SECURE_PROXY_SSL_HEADER`](../configuration#secure_proxy_ssl_header)