citusdata/sphinx-heroku-buildpack

Name: sphinx-heroku-buildpack

Owner: Citus Data

Description: A Heroku buildpack to generate launch a sphinx documentation based on the same repo.

Forked from: Thermondo/heroku-buildpack-sphinx

Created: 2016-05-03 20:18:48.0

Updated: 2016-05-03 20:18:49.0

Pushed: 2016-05-03 21:42:09.0

Homepage:

Size: 27

Language: Shell

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

Sphinx Heroku Buildpack

A Heroku buildpack to generate launch a sphinx documentation based on the same repository.

For more information read about Heroku Buildpacks

Setting up Sphinx Heroku Buildpack

Setting up documentation with graphviz.

• Create heroku app to host sphinx documentation.

ku create myapp-docs

The order of buildpacks on your application is important!

• First setup heroku-buildpack-graphviz

  ku buildpacks:set https://github.com/weibeld/heroku-buildpack-graphviz.git
  

• Setup sphinx-heroku-buildpack

  ku buildpacks:set https://github.com/Thermondo/sphinx-heroku-buildpack.git
  

• Finally setup heroku's official python buildpack

  ku buildpacks:set heroku/python
  

When listing the buildpacks on our application, we get this result:

ku buildpacks --app myapp-docs
myapp-docs Buildpack URLs
ttps://github.com/weibeld/heroku-buildpack-graphviz.git     # If you need graphiz
ttps://github.com/Thermondo/sphinx-heroku-buildpack.git
eroku/python

Why?

With Heroku auto deploy configured it reduces deployment time by serving sphinx documentation on a separate Heroku app but still using the same source code for your application. And allows to host private documentation.

Use Case

When using Heroku, Github and Travis:

push {remotename} master

Your application myapp will be tested by travis and deployed regularly to Heroku, while sphinx documentation will be build and served on myapp-docs separately.

Custom wsgi.py file

You can have a custom wsgi.py file to enable oauth2 authentication and use SSL.

• Create a wsgi.py file in your docs folder

  h docs/wsgi.py
  

• Customize the wsgi.py file to authenticate user login using wsgi-oauth2 and SSL.

rt os

rt requests
rt static
 wsgi_sslify import sslify
 wsgioauth2 import Service


s GoogleService(Service):
def __init__(self, allowed_domains=None):
    super().__init__(
        authorize_endpoint='https://accounts.google.com/o/oauth2/auth',
        access_token_endpoint='https://accounts.google.com/o/oauth2/token')

    if isinstance(allowed_domains, str):
        allowed_domains = allowed_domains.split(',')
    self.allowed_domains = allowed_domains

def is_user_allowed(self, access_token):
    response = requests.get(
        'https://www.googleapis.com/oauth2/v1/tokeninfo',
        params={'access_token': access_token['access_token']},
        verify=True,
    )

    res = response.json()
    email = res['email']
    verified = res['verified_email']
    return any(
        email.endswith(allowed_domain)
        for allowed_domain in self.allowed_domains
    ) and verified


= os.environ.get('GOOGLE_OAUTH2_KEY')
et = os.environ.get('GOOGLE_OAUTH2_SECRET')

le = GoogleService(allowed_domains=os.environ.get('GOOGLE_ALLOWED_DOMAINS'))

nt = google.make_client(client_id=key, client_secret=secret, scope="email")

ication = static.Cling('/app/docs/_build/html')
ication = client.wsgi_middleware(application, secret=secret.encode('utf-8'), path='/oauth2/')
ication = sslify(application, proxy_header='X-Forwarded-Proto')

Custom post_compile file

• Create a post_compile file in your docs folder

  h docs/post_compile
  

• Customize your post_compile

 custom commands


install -r ${BUILD_DIR}/docs/requirements.txt

ild Sphinx documentation
${BUILD_DIR}/docs && make apidoc html)