DNAnexus Public Developer Documentation Wiki Repo

If you are browsing this repo on Github or reading this file in a git checkout on your local machine, this repository backs the wiki at http://wiki.dnanexus.com. To change it, you can either use the wiki interface or fork this repo and send us a pull request. Comments are encouraged: please comment on commits inline or open an issue in the Issues tab.

Style Guide

API methods

Inputs

Inputs appear in a list after the heading 'Inputs'. Example:

  • name string The name of this app
  • count number How many widgets the app contains

Description

The first letter of the description is capitalized, whether or not the description is a phrase or sentence. This is to help visually distinguish the description from the type and the optional part (if included). Where it makes sense, don't reuse the input's name in the input description to avoid a circular definition. Example:

  • id string The folder's id will be used to uniquely identify it and distinguish it from other folders.
  • name string (optional, defaults to a string generated from the folder id) The folder's name
  • count number (optional, defaults to 1) Space will be allocated for this many files within the folder.

Names

Input names look like code. Do this in all contexts when referring to a specific input, not just when listing the arguments. E.g. when an argument name appears in a description. Example:

  • name string The name of this app
  • aliases array of strings The different ways to refer to this app, including the app's name

Notice how name is not bold in the first description, because we're describing the argument, not referring to it, but in the second description, when we refer to name we make it look like code.

Types

The type of each argument always comes after the argument name, in bold. Please include the type even if you feel it's obvious. Example:

  • name string The name of this app

The input type may be one of the following: string, number, boolean, array of innerType, mapping

Examples:

  • tags array of strings The tags to add to this app version
  • count number How many widgets the app will have
  • name string The name of this app

mapping has a little extra formatting to explain the keys and values. A description of the mapping goes on the first line. The key and value each appear on a new line. The value's type is stated, but not the key's type, because keys are always strings. Example:

  • widgetCounts mapping The number of widgets of each type.
    • key Widget's type
    • value number The number of widgets of this type

For string, do not say nonempty string. If an empty string is an error, state that in the Errors section for the function. The type is intended to be very brief.

Optional Inputs

Optional inputs are denoted by (optional) immediately after the type. If the optional part needs further explanation, put the explanation in the same parenthesis. Where possible, group all required inputs first and all optional inputs last. This helps the reader know what's strictly required in a quick glance, without requiring them to read all inputs. See the examples for suggested phrasings. Examples:

  • tags array of strings (optional) Tags to associate with the object
  • makeDefault boolean (optional; default false) The name of the object
  • name string (optional; defaults to the generated object ID) The name of the object
  • foo integer (optional; mutually exclusive with bar) Number of foo widgets
  • bar integer (optional; mutually exclusive with foo) Number of bar widgets

Complex Outputs

  • pricingModelsByRegion mapping Contains pricing models

    • key the string "aws:us-east-1"
    • value mapping pricing model

      • storageRatePerGBMonth number Storage rate

      The following field will be present only if the org has the phiFeaturesEnabled field set to true:

      • computeRatesPerHourPHI mapping

Line breaks

For adding line breaks, <br/> is preferred over two trailing spaces because it's more explicit. It's too easy to accidentally delete whitespace without realizing it. Also, trailing whitespace is not significant in most programming contexts, and some tools will automatically remove it.

List of routes

When presenting a list of API routes, use a markdown list:

  • file/new
  • file/addTypes

Alerts

Warning! Best check yo self, you're not looking too good. Use class .alert
Heads up! This alert needs your attention, but it's not super important. Use class .alert and .alert-info
Well done! You successfully read this important alert message. User class .alert and .alert-success
Oh snap! Change a few things up and try submitting again. Use class .alert and .alert-error

Alert Block

For longer messages, increase the padding on the top and bottom of the alert wrapper by using .alert and .alert-block

dxcode

<div class='dxcode'>$ <font color='blue'>&lt;ENTER&gt;</font></div>
$ <ENTER>

Image thumbnails

Check the image into Git, under /Images/.

<a href="/Images/ExampleScreenshot.png" rel="lightbox" title="DNAnexus Platform">
<img src="/Images/ExampleScreenshot.png" width="20%" height="20%"/>
</a>

こんにちは добрый вечер

Math
  • ( e^{ix} = \cos x + i\sin x )

[ E[\pi]=\theta=E\left[\frac{S}{\sum_{i=1}^{n-1} \frac{1}{i}}\right]=4N\mu ]

Font awesome

Markdown formatted table
First Header Second Header
Content Cell Content Cell
Content Cell Content Cell

Put [[ _TOC_ ]] (but with no spaces) in your page to generate a table of contents:

Or use sidebars. See the Gollum wiki project page for more docs.

Syntax highlighting
def foo(bar):
    print "hi"

Inserting images, files, and other assets

  • Check in the image into dev_wiki:Images/
  • Run the wiki sync script (sync_dev_wiki in the cells repo). (If you don't have direct access, we will do this for you.)
  • Link to the image like so:
<img src="/Images/dnanexus_big_white_logo.png" />

Formatting wishlist

This is where we list things that we'd like to have a style guide for. Feel free to add to this list.

API methods

  • ...nothing yet...

Quickstarts

  • Graphic symbols for displaying next to tips, "for more information" links, etc.

Broken link detection and warnings

  • Functionality to replace Mediawiki's "what links here" and "leave a redirect behind" (or "rewrite all links to this page" when moving).

Link-Title Link-Title

DNAnexus custom alert formatting

<div class=alert>Alert</div>
<div class='alert alert-info'>Alert: Info</div>
<div class='alert alert-success'>Alert: Success</div>
<div class='alert alert-error'>Alert: Error</div>
Alert
Alert: Info
Alert: Success
Alert: Error
Serious Business
{
    "error": {
        "type": "Analysis failed",
        "message": "Not enough DNAnexus"
    }
}

foobar

Image thumbnails

Check in the image as described above.

<a href="/Images/ExampleScreenshot.png" rel="lightbox" title="DNAnexus Platform">
<img src="/Images/ExampleScreenshot.png" width="20%" height="20%"/>
</a>

Collapsible sections

For best results:

  • Remove the space between __ and BEGIN_EXPANDABLES below.
  • Use the BEGIN and END strings only once on a page
__ BEGIN_EXPANDABLES
### Barney
This collapsible section is expandable.

### Lee
Another expandable collapsible section.

### Villain
Currently, only H3 tags (`### Heading`) are supported.

### Gunnar
We use these collapsible sections for the [[FAQ]].
__END_EXPANDABLES

Barney

This collapsible section is expandable.

Lee

Another expandable collapsible section.

Villain

Currently, only H3 tags (### Heading) are supported.

Gunnar

We use these collapsible sections for the FAQ.

Alternatively, plain HTML can also be used.

<div id="expandables">
  <h4>Section 1</h4>
  <div>
    <p>
    Paragraph 1
    </p>
  </div>
  <h4>Section 2</h4>
  <div>
    <p>
    Paragraph 1
    </p>
  </div>
</div>

Code/Other tabs

This is also borrowed from jQuery. To use:

  • remove spaces after "__" in the following example
  • __ OPENDIV → "<div"
  • __ RANGLE → ">"
  • __ CLOSEDIV → "</div>"
__ OPENDIV class='tabs'
 __ RANGLE

- [bash](#parallel-bash)
- [Python](#parallel-python)

__ OPENDIV id="parallel-bash"
 __ RANGLE
 ```bash (without the leading space)
# Anything outside the function declarations is always run

myfunc() {
        echo $myinput
}

main() {
        # main gets run when you run the app/applet

        # The following line creates a new job running "myfunc" which
        # will receive an input variable $myinput set to "hello world"

        dx-jobutil-new-job myfunc -imyinput='hello world'
}
 ``` (without the leading space)
 __ CLOSEDIV
 __ OPENDIV id="parallel-python"
 __ RANGLE
 ```python (without the leading space)
import dxpy

@dxpy.entry_point("myfunc")
def myfunc(myinput):
    print myinput

@dxpy.entry_point("main")
def main():
    # main gets run when you run the app/applet

    # The following line creates a new job running "myfunc" which
    # will receive an input variable myinput set to "hello world"

    dxpy.new_dxjob(fn_input={ "myinput": "hello world" }, fn_name="myfunc")

# The following line will call the appropriate entry point.
dxpy.run()
 ``` (without the leading space)
 __ CLOSEDIV
 __ CLOSEDIV

# Anything outside the function declarations is always run

myfunc() {
        echo $myinput
}

main() {
        # main gets run when you run the app/applet

        # The following line creates a new job running "myfunc" which
        # will receive an input variable $myinput set to "hello world"

        dx-jobutil-new-job myfunc -imyinput='hello world'
}
import dxpy

@dxpy.entry_point("myfunc")
def myfunc(myinput):
    print myinput

@dxpy.entry_point("main")
def main():
    # main gets run when you run the app/applet

    # The following line creates a new job running "myfunc" which
    # will receive an input variable myinput set to "hello world"

    dxpy.new_dxjob(fn_input={ "myinput": "hello world" }, fn_name="myfunc")

# The following line will call the appropriate entry point.
dxpy.run()

Citations

<a rel="citation" doi="doi:10.1093/bioinformatics/btp324">
  doi:10.1093/bioinformatics/btp324
</a>

doi:10.1093/bioinformatics/btp324

Last edited by Phil Sung, 2015-12-30 05:47:56

 Feedback