Welcome to griffin’s documentation!¶

Release v0.0.1.dev1 (What’s new?).

griffin is an Apache 2.0-licensed documentation generator written in Python leveraging the RAMLfications library to create API docs from RAML.

If you’ve never heard of RAML, you’re missing out:

RESTful API Modeling Language (RAML) is a simple and succinct way of describing practically-RESTful APIs. It encourages reuse, enables discovery and pattern-sharing, and aims for merit-based emergence of best practices. The goal is to help our current API ecosystem by solving immediate problems and then encourage ever-better API patterns. RAML is built on broadly-used standards such as YAML and JSON and is a non-proprietary, vendor-neutral open spec.

About¶

griffin’s documentation lives at Read the Docs, the code on GitHub. It’s tested on Python 2.6, 2.7, 3.3+, and PyPy. Both Linux and OS X are supported.

User’s Guide¶

Warning

This is an ALPHA! Be prepared for shit to break!

Requirements and Installation¶

User Setup¶

The latest version (currently alpha only) can be found on PyPI, and you can install via pip:

$ pip install griffin --pre

The --pre is needed to download since it’s still in alpha.

Continue onto usage to get started on using griffin.

Supported Python/Systems¶

Warning

currently runs with Python 2.7 - but will get up to 3.3+ and PyPy

Both Linux and OS X are supported.

Developer Setup¶

If you’d like to contribute or develop upon griffin, be sure to read How to Contribute first.

System requirements:¶

C Compiler (gcc/clang/etc.)
If on Linux - you’ll need to install Python headers (e.g. apt-get install python-dev)
Python 2.6, 2.7, 3.3+, or PyPy
virtualenv

Here’s how to set your machine up:

$ git clone git@github.com:spotify/griffin
$ cd griffin
$ virtualenv env
$ source env/bin/activate
(env) $ pip install -r dev-requirements.txt

Run Tests¶

If you’d like to run tests for all supported Python versions, you must have all Python versions installed on your system. I suggest pyenv to help with that.

To run all tests:

(env) $ tox

To run a specific test setup (options include: py26, py27, py33, py34, pypy, flake8, verbose, manifest, docs, setup, setupcov):

(env) $ tox -e py26

To run tests without tox:

(env) $ py.test
(env) $ py.test --cov griffin --cov-report term-missing

Build Docs¶

Documentation is build with Sphinx, written in rST, uses the Read the Docs theme with a slightly customized CSS, and is hosted on Read the Docs site.

To rebuild docs locally, within the parent griffin directory:

(env) $ tox -e docs

or:

(env) $ sphinx-build -b docs/ docs/_build

or:

(env) $ cd docs
(env) $ make html

Then within griffin/docs/_build you can open the index.html page in your browser.

Still have issues?¶

Feel free to drop by #ramlfications on Freenode (webchat) (no dedicated IRC channel - yet) or ping via Twitter. “roguelynn” on IRC is the maintainer, a.k.a econchick on GitHub, and based in San Fran.

Usage¶

To use griffin:

$ griffin build -r path/to/api.raml

With the above example, new directories & HTML files should now live in output.

To view them, you can simply run the following command within output:

$ python -m SimpleHTTPServer 8080

then navigate your browser to localhost:8080.

Note

Make sure the port in the above command matches your config file (if you have one). The default will be 8080.

For more information about the griffin build command, continue to API Definition.

API Definition¶

CLI¶

build -r RAMLFILE¶

Command-line function to build HTML documentation off of a given RAML file.

-o OUTPUT, --output OUTPUT¶: Specify where to output the built HTML files. If not given, then output from the giving config file will be used. If not defined in output, then a directory named output will be created in the relative location that the command is ran.

-c CONFIGFILE, --config CONFIGFILE¶

A yaml configuration file for the documentation generator. See Configuration for more information.

If no config file is provided, griffin will look for a file called griffin.yaml by default within the same directory that the build command is run.

-R RAMLCONFIGFILE, --ramlconfig RAMLCONFIGFILE¶: A ini configuration file for parsing RAML. See the ramlfications documentation for more information.

-q, --quiet¶: Suppress output.

griffin.cli.build(ramlfile, config, output=None, ramlconfig=None)¶

Builds HTML templates from a RAML file and saves to desired output.

Parameters:	ramlfile (str) – path to raml file config (dict) – documentation config output (str) – output of HTML files ramlconfig (str) – configuration for RAML parsing. See ramlfications documentation for more information.

Core¶

class griffin.core.APIContext¶

Context object of the parsed API.

api¶: The API parsed by ramlfications.

metadata¶: Metadata about the API.

groupings¶

A dict of groups of endpoints, defined by their parent nodes. For example,:

/foo
    displayName: Foo
    description: a foo endpoint
    get:
    /{id}
        displayName: A single Foo
        description: A particular Foo
        get:

There would be a foo grouping, with the foo and the foo/{id} endpoints.

endpoints¶: A list of all parsed endpoints.

griffin.core.create_context(ramlfile, ramlconfig=None)¶

Returns context to populate templates.

Parameters:	ramlfile (str) – RAML file to parse ramlconfig (str) – config file for RAML (see `ramlfications` docs)
Return type:	`APIContext` object

Configuration¶

You may use a yaml file to help configure the generation of your documentation. You’ll notice without certain fields within your config, you’ll see some attributes titled MISSING. So it may be a good idea to have a config file.

When running the build command on the command line, griffin will automatically look for a griffin.yaml file within the directory that build is run.

You may also provide the build command with a path to a different config file, via -c or --config. See API Definition for more details.

HTML `<head>` & Metadata¶

variable name	what	used for	default
`title`	`str`	Site title	`MISSING`
`base_url`	`str`	Relative URL for assets	`http://localhost:8080`
`description`	`str`	Site description	`MISSING`
`author`	`str`	Site Author name	`MISSING`
`canonical_url`	URL that site will be deployed to	Canonical URL	`MISSING`
`favicon`	path to an image relative to `static_dir`	Favicon	default theme img

Theming¶

variable name	what	used for	default
`brand_image`	path to an image relative to `static_dir`	Navbar Brand image	default theme img
`theme_path`	path to an image relative to `static_dir`	Location of own theme	built-in themes
`theme_name`	name of them	Directory name of theme	`default`

Directory Locations¶

variable name	what	used for	default
`template_dir`	path to directory	Your own templates	`templates`
`static_dir`	path to directory	Your own static assets	`assets`
`output_dir`	path to directory	Final HTML output	`output`

Project Information¶

Contributing¶

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

You can contribute in many ways:

Types of Contributions¶

Report Bugs¶

Report bugs at https://github.com/spotify/griffin/issues.

If you are reporting a bug, please include:

Your operating system name and version.
Any details about your local setup that might be helpful in troubleshooting.
Detailed steps to reproduce the bug.

Fix Bugs¶

Look through the GitHub issues for bugs. Anything tagged with “bug” is open to whoever wants to implement it.

Implement Features¶

Look through the GitHub issues for features. Anything tagged with “feature” is open to whoever wants to implement it.

Write Documentation¶

griffin could always use more documentation, whether as part of the official griffin docs, in docstrings, or even on the web in blog posts, articles, and such.

Submit Feedback¶

The best way to send feedback is to file an issue at https://github.com/spotify/griffin/issues.

If you are proposing a feature:

Explain in detail how it would work.
Keep the scope as narrow as possible, to make it easier to implement.
Remember that this is a volunteer-driven project, and that contributions are welcome :)

Get Started!¶

Ready to contribute? Here’s how to set up griffin for local development.

Fork the griffin repo on GitHub.

Clone your fork locally:

$ git clone git@github.com:your_name_here/griffin.git

Create a branch for local development:

$ git checkout -b name-of-your-bugfix-or-feature

Now you can make your changes locally.

When you’re done making changes, check that your changes pass style and unit tests, including testing other Python versions with tox:
```
$ tox
```

To get tox, just pip install it.

Commit your changes and push your branch to GitHub:

$ git add .
$ git commit -m "Your detailed description of your changes."
$ git push origin name-of-your-bugfix-or-feature

Submit a pull request through the GitHub website.

Pull Request Guidelines¶

Before you submit a pull request, check that it meets these guidelines:

The pull request should include tests.
If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst.
The pull request should work for Python 2.6, 2.7, and 3.3, and for PyPy. Check https://travis-ci.org/spotify/griffin under pull requests for active pull requests or run the tox command and make sure that the tests pass for all supported Python versions.

Tips¶

To run a subset of tests:

$ py.test test/test_griffin.py

License and Hall of Fame¶

griffin is licensed under the Apache 2.0 license. The full license text can be also found in the source code repository.

Credits¶

Development Lead¶

Lynn Root <lynn@spotify.com>

Contributors¶

None yet. Why not be the first?

Changelog¶

0.0.1a (2015-07-29)¶

Super alpha version!