Skip to content
Permalink
Browse files

Add User Guide documentation (MLH#3)

* Rename project folders `starter` -> `project_name`

- Update Contributing Guide

* Update user guide

* Add more information

* Tweak links

* Rename project_name -> app

* Add email and fix minor things
  • Loading branch information...
nlaz committed Feb 5, 2019
1 parent 4ae36e5 commit b6462c6e61f809704d3f39ceb55e85733d31a35d
@@ -1,5 +1,5 @@
# Sample environment variables file.
FLASK_APP=starter/app.py
FLASK_APP=app/app.py
FLASK_ENV=development
DATABASE_URL="sqlite:////tmp/dev.db"
SECRET_KEY="octocat"
@@ -1,6 +1,6 @@
include starter/schema.sql
graft starter/static
graft starter/templates
graft starter/models
graft starter/controllers
include app/schema.sql
graft app/static
graft app/templates
graft app/models
graft app/views
global-exclude *.pyc
@@ -1 +1 @@
web: gunicorn --bind 0.0.0.0:${PORT} starter.app:create_app\(\)
web: gunicorn --bind 0.0.0.0:${PORT} app.app:create_app\(\)
@@ -21,8 +21,8 @@ To get started, install Python and Postgres on your local computer, if you don't
**1. Clone this repository to your local computer.**

```
$ git clone https://github.com/MLH/github-hackathon-starter.git
$ cd github-hackathon-starter
$ git clone https://github.com/MLH/mlh-hackathon-flask-starter.git
$ cd mlh-hackathon-flask-starter
```

**2. Create and activate a [virtual environment](http://flask.pocoo.org/docs/1.0/installation/#virtual-environments).**
@@ -48,23 +48,23 @@ Development mode makes it easier to make changes to your application. It include
For Linux and Mac:

```
export FLASK_APP=starter
export FLASK_APP=app
export FLASK_ENV=development
flask run
```

For Windows Powershell, use `$env:` instead of `export`:

```
$env:FLASK_APP = 'starter'
$env:FLASK_APP = 'app'
$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.
Open 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.
@@ -76,7 +76,7 @@ Installs a Python package for your application. Used to add new functionality to
# 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 Blueprints](http://flask.pocoo.org/docs/1.0/blueprints/) - A Flask extension 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.
@@ -85,7 +85,7 @@ Installs a Python package for your application. Used to add new functionality to

# 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.
We enforce a Code of Conduct for all maintainers and contributors of this Guide. Read more in [CONDUCT.md](https://github.com/MLH/mlh-hackathon-flask-starter/blob/master/starter/docs/CONDUCT.md).

# License

File renamed without changes.
@@ -1,8 +1,8 @@
import os

from flask import Flask, render_template
from starter import settings, controllers, models
from starter.extensions import db, markdown
from app import settings, views, models
from app.extensions import db, markdown

project_dir = os.path.dirname(os.path.abspath(__file__))

@@ -27,9 +27,9 @@ def register_extensions(app):

def register_blueprints(app):
"""Register Flask blueprints."""
app.register_blueprint(controllers.public.blueprint)
app.register_blueprint(controllers.auth.blueprint)
app.register_blueprint(controllers.github.blueprint)
app.register_blueprint(views.public.blueprint)
app.register_blueprint(views.auth.blueprint)
app.register_blueprint(views.github.blueprint)
return None

def register_errorhandlers(app):
File renamed without changes.
File renamed without changes.
@@ -1,5 +1,5 @@
from starter.extensions import db
from starter.services.github import GitHub
from app.extensions import db
from app.services.github import GitHub

class User(db.Model):
__tablename__ = 'user'
@@ -13,6 +13,7 @@ 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)

File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.

Some generated files are not rendered by default. Learn more.

File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
@@ -3,7 +3,7 @@
{% block header %}
<div class='bg-dark text-light'>
<div class='container py-5 my-4'>
<h1 class='h3 mb-1'>Hackathon Starter Kit</h1>
<h1 class='h3 mb-1'>Hackathon Flask Starter Kit</h1>
<h2 class='h6 text-secondary'>Presented by GitHub & MLH</h2>
</div>
</div>
@@ -8,7 +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') }}" >
<link rel="stylesheet" href="{{ url_for('static', filename='vendor/markdown.min.css') }}" >
{% endblock %}
</head>
<body class='d-flex flex-column' style='min-height: 100vh;'>
@@ -16,10 +16,7 @@ <h1 class="h5 m-0">{Project Name}</h1>
</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>
<a href="{{ url_for('public.user_guide') }}">User Guide</a>
</span>
{% if g.user %}
<span class="nav-item p-2 m-1">
@@ -1,2 +1,2 @@
"""Controllers package"""
"""Views package"""
from . import auth, github, public
@@ -3,9 +3,9 @@
from flask import flash, redirect, render_template, request
from flask import Blueprint, session, url_for, g

from starter.models.user import User
from starter.settings import GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET
from starter.services.github import GitHub
from app.models.user import User
from app.settings import GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET
from app.services.github import GitHub

blueprint = Blueprint('auth', __name__, url_prefix='/auth')

@@ -1,8 +1,8 @@
from flask import redirect, render_template, request
from flask import Blueprint, flash, url_for, session

from starter.controllers.auth import login_required
from starter.services.github import GitHub
from app.views.auth import login_required
from app.services.github import GitHub

blueprint = Blueprint('github', __name__, url_prefix='/github')

@@ -1,6 +1,6 @@
from flask import Blueprint, render_template

from starter.extensions import markdown
from app.extensions import markdown

blueprint = Blueprint('public', __name__)

@@ -13,14 +13,14 @@ def index():

@blueprint.route('/user-guide')
def user_guide():
with open('starter/docs/USER_GUIDE.md', 'r') as input_file:
with open('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():
with open('starter/docs/GETTING_STARTED.md', 'r') as input_file:
@blueprint.route('/contributing')
def contributing():
with open('docs/CONTRIBUTING.md', 'r') as input_file:
text = input_file.read()
content = markdown.render(text)
return render_template('home/index.html', body=content)
@@ -0,0 +1,18 @@
# Code of Conduct

All contributors and maintainers of this guide, in the interest of fostering an open and welcoming community, are required to adhere to the [Major League Hacking Code of Conduct][mlh-coc].

### Addendum for Open Source Projects

Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to the [Major League Hacking Code of Conduct][mlh-coc], or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.

By adopting this Code of Conduct, project maintainers commit themselves to fairly and consistently applying these principles to every aspect of managing this project. Project maintainers who do not follow or enforce the [Code of Conduct][mlh-coc] may be permanently removed from the project team.

The [Major League Hacking Code of Conduct][mlh-coc] applies both within project spaces and in public spaces when an individual is representing the project or its community.

### Credits

Inspired by [Jekyll's Code of Conduct][jekyll-coc].

[mlh-coc]: https://github.com/MLH/mlh-policies/blob/master/code-of-conduct.md
[jekyll-coc]: https://github.com/jekyll/jekyll/blob/master/CONDUCT.markdown
@@ -0,0 +1,23 @@
# Contributing

Want to contribute to making this project better for others? Thanks! There are plenty of ways you can help.

Before you do anything else, please read the [README](https://github.com/MLH/mlh-hackathon-flask-starter) of this project first. It will highlight the key features and help you understand the project structure. The rest of this document will help make the contribution process easier.

### Where do I go from here?

If you noticed a bug or have a question, [open an issue](https://github.com/MLH/mlh-hackathon-flask-starter/issues). We'll try to answer it as fast as possible.

### Can you add this technology?

This project includes many different frameworks and technologies to help hackers get started building an app quickly. If you would like to recommend or suggest a particular framework, [open an issue](https://github.com/MLH/mlh-hackathon-flask-starter/issues). Suggestions are always welcome.

### Can I submit a Pull Request?

Pull requests to fix issues, add improvements, or other features are always appreciated! Good pull requests should be focused and avoid unrelated commits. Including helpful descriptions, titles, and screenshots will make it easier to review.

Before working on changes, check if there is already an issue created in the [issue tracker](https://github.com/MLH/mlh-hackathon-flask-starter/issues). This will help reduce confusion on what can and should be changed. You can also reach out to [our email](mailto:hi@mlh.io) if you want to work on an issue.

### What can I contribute to?

Even the smallest change is appreciated. It can be a typo error or fixing a bug. Nothing is too small to be helpful. You can also reach out to [our email](mailto:hi@mlh.io) if you want to work on an issue.

0 comments on commit b6462c6

Please sign in to comment.
You can’t perform that action at this time.