Giter Club home page Giter Club logo

docsv2's Introduction

Shippable Documentation

Overview

Shippable is a docker based continuous integration and deployment platform. This repository contains the documentation, which is open source to allow anyone to make quick changes if needed.

The source is under sources/ in the form of .md files. These files use Markdown formatting with Mkdocs extensions for structure, cross-linking and some Markdown additional syntax using Python-Markdown.

The HTML files are built and hosted on Amazon S3, appearing via proxy on docs.shippable.com. The HTML files update automatically after each change to the master.

Contributing

Using Github web interface

For small changes and typos you might want to use GitHub's built in file editor. It allows you to preview your changes right online (though there can be some differences between GitHub flavored markdown and Mkdocs markdown). Just be careful not to create many commits.

Using local copy of the repository

Installation

To get started you have to have git and python3 with pip and virtualenv installed:

$ git clone [email protected]:Shippable/docs.git shippable-docs
$ cd shippable-docs
$ virtualenv venv
$ source venv/bin/activate
(venv)$ pip install -r requirements.txt

Server

To start documentation server at localhost:5555:

(venv)$ mkdocs serve --dev-addr=localhost:5555

It uses livereload there is no need to restart the server after changes have been made. Also it automatically reloads pages in the browser.

Structure

Page structure is really easy to change with mkdocs:

# mkdocs.yaml

pages:
  - [index.md, Overview]

  - [start.md, Getting Started]

  - [yml.md, Configuration, Configuring Your YML]
  - [config.md, Configuration, A Bit Deeper]

http://www.mkdocs.org/user-guide/configuration/#pages

Images

When you need to add images, try to make them as small as possible (e.g. as gif). Usually images should go to the same directory as the .md file which references them (![Alt](path.ext)), or in a subdirectory if one already exists.

Deploy

Just commit and push you changes to the master branch to update documentation site.

Settings

To configure deployment change shippable.yml:

# shippable.yml

env:
  global:
    - AWS_S3_LOCAL_PATH='site'
    - AWS_S3_BUCKET='s3://<bucket>'
    - AWS_S3_REGION='<region>'
    # AWS_ACCESS_KEY_ID
    # AWS_SECRET_ACCESS_KEY
    - secure: <encrypted>

notifications:
  email:
    recipients:
      - <email>

To update theme change files in theme/shippable directory.

During sphinx-mkdocs migration theme/shippable/static/ash files was handled as legacy code and never have been changed except:

  • theme/shippable/static/ash/js/custom.js
  • theme/shippable/static/ash/css/custom.css

All html files and those two files look like good targets for theme tweaking.

Issues

  • A broken link in api.md: https://prod-shippable.s3.amazonaws.com/artifacts/subscriptions/.../tar.gz
  • Mkdoks for now (May 2015) is a real raw project without enough documentation
  • "Edit this article" doesn't point to the document only to the whole source dir:
  • There are still 2 javascript errors (as before migration):
    • related to jsapi
    • related to async-ads.js
  • No text in 404.html because of bug with including content block
  • Header menu doesn't work on mobile (as before migration)
  • Bootstrap theme "Little Necko" patches bootstrap and does it in really odd way. Some hacks are used to fight "Little Necko". All css looks legacy and fragile. Hopefully css will be rewritten from strach soon.
  • Minor style bugs (especially for mobile)

As default in boostrap, shippable and docs.shippable use following font stack: "Helvetica Neue", Helvetica, Arial, sans-serif. Helvetica Neue is proprietary font is not available on most Linux ans Windows machines (that's true right?). Also it can't be shipped with website as webfont because of its license. That means Helvetica font for the most of the users which someone believe a little bit ugly font for the web.

docsv2's People

Contributors

manishas avatar avinci avatar kailevy avatar archana2015 avatar

Watchers

Christopher Lindblom avatar James Cloos avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.