Rewrite of docs

.gitignore

@@ -1,15 +1,13 @@
-*venv*
-*vscode*
-*pyc
-*pycache*
-*vscode
-*vim*
-*swp
-*swo
-*swn
-*.lock*
-*.orig*
-*poetry*
+__pycache__/
+*venv/
+/.vscode/
+*.pyc
+*.vim
+*.swp
+*.swo
+*.swn
+*.lock
+*.orig
 secrets*
-*.db*
+*.db
 *.env

README.md

@@ -12,63 +12,107 @@ Features:
 * News collection(scraping, api) and serving
 * Pagination, Collapsible sidebar, Responsive navigation
 * Use proper structure with flask blueprinting
-* Support PostgreSQL and Sqlite database
 * Hosted Live at heroku @ kbd.herokuapp.com
 
-Todo:
-* Tick indcates progress.
+Todos:
+
 - [x] Integrate various international news apis(top, general, sports, tech...)
-- [ ] News search on keyword for custom category (like bitcoin, trump, etc)
-- [ ] Give user choice to customize news topic, sources, language etc
-- [ ] Remove compulsory login and establish per person db record of preferences
+- [x] Rewrite manage.py and database management
+- [ ] Add logging
+- [ ] Add tests
+- [ ] Experiment with docker deploys
+- [ ] Extract the scraper to separate news API
 - [ ] Redesign the dashboard
+- [ ] Remove compulsory login and establish per person db record of preferences
+- [ ] Give user choice to customize news topic, sources, language etc
+- [ ] News search on keyword for custom category (like bitcoin, trump, etc)
 - [ ] Integrate social media login (facebook, github)
-- [ ] Use Docker
-- [x] Add logging
-- [x] Add tests
-- [ ] Rewrite manage.py and database management
 
-## Installation
 
-### Fast-Track test installation
-* First properly install python 3.6 or above in your system.
-* clone/download this repository and navigate to this repo through cmd
-* Run
+## Installation and Usage
 
-      python setupenv.py sqlite
+- Install [python 3.6 or above](https://python.org/downloads)
+- Clone/download this repository and navigate to this repo through cmd
 
-             OR
+```sh
+$ git clone https://github.com/hemanta212/nepali-news-portal-kbd
+```
 
-      python setupenv.py postgres
+- Install either [poetry](https://github.com/python-poetry/poetry) or follow [this guide](/docs/venv.md) for setting up virtual environment.
+- Installing dependencies using poetry
+```sh
+$ poetry install
+```
+- Installing dependencies using pip.
+```sh
+$ python -m pip install -r requirements.txt
+```
+
+### Setting up Database
+You can setup any database supported [here](https://docs.sqlalchemy.org/en/13/core/engines.html#supported-databases). This doc covers setting up sqlite and postgres db.
+
+##### Setting up SQLite
+Populate the following as your environment variables
+
+```
+SECRET_KEY="<your secret key here (random string sequence)"
+SQLALCHEMY_DATABASE_URI="sqlite:///site.db"
+MAIL_USERNAME="your email",  //optional
+MAIL_PASSWORD="your password" //optional
+```
 
-      According to your needs
+###### NOTE
+* optional: only required for 'forgot/reset password' functionality to work
+If you use gmail and 2 factor-auth, you can use [app passwords](https://support.google.com/accounts/answer/185833) without compromising to low security.
 
-* Done !!!
+* To enable the international news section get an api key from [News API](https://newsapi.org/register) and set environment variable 'NEWS_API_KEY' to that value.
 
-## Note
-* If you're facing problems while installing packages in windows try removing the package gunicorn from requirements.txt.
+Alternatively, you can populate these detail in 'template_secrets.json' file and rename it to secrets.json.
 
-* Also to enable the international news section get an api key from [News API](https://newsapi.org/register) and set environment variable 'NEWS_API_KEY' to that value.
+##### Setting up the Postgres Databse
+The details of installing, configuring a postgres database is [detailed here.](/docs/postgres_setup.md)
 
-- Once setup completed, You can just activate virtual environment inside venv folder and run ONE of these according to your setup:
+Once you have setup the db and have its URI, just set it as the value of 'SQLALCHEMY_DATABASE_URI' in above SQLite section and continue following this doc.
 
+#### Initializing the database
+To upgrade the newly created database to the project's structure use 
 ```
-# For sqlite
-    python manage.py sqlite
-    python run.py sqlite-prod # Production environment
-    python run.py sqlite-debug # Debug environment
-
-# For other databases like postgres, sql
-    python run.py db-prod
-    python run.py db-debug
+$ python manage.py upgrade
 ```
 
-## Complete installation
-For complete installation details visit [installation docs](docs/manual_install.md) which includes:
+Similarly, if you need to start fresh, delete the migrations folder and now run,
+```
+$ python manage.py db init # create the migrations folder
+$ python manage.py db migrate # create sql commands for the required db construction
+$ python manage.py db upgrade # executes those changes in the db
+```
 
-* Step by step setup process.
-* Running with diffrent databases and with debug and production configs
+#### KNOWN ISSUE
+- While Using SQLite relative URI:
+Due to the mismatch in the folder level of manage.py and flask application only the sqlite:///site.db relative URI is supported other relative URIs wont work so consider using absolute sqlite URIs.
 
-## Accessing all news
-After successfully running the app, go to localhost:5000/signup and create an account with this email '[email protected]' and login. You should see news from all the sources.
+#### Running the Server
+```
+    python run.py // production environment (default)
+    python run.py debug // for debug environment
+```
+
+NOTE: Running in Prod mode is unsupported with secrets.json file and will fallback to Debug.
+
+### Running from gunicorn (Not supported on windows) <a id='gunicorn'></a>
+Gunicorn is a production WSGI server that is essential for running flask project in production environments like with Procfile in [Heroku](https://heroku.com).
 
+After installing, you just provide the application instance of project to gunicorn.
+
+eg.
+```
+gunicorn run:app  // prod env
+
+gunicorn run:app debug
+```
+
+#### *NOTE*:
+Gunicorn is not supported in windows operating system. However, you can run it using [WSL](https://google.com/search?query=windows%20subsytem%20for%20linux).
+
+## Accessing all news
+After successfully running the app, go to localhost:5000/signup and sign up with an account with this admin provisioned email '[email protected]' (yes this exact email only) and login. You should see news from all the sources.