Adds support for markdown files (#2)

* Adding support for markdown files

* Initialize project with basic instructions

* Add navigation to documentation

* Use markdown library for rendering

* Update README.md with new instructions

* Remove unused /views folder

* Edit documentation

LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2019 Major League Hacking, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE

README.md

@@ -0,0 +1,92 @@
+# Introduction
+
+This is a hackathon boilerplate for new Flask web applications created by [Major League Hacking](https://github.com/MLH). It is for hackers looking to get started quickly on a new hackathon project using the Flask microframework.
+
+* [Installation Guide](#installation-guide) - How to get started with a new Flask app
+* [User Guide](/user-guide) - How to develop apps created with this starter project
+* [Contributing Guide](/contributing) - How to contribute to the project
+
+# <a name='installation-guide'>Installation Guide</a>
+
+This project requires the following tools:
+
+* Python ([3.4](https://www.python.org/downloads/)) - The programming language used by Flask.
+* PostgreSQL ([9.4](https://wiki.postgresql.org/wiki/What's_new_in_PostgreSQL_9.4)) - A relational database system.
+* Virtualenv - A tool for creating isolated Python environments.
+
+To get started, install Python and Postgres on your local computer, if you don't have them already. A simple way for Mac OS X users to install Postgres is using [Postgres.app](https://postgresapp.com/). You can optionally use another database system instead of Postgres, like [SQLite](http://flask.pocoo.org/docs/1.0/patterns/sqlite3/).
+
+## Installation
+
+**1. Clone this repository to your local computer.**
+
+```
+$ git clone https://github.com/MLH/github-hackathon-starter.git
+$ cd github-hackathon-starter
+```
+
+**2. Create and activate a [virtual environment](http://flask.pocoo.org/docs/1.0/installation/#virtual-environments).**
+
+```
+$ python3 -m venv venv
+$ . venv/bin/activate
+```
+
+**3. Install Flask dependencies using `pip`.**
+
+```
+$ pip install -r requirements.txt
+```
+
+
+## Starting the app
+
+You can run your application from your terminal using the `flask` command. To run the app locally, you need to tell Flask where to find your application, then run it in development mode.
+
+Development mode makes it easier to make changes to your application. It includes an interactive debugger and will restart the server whenever you make changes to the code.
+
+For Linux and Mac:
+
+```
+export FLASK_APP=starter
+export FLASK_ENV=development
+flask run
+```
+
+For Windows Powershell, use `$env:` instead of `export`:
+
+```
+$env:FLASK_APP = 'starter'
+$env:FLASK_ENV = 'development'
+flask run
+```
+
+### `flask run`
+
+Runs the app in development mode. Requires the `FLASK_APP` and `FLASK_ENV` variables to be set.
+Opens http://localhost:5000 to view it in your browser.
+
+The app will automatically reload if you make changes to the code.
+You will see the build errors and warnings in the console.
+
+### `pip install`
+
+Installs a Python package for your application. Used to add new functionality to the project.
+
+# What's Included?
+
+* [Flask](http://flask.pocoo.org/) - A microframework for Python web applications
+* [Flask Blueprints](http://flask.pocoo.org/docs/1.0/blueprints/) - A Flask concept for making modular applications
+* [Flask-SQLAlchemy](http://flask-sqlalchemy.pocoo.org/2.3/) - A Flask extension that adds ORM support for your data models.
+* [Flask-Misaka](https://flask-misaka.readthedocs.io) - A Flask extension that supports rendering markdown into HTML.
+* [Werkzeug](http://werkzeug.pocoo.org/) - A Flask framework that implements WSGI for handling server requests.
+* [Bootstrap 4](https://getbootstrap.com/) - An open source design system for HTML, CSS, and JS.
+* [Jinja2](http://jinja.pocoo.org/docs/2.10/) - A templating language for Python, used by Flask.
+
+# Code of Conduct
+
+The [MLH Code of Conduct](https://static.mlh.io/docs/mlh-code-of-conduct.pdf) applies to project participants and we expect contributors and maintainers to adhere to this standard.
+
+# License
+
+The Hackathon Starter Kit is open source software [licensed as MIT](https://github.com/nlaz/github-hackathon-starter/blob/master/LICENSE.md).

requirements.txt

@@ -1,16 +1,24 @@
+alembic==1.0.6
 certifi==2018.11.29
+cffi==1.11.5
 chardet==3.0.4
 Click==7.0
 Flask==1.0.2
+Flask-Misaka==1.0.0
 Flask-SQLAlchemy==2.3.2
 gunicorn==19.9.0
 idna==2.8
 itsdangerous==1.1.0
 Jinja2==2.10
+Mako==1.0.7
 MarkupSafe==1.1.0
+misaka==2.1.1
 psycopg2==2.7.3.2
+pycparser==2.19
 python-dotenv==0.10.1
+python-editor==1.0.3
 requests==2.21.0
+six==1.12.0
 SQLAlchemy==1.2.16
 urllib3==1.24.1
 Werkzeug==0.14.1

starter/app.py

@@ -2,7 +2,7 @@
 
 from flask import Flask, render_template
 from starter import settings, controllers, models
-from starter.database import db
+from starter.extensions import db, markdown
 
 project_dir = os.path.dirname(os.path.abspath(__file__))
 
@@ -19,6 +19,7 @@ def create_app(config_object=settings):
 def register_extensions(app):
     """Register Flask extensions."""
     db.init_app(app)
+    markdown.init_app(app)
 
     with app.app_context():
         db.create_all()

starter/controllers/auth.py

@@ -2,9 +2,7 @@
 
 from flask import flash, redirect, render_template, request
 from flask import Blueprint, session, url_for, g
-from werkzeug.security import check_password_hash, generate_password_hash
 
-from starter.database import db
 from starter.models.user import User
 from starter.settings import GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET
 from starter.services.github import GitHub

starter/controllers/github.py

@@ -2,7 +2,6 @@
 from flask import Blueprint, flash, url_for, session
 
 from starter.controllers.auth import login_required
-from starter.database import db
 from starter.services.github import GitHub
 
 blueprint = Blueprint('github', __name__, url_prefix='/github')

starter/controllers/public.py

@@ -1,21 +1,26 @@
-from flask import (
-    Blueprint, flash, g, redirect, render_template, request, url_for, session
-)
+from flask import Blueprint, render_template
 
-from starter.controllers.auth import login_required
+from starter.extensions import markdown
 
 blueprint = Blueprint('public', __name__)
 
 @blueprint.route('/')
 def index():
-    return render_template('home/index.html')
+    with open('README.md', 'r') as input_file:
+        text = input_file.read()
+        content = markdown.render(text)
+        return render_template('home/index.html', body=content)
 
-@blueprint.route('/about')
-def about():
-    # TODO: Create this template
-    return render_template('home/index.html')
+@blueprint.route('/user-guide')
+def user_guide():
+    with open('starter/docs/USER_GUIDE.md', 'r') as input_file:
+        text = input_file.read()
+        content = markdown.render(text)
+        return render_template('home/index.html', body=content)
 
 @blueprint.route('/getting-started')
 def getting_started():
-    # TODO: Create this template
-    return render_template('home/index.html')
+    with open('starter/docs/GETTING_STARTED.md', 'r') as input_file:
+        text = input_file.read()
+        content = markdown.render(text)
+        return render_template('home/index.html', body=content)

starter/docs/CONTRIBUTING.md

@@ -0,0 +1,6 @@
+# Contributing
+
+* Core Ideas
+* Filing an issue
+* Submitting a Pull Request
+* Setting up a Local Copy

starter/docs/GETTING_STARTED.md

@@ -0,0 +1,6 @@
+# Getting Started
+
+* Environment requirements
+* Project structure
+* Installation commands
+* Simple command definitions

starter/docs/USER_GUIDE.md

@@ -0,0 +1,38 @@
+# User Guide
+
+This is the User Guide for the Hackathon Starter Kit. Here you will find additional documentation and guides on how to use the project.
+
+## How It Works
+
+## Starting the app
+
+## Project Structure (Overview)
+
+## Flask Development
+* Application Setup
+* Templates
+* Blueprints and Views
+* Static Files
+* Using the Database
+* Flash Messages
+
+## Guides
+
+### GitHub
+* Setting up OAuth apps, authentication, etc.
+* Fetching and using GitHub's API
+
+### PostgresSQL
+* Setting up database
+* Inserting and running commands
+
+## Deployment
+* Deploy to Heroku
+* Deploy to Google Cloud Platform
+* Deploy using Docker
+
+## Support
+* Troubleshooting
+* Support channel for hackathons
+* Filing issues
+* Contact email

starter/extensions.py

@@ -0,0 +1,6 @@
+"""Database module"""
+from flask_sqlalchemy import SQLAlchemy
+from flask_misaka import Misaka
+
+db = SQLAlchemy()
+markdown = Misaka(fenced_code=True, tables=True, autolink=True, strikethrough=True, no_intra_emphasis=True)

starter/models/user.py

@@ -1,4 +1,4 @@
-from starter.database import db
+from starter.extensions import db
 from starter.services.github import GitHub
 
 class User(db.Model):
@@ -13,6 +13,18 @@ def __init__(self, username, avatar_url, github_id):
         self.username = username
         self.avatar_url = avatar_url
         self.github_id = github_id
+    def find_or_create_from_token(access_token):
+        data = GitHub.get_user_from_token(access_token)
+
+        """Find existing user or create new User instance"""
+        instance = User.query.filter_by(username=data['login']).first()
+
+        if not instance:
+            instance = User(data['login'], data['avatar_url'], data['id'])
+            db.session.add(instance)
+            db.session.commit()
+
+        return instance
 
     def find_or_create_from_token(access_token):
         data = GitHub.get_user_from_token(access_token)

starter/templates/home/index.html

@@ -11,19 +11,8 @@ <h2 class='h6 text-secondary'>Presented by GitHub & MLH</h2>
 
 {% block content %}
   <div class='container my-5'>
-    <h3>Getting Started</h3>
-    <hr/>
-    <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas scelerisque leo eu imperdiet tincidunt. Nullam cursus massa lacus, eget ornare urna lobortis id. Vivamus enim augue, lacinia vel tellus eu, commodo varius lectus. Maecenas quam orci, vestibulum et hendrerit vitae, accumsan quis ligula.</p>
-    <p>Mauris varius dui ut ipsum pretium fringilla. Sed ac magna nec ante vestibulum feugiat. Vivamus vel mauris metus. Aliquam erat volutpat. Aenean commodo velit sed vestibulum sagittis. Integer viverra lobortis facilisis. Donec gravida iaculis sagittis. In hac habitasse platea dictumst. Aenean tristique gravida velit.</p>
-    <br/>
-    <h3>Installation</h3>
-    <hr/>
-    <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas scelerisque leo eu imperdiet tincidunt. Nullam cursus massa lacus, eget ornare urna lobortis id. Vivamus enim augue, lacinia vel tellus eu, commodo varius lectus. Maecenas quam orci, vestibulum et hendrerit vitae, accumsan quis ligula.</p>
-    <p>Mauris varius dui ut ipsum pretium fringilla. Sed ac magna nec ante vestibulum feugiat.</p>
-    <br/>
-    <h3>Contributing</h3>
-    <hr/>
-    <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas scelerisque leo eu imperdiet tincidunt.</p>
-    <p>Mauris varius dui ut ipsum pretium fringilla. Sed ac magna nec ante vestibulum feugiat.</p>
+    {% if body %}
+      <div class='content markdown'>{{ body|safe }}</div>
+    {% endif %}
   </div>
 {% endblock %}

starter/templates/layout.html

@@ -8,6 +8,7 @@
     <link rel="shortcut icon" href="{{ url_for('static', filename='favicon.ico') }}">
     <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.2.1/css/bootstrap.min.css" crossorigin="anonymous">
     <link rel="stylesheet" href="{{ url_for('static', filename='style.css') }}" >
+    <link rel="stylesheet" href="{{ url_for('static', filename='markdown.min.css') }}" >
     {% endblock %}
   </head>
   <body class='d-flex flex-column' style='min-height: 100vh;'>

starter/templates/nav.html

@@ -8,12 +8,20 @@ <h1 class="h5 m-0">{Project Name}</h1>
         GitHub API
       </a>
     </div>
-    <div class="d-flex">
+    <div class="d-flex align-items-center">
       {% if g.user %}
-        <span class="nav-item p-2 m-1 text-secondary">
-          <img src="{{ g.user['avatar_url'] }}" class='rounded mr-1' style='width:25px; height:25px;'/>
+        <span class="nav-item p-2 text-secondary d-flex align-items-center">
+          <img src="{{ g.user['avatar_url'] }}" class='rounded mr-2' style='width:24px; height:24px;'/>
           {{ g.user['username'] }}
         </span>
+      {% endif %}
+      <span class="nav-item p-2 m-1">
+        <a href="{{ url_for('public.user_guide') }}">Docs</a>
+      </span>
+      <span class="nav-item p-2 m-1">
+        <a href="{{ url_for('public.getting_started') }}">Getting Started</a>
+      </span>
+      {% if g.user %}
         <span class="nav-item p-2 m-1">
           <a href="{{ url_for('auth.logout') }}">Log out</a>
         </span>