-
Notifications
You must be signed in to change notification settings - Fork 8
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Added self-documenting capability to the API.
* Run the generate_docs.sh script to generate a man page describing all of the api commands. The man page is appropriate to distribute to end users, and is in fact geared for that. * The documentation is pulled from the galah.api.commands module. Modify the docstrings for functions in that module to modify the documentation. * An index.rst file was created that gives some summary info. This documentation structure is simple to understand, read up on Sphinx to learn more. * galah.api.commands.api_call was renamed to galah.api.commands._api_call to ensure it does not appear in the documentation.
- Loading branch information
John Sullivan
committed
Oct 24, 2012
1 parent
ff37f3b
commit 568f03b
Showing
4 changed files
with
125 additions
and
20 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,50 @@ | ||
# -*- coding: utf-8 -*- | ||
# | ||
# Galah documentation build configuration file, created by | ||
# sphinx-quickstart on Sun Oct 14 01:32:18 2012. Since modified (see git log) | ||
# | ||
# This file is execfile()d with the current directory set to its containing dir. | ||
|
||
import sys, os | ||
|
||
sys.path.insert(0, os.path.abspath('../../../')) | ||
|
||
# -- General configuration ----------------------------------------------------- | ||
|
||
extensions = ['sphinx.ext.autodoc'] | ||
|
||
# The suffix of source filenames. | ||
source_suffix = '.rst' | ||
|
||
# The master toctree document. | ||
master_doc = 'index' | ||
|
||
# General information about the project. | ||
project = u'Galah' | ||
copyright = u'2012, John Sullivan' | ||
|
||
# The version info for the project you're documenting. | ||
version = release = '0.2' | ||
|
||
# The name of the Pygments (syntax highlighting) style to use. | ||
pygments_style = 'sphinx' | ||
|
||
# -- Options for manual page output -------------------------------------------- | ||
|
||
# One entry per manual page. List of tuples | ||
# (source start file, name, description, authors, manual section). | ||
man_pages = [ | ||
('index', 'galah.api.commands', u'Galah\'s API Documentation', | ||
[u'John Sullivan'], 1) | ||
] | ||
|
||
# -- Autodoc signal handlers --------------------------------------------------- | ||
|
||
# Will skip all documentable objects that aren't exposed API functions | ||
def should_skip(app, what, name, obj, skip, options): | ||
from types import FunctionType | ||
|
||
return name.startswith("_") or type(obj) is not FunctionType | ||
|
||
def setup(app): | ||
app.connect('autodoc-skip-member', should_skip) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,29 @@ | ||
Galah API | ||
========= | ||
|
||
Summary | ||
------- | ||
This is a complete reference to Galah's outward facing API. If you are using | ||
api_client.py to access the API, you should treat each parameter given for | ||
the functions below as an argument to pass to the command. | ||
|
||
For example, to create a new user, you could execute... | ||
|
||
api_client.py create_user john.doe@college.edu StRongPassWOrd | ||
|
||
Notice I leave out the last two arguments (account_type and send_receipt). I | ||
can do this because both has default parameters. You could specify a value for | ||
each of them if you desire... | ||
|
||
api_client.py create_user jane.doe@college.edu DifferentPassWoRD teacher | ||
|
||
You will be given the results of your command in a human-readable format. | ||
|
||
If you are accessing the API via a Python interpreter, the only thing to note | ||
is that every API function will always, and only, return a string. This may be | ||
changed soon. | ||
|
||
Reference | ||
--------- | ||
.. automodule:: galah.api.commands | ||
:members: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,21 @@ | ||
#!/usr/bin/env bash | ||
|
||
# This will ensure that the script exits if a failure occurs | ||
set -e | ||
|
||
# This will ensure the user is visually prompted upon failure | ||
trap "echo FAILURE: An error has occured! >&2" EXIT | ||
|
||
# The directory that will contain all of the generated documentation | ||
DOCS_PATH=./docs | ||
|
||
## Create the API documentation for shell users ################################ | ||
echo Building API documentation... | ||
|
||
sphinx-build -q -a -b man ./docs/src/galah.api/ $DOCS_PATH | ||
|
||
echo "SUCCESS: MAN page 'galah.api.commands.1' created in $DOCS_PATH" | ||
|
||
# Unset the trap so we don't freak the user out by telling them an error has | ||
# occured when everything went fine. | ||
trap - EXIT |