From 329fd0a7eb055b01f127c6640a2f85e6d0b1d31b Mon Sep 17 00:00:00 2001 From: Tom Gallacher Date: Fri, 27 Jan 2017 12:49:48 +0000 Subject: [PATCH] Add docs service --- docker-compose.yml | 14 ++++ docs/.gitignore | 1 + docs/Dockerfile | 16 ++++ docs/Makefile | 56 +++++++++++++ docs/README.rst | 49 ++++++++++++ docs/circle.yml | 22 ++++++ docs/source/conf.py | 161 ++++++++++++++++++++++++++++++++++++++ docs/source/deployment.md | 48 ++++++++++++ docs/source/index.rst | 17 ++++ local-compose.yml | 7 ++ 10 files changed, 391 insertions(+) create mode 100644 docs/.gitignore create mode 100644 docs/Dockerfile create mode 100644 docs/Makefile create mode 100644 docs/README.rst create mode 100644 docs/circle.yml create mode 100644 docs/source/conf.py create mode 100644 docs/source/deployment.md create mode 100644 docs/source/index.rst diff --git a/docker-compose.yml b/docker-compose.yml index b778fac7..328cea21 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -96,3 +96,17 @@ prometheus: labels: - triton.cns.services=prometheus - com.docker.swarm.affinities=["container!=~*prometheus*"] +############################################################################# +# docs is an open source performance monitoring tool +# it is included here for demo purposes and is not required +############################################################################# +docs: + image: quay.io/yldio/joyent-portal-docs + restart: always + mem_limit: 128m + env_file: .env + ports: + - 80:80 + labels: + - triton.cns.services=docs + - com.docker.swarm.affinities=["container!=~*docs*"] diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 00000000..378eac25 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +build diff --git a/docs/Dockerfile b/docs/Dockerfile new file mode 100644 index 00000000..aea2d3cf --- /dev/null +++ b/docs/Dockerfile @@ -0,0 +1,16 @@ +FROM jfloff/alpine-python:3.4-slim +RUN /entrypoint.sh \ + -p sphinx \ + -p recommonmark \ + -p sphinx_rtd_theme \ + -a make \ +&& echo + +RUN mkdir -p /docs/ +WORKDIR /docs/ +COPY Makefile . +COPY source ./source/ +RUN make html +WORKDIR /docs/build/html/ +EXPOSE 8080 +CMD ["python", "-m", "http.server", "8080"] diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..08e599c9 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,56 @@ +NAME := $(lastword $(subst /, ,$(CURDIR))) +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SPHINXPROJ = PrototypeJoyentPortal +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: build +build: + docker build -t quay.io/yldio/joyent-dashboard-$(NAME) . + +.PHONY: push +push: + docker push quay.io/yldio/joyent-dashboard-$(NAME) + +.PHONY: test +test: + +.PHONY: test-ci +test-ci: + +.PHONY: install +install: + +.PHONY: start +start: + +.PHONY: install-production +install-production: + +.PHONY: clean +clean: + +.PHONY: lint +lint: + +.PHONY: lint-ci +lint-ci: + +.PHONY: licence-check +lint-ci: diff --git a/docs/README.rst b/docs/README.rst new file mode 100644 index 00000000..7f844c8c --- /dev/null +++ b/docs/README.rst @@ -0,0 +1,49 @@ +Prototype Joyent Portal Docs +************** + +This repo contains the source code for the `Prototype Joyent Portal docs`_. + +Contributing +############ + +Fork the repo, make an edit, submit a PR. No patch is too small! <3 + +Building locally +################ + +1. Install `Sphinx `_. +2. Install ``sphinx_rtd_theme`` with ``pip install sphinx_rtd_theme`` +3. Run ``make html`` +4. Open ``build/html/index.html`` in your browser. + +Deployment +########## + +``master`` is automatically deployed to `https://xxx `_. + +License +####### + +This project was forked from `https://github.com/shoreditch-ops/artillery-docs`_ + +:: + + The MIT License (MIT) + Copyright (c) 2015-2016 Shoreditch Ops Ltd + + 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. diff --git a/docs/circle.yml b/docs/circle.yml new file mode 100644 index 00000000..327866c9 --- /dev/null +++ b/docs/circle.yml @@ -0,0 +1,22 @@ +machine: + python: + version: 2.7.5 + environment: + PATH: "/usr/local/bin:${PATH}" +dependencies: + cache_directories: + - "~/.apt-cache" + pre: + - sudo rm -rf /var/cache/apt/archives && sudo ln -s ~/.apt-cache /var/cache/apt/archives && mkdir -p ~/.apt-cache/partial + - sudo apt-get update; sudo apt-get install python-sphinx + - pip install sphinx_rtd_theme + - pip install s3cmd +test: + override: + - make html +deployment: + production: + branch: master + commands: + - cp .s3cfg ~/.s3cfg + - bash scripts/deploy.sh diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 00000000..f45ee3ed --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,161 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +# +# Prototype Joyent Portal documentation build configuration file, created by +# sphinx-quickstart on Fri Jan 27 11:28:13 2017. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) +import sphinx_rtd_theme + + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = ['sphinx.ext.githubpages'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +from recommonmark.parser import CommonMarkParser + +source_parsers = {'.md': CommonMarkParser} +source_suffix = ['.rst', '.md'] + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = 'Prototype Joyent Portal' +copyright = '2017, YLD and Make Us Proud' +author = 'YLD and Make Us Proud' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '1.0' +# The full version, including alpha/beta/rc tags. +release = '1.0.0' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = [] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "sphinx_rtd_theme" + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] + +# 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, +# so a file named "default.css" will overwrite the builtin "default.css". +# html_static_path = ['_static'] + + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = 'PrototypeJoyentPortaldoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'PrototypeJoyentPortal.tex', 'Prototype Joyent Portal Documentation', + 'YLD and Make Us Proud', 'manual'), +] + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'prototypejoyentportal', 'Prototype Joyent Portal Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'PrototypeJoyentPortal', 'Prototype Joyent Portal Documentation', + author, 'PrototypeJoyentPortal', 'One line description of project.', + 'Miscellaneous'), +] + + + diff --git a/docs/source/deployment.md b/docs/source/deployment.md new file mode 100644 index 00000000..5ce18498 --- /dev/null +++ b/docs/source/deployment.md @@ -0,0 +1,48 @@ +# Deployment + +The project as it stands is a monorepo, each part of this prototype +(cloudapi-graphql, ui, frontend, nginx) can be found in the root directory. + +We currently are using [CircleCI](https://circleci.com/gh/yldio/joyent-portal/) +for continuous deployment. As soon as a commit is push to Github, we fire a hook +off to CircleCI which kicks off our tests. + +CircleCI is configured through the [circle.yaml](https://github.com/yldio/joyent-portal/blob/master/circle.yml) +found at the root of the project. The main take from this is that we install and +setup our dependencies such as docker, docker-compose, triton and yarn. CircleCI +then runs the appropriate Makefile command. + +## Configuration + +CircleCI is configured purely from environment variables. The current set of +variables are defined below, The SDC\_ variables are pulled directly from the +output of `triton env` and inserted into CircleCI to simplifying setting up triton-cli +in a testing environment. + +We also have some \_DOCKER\_ variables, again these are used by triton, but because +we wish to build and push the images inside CircleCI we only use them at deployment. + +The docker login username and password is derived from a robot account quay.io + + +``` +COMPOSE_HTTP_TIMEOUT +NPM_TOKEN +SDC_ACCOUNT +SDC_KEY_ID +SDC_URL +_DOCKER_CERT_PATH +_DOCKER_HOST +_DOCKER_LOGIN_PASSWORD +_DOCKER_LOGIN_USERNAME +_DOCKER_REGISTRY +_DOCKER_TLS_VERIFY +``` + +## /.bin/deploy + +This command is ran at the point when all of the tests are passing. It fires off +a call to `docker-compose -d up`. This can equally be ran on a developers machine +if manual intervention is needed. + + diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 00000000..60169779 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,17 @@ +.. Prototype Joyent Portal documentation master file, created by + sphinx-quickstart on Fri Jan 27 11:28:13 2017. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to Prototype Joyent Portal's documentation! +=================================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + deployment + + +Indices and tables +================== diff --git a/local-compose.yml b/local-compose.yml index 0b7d0c1c..a238d2a5 100644 --- a/local-compose.yml +++ b/local-compose.yml @@ -60,3 +60,10 @@ prometheus: - consul:consul ports: - 9090:9090 +docs: + extends: + file: docker-compose.yml + service: docs + restart: never + ports: + - 80:8081