Updated Documentation (#763)

* Updated documentation * reverted background docker run
ohcnetwork · Jun 6, 2022 · 0a9ace2 · 0a9ace2
1 parent 39d2be3
commit 0a9ace2
Show file tree

Hide file tree

Showing 9 changed files with 309 additions and 5 deletions.
diff --git a/docs/Makefile b/docs/Makefile
@@ -3,6 +3,12 @@
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
+
+# To generate the documentation, run:
+# make html
+# 
+# This will build the documentation and put it in the _build/html
+
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .

diff --git a/docs/conf.py b/docs/conf.py
@@ -22,8 +22,8 @@
 # -- Project information -----------------------------------------------------
 
 project = "Care"
-copyright = """2020, 👪"""
-author = "👪"
+copyright = """2022, Care"""
+author = "coronasafe"
 
 
 # -- General configuration ---------------------------------------------------
@@ -47,7 +47,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "alabaster"
+html_theme = "sphinx_book_theme"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

diff --git a/docs/django-commands/configuration.rst b/docs/django-commands/configuration.rst
@@ -0,0 +1,24 @@
+Django Commands
+===============
+
+All Django commands must be executed by invoking :code:`python manage.py`, so for example, if the command is :code:`do_something` then the correct way to call the command is :code:`python manage.py do_something`. Make sure that the command is run in the root directory of the project and any virtual environment present must be activated before running the command.
+
++-----------------+---------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+|     command     |                           Arguments                           |                                                                                                                                                           Description                                                                                                                                                            |
++=================+===============================================================+==================================================================================================================================================================================================================================================================================================================================+
+| createsuperuser | None                                                          | This command is used to create a superuser in the care application, Superusers are able to log in through the Django Admin panel and Access Scopes do not apply to them. Please take caution when creating them, apply strict password policies for accounts created as superusers. ideally, there should only be one superuser. |
+|                 |                                                               |                                                                                                                                                                                                                                                                                                                                  |
+|                 |                                                               | Example Invocation: :code:`python manage.py createsuperuser`                                                                                                                                                                                                                                                                     |
++-----------------+---------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| load_data       | state_name                                                    | This command is used to load all the DIstrict/Lsg/Ward Level data for a given state, The data that is imported is scraped from various sources, The admin can change this data at any point through the admin panel, If the state name is given as "all" then all available data is imported into care.                          |
+|                 |                                                               |                                                                                                                                                                                                                                                                                                                                  |
+|                 |                                                               | Example Invocation: :code:`python manage.py load_data kerala`                                                                                                                                                                                                                                                                    |
++-----------------+---------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| seed_data       | None                                                          | This command loads all static data that the application needs to run, this includes inventory seed data for Oxygen, Medical Tests data, etc. All this data can be changed by the superuser from the admin panel.                                                                                                                 |
+|                 |                                                               |                                                                                                                                                                                                                                                                                                                                  |
+|                 |                                                               | Example Invocation: :code:`python manage.py seed_data`                                                                                                                                                                                                                                                                           |
++-----------------+---------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| summarize       | None                                                          | The summary jobs are run by Celery every 10 mins, but we can force Django to summarize the current data and update the summary table with this command                                                                                                                                                                           |
+|                 |                                                               |                                                                                                                                                                                                                                                                                                                                  |
+|                 |                                                               | Example Invocation: :code:`python manage.py summarize`                                                                                                                                                                                                                                                                           |
++-----------------+---------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
diff --git a/docs/github-repo/configuration.rst b/docs/github-repo/configuration.rst
@@ -0,0 +1,16 @@
+GitHub Repository
+=================
+
+The Github Repo available here_ contains the source code for the care project, Apart from the secrets configured at runtime, the exact copy is deployed in production.  
+
+The :code:`master` branch auto deploys to the Development instance and is regarded as the Beta version of the application.  
+
+The :code:`production` branch auto deploys to Production instance and is regarded as the Stable version of the application.  
+
+All Stable Releases are tagged in Github.  
+
+All PR's and issues are monitored by the code reviewers team and merged after a security review.  
+
+Any other forks for deployments **MUST** follow the same Github structure so as to remain in sync and to keep getting updates.  
+
+.. _here: https://github.com/coronasafe/care
diff --git a/docs/index.rst b/docs/index.rst
@@ -7,10 +7,14 @@ Welcome to Care's documentation!
 ======================================================================
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 4
    :caption: Contents:
 
+   local-setup/configuration
    pycharm/configuration
+   working-components/configuration
+   django-commands/configuration
+   github-repo/configuration
 
 
 

diff --git a/docs/local-setup/configuration.rst b/docs/local-setup/configuration.rst
@@ -0,0 +1,213 @@
+Setting up development environment
+===================================
+
+There are two ways to run the development server:
+
+    1. `Using Docker Compose`_ (most recommended)
+    2. `Setup it manually <#manual-setup>`__ (if you don't have Docker Compose)
+
+
+Using Docker Compose
+---------------------
+
+    This setup will run 5 Docker containers:   
+
+    - PostGIS
+    - care (main repo)
+    - redis (in-memory cache)
+    - celery (task queue)
+    - localstack (to mimic AWS services locally)
+
+This is the most recommended way of setting up care locally, 
+as it installs appropriate dependencies in containers so there 
+is no chance of conflicting dependencies. If you are running this 
+first time, it might take a while depending upon your internet speed and machine specs.
+
+- Steps to run the development server:
+
+    1. Run the following command to start the development environment:  
+        .. code-block:: bash
+
+            $ make up
+
+    2. Open a browser and go to `http://localhost:9000`
+
+
+- To stop the development environment:  
+    .. code-block:: bash
+
+        $ make down  
+
+- To run tests:
+    .. code-block:: bash
+
+        $ make test
+
+
+Manual setup
+------------
+
+
+Setting up postgres for the first time
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+After installation of Postgresql
+
+Run::
+
+    sudo psql -U postgres
+
+If you see error::
+
+    FATAL: Peer authentication failed for user "postgres"FATAL: Peer authentication failed for user "postgres"
+
+Do the following steps to set up password authentication.
+
+::
+
+    sudo -u postgres psql
+
+In the `postgres#` shell type:: 
+
+\password postgres
+
+to change the password
+
+Exit psql::
+
+    \q
+
+Edit `/etc/postgresql/<postgres-version>/main/pg_hba.conf` and change:
+
+::
+
+
+ local    all        postgres                               peer
+
+To::
+
+ local    all        postgres                               md5
+
+Restart postgresql::
+
+ sudo service postgresql restart
+
+
+Login to the postgres shell and run:
+
+::
+
+ CREATE DATABASE care;
+ GRANT ALL PRIVILEGES ON DATABASE care TO postgres;
+ \q
+
+You may replace `care` with the database name of your preference
+
+You also might have to install PostGIS scripts.
+
+* Linux users can install PostGIS scripts by running ::
+
+    $ sudo apt install postgresql-<version>-postgis-scripts
+
+* Windows users can install
+    - PostGIS through Application Stack Builder which is installed along PostgreSQL using standard PostgreSQL installer.
+    - OSGeo4W from this site_. 
+
+Then follow the steps listed here_.
+
+Setting up Pre-Commit
+^^^^^^^^^^^^^^^^^^^^^
+Git hooks is a feature which helps to fix small issues in your code before you commit the code.
+Pre-Commit is a package manager and tool for running and organising your git hooks. More here at pre_commit_site_.
+
+* Install pre-commit
+    pre-commit is installed while you run ::
+
+     pip install -r requirements/local.txt
+
+* Setup
+    this installs all the git-hooks ::
+
+    $ pre-commit install
+
+* Running pre-commits
+    The git hooks run every time you commit code to the repo.
+    If you want to run it before committing, use the following command ::
+
+    $ pre-commit run --all-files
+
+* FAQs and Issues with pre-commit
+    - Reach out on the #coronasafe_django channel in slack to resolve the issues.
+
+.. _here: https://cookiecutter-django.readthedocs.io/en/latest/developing-locally.html
+.. _pre_commit_site: https://pre-commit.com/
+.. _site: https://trac.osgeo.org/osgeo4w/
+
+Basic Commands
+^^^^^^^^^^^^^^
+
+Setting Up Your Users
+~~~~~~~~~~~~~~~~~~~~~
+
+* To create an **superuser account**, run this command::
+
+    $ python manage.py createsuperuser
+
+If the command prompts for username only and after entering if it goes to error
+do make sure that you have done the following 
+
+Note: Make sure that you have created a database named `care` (replace thisw with your database name)  with privileges set for the user `postgres`
+
+In the virtualenv shell type the following commands also::
+
+ export DATABASE_URL=postgres://postgres:<password>@127.0.0.1:5432/care
+
+ export TEST_POSTGIS_URL="postgis://postgres:<password>@127.0.0.1:5432/care"
+
+You may replace **care** with the database you have created before.
+
+After doing this you can type the following command::
+
+    $ python manage.py migrate
+
+and after you make sure everything is ok
+
+run this command again::
+
+$ python manage.py createsuperuser
+
+This will now prompt for the following details - Ignore any warnings.
+
+- username: give the username here
+- usertype: Give the value `10` [5 for doctor, 10 for hospital staff/hospital administrator, 15 for patient, 20 for volunteer]
+- gender: 1 for male, 2 for female, 3 for other
+- email: give e-mail id
+- phonenumber: give your ten digit phone number here
+- password: Give the password here
+
+To copy static files (css, js, images) into the care/care/media directory so that the website loads with images and CSS styles, you may use the command:
+
+::
+
+$ python manage.py collectstatic
+
+
+Type checks
+~~~~~~~~~~~
+
+Running type checks with mypy:
+
+::
+
+  $ mypy care
+
+Run Tests
+~~~~~~~~~
+::
+
+   $ python manage.py test --settings=config.settings.test -n
+
+If you get an :code:`ImproperlyConfigured` error regarding the Spatialite library extension, install it with the command:
+
+::
+
+  $ sudo apt install libsqlite3-mod-spatialite
diff --git a/docs/pycharm/configuration.rst b/docs/pycharm/configuration.rst
@@ -1,4 +1,4 @@
-Docker Remote Debugging
+Debugging with Pycharm
 =======================
 
 To connect to python remote interpreter inside docker, you have to make sure first, that Pycharm is aware of your docker.

diff --git a/docs/working-components/configuration.rst b/docs/working-components/configuration.rst
@@ -0,0 +1,40 @@
+Working Components
+==================
+
+This page explains the various components that make up the backend
+
+Backend (Django)
+----------------
+The Backend is a Django application server with gunicorn, it uses the default gunicorn workers and processes count, It can only serve ( 2 * No of cores ) requests at a time per deployed instance, Since the application involves very little CPU, ideally The Backend Deployments need very little CPU and memory allocation. Increasing the number of gunicorn instances with the help of a load balancer can scale the application up.
+
+Task Scheduler (celery beat)
+----------------------------
+This is a scheduler that schedules jobs at certain intervals similar to at Cron Job, The task scheduler is responsible for summarizing data at periodic intervals, the scheduler only schedules the job, it does not execute the actual job, because of this it is crucial that there is always only one instance of the scheduler running at any scale.
+
+Task Worker (celery worker)
+---------------------------
+The celery worker is used to asynchronously execute code, The summary jobs are an example of a task that should be executed asynchronously. This project also creates notifications for events, produces discharge summaries which are all run as background tasks with celery. Celery requires a scheduler to schedule its tasks, by default it uses Redis to Schedule jobs and to store the results, this can be changed to use RabbitMq Instead. Using the database for this purpose is highly discouraged.
+
+Database (PostgreSQL)
+---------------------
+Care uses a Postgresql database with the PostGIS plugin enabled, PostGIS is used in different contexts to store location information, it was used so that in a later context the application could intelligently suggest nearby locations to shift patients or do geo queries really quickly. 
+
+Cache (Redis)
+-------------
+Redis is used in a lot on API routes to cache data at the Request Layer, it is also used in various contexts to store intermediate query results, all permissions structures are cached in redis to avoid multiple queries to be executed on each API request, it is also intelligent enough to remove the caches when the permission model it describes changes.
+
+Bucket (S3)
+-----------
+Care is built to use AWS S3 as the primary object storage but it can work with any provider that supports the S3 API, it primarily uses three buckets, one public bucket to store static data like CSS/js/images used by the Backend and one bucket stores facility data (e.g., Facility Cover Image). There is a private bucket to store confidential patient information, ideally, this bucket should have encryption at rest and encryption in transit enabled. Access to the patient bucket is given on request only through signed requests, Uploads also happen in a similar manner, The Upload mechanism randomizes names and removes all relations with the patient so that even in a worst-case scenario the damages can be minimalized.
+
+SMS Gateway (AWS SNS)
+---------------------
+Care uses SNS as an SMS Gateway, the SMS feature is used for patient login via OTP and for Shifting updates.
+
+Email Gateway (AWS SES)
+-----------------------
+Care uses emails to send discharge summaries, reset password tokens, and crash reports.
+
+Reporting Infrastructure
+------------------------
+Since care by itself cannot produce a really detailed summary of its data, it is advised to use Metabase or Superset as external Business Intelligence tools and connect a Read Replica of the primary database with PII fields masked. This will allow much higher visibility into the actual data and make better data-driven decisions. If you are using Metabase you can ask the coronasafe team to share the existing dashboard structure for simplicity. Care Databases are designed to provide easy and configurable Reporting.
diff --git a/requirements/local.txt b/requirements/local.txt
@@ -2,6 +2,7 @@
 Werkzeug==1.0.0 # https://github.com/pallets/werkzeug
 ipdb==0.13.2  # https://github.com/gotcha/ipdb
 Sphinx==2.4.4  # https://github.com/sphinx-doc/sphinx
+sphinx-book-theme==0.3.2  # https://github.com/executablebooks/sphinx-book-theme
 psycopg2-binary==2.8.4  # https://github.com/psycopg/psycopg2
 # Code quality
 # ------------------------------------------------------------------------------