Writing WDAE API documentation¶

The Workflow¶

The WDAE API documentation is written in Python docstrings. When building the documentation, a custom tool (api_docs_generator.py) will scan the WDAE project root directory for pairs of urls.py and views.py files in directories. Then it will collect the docstrings inside them and output the result in a formatted reStructuredText file in wdae/wdae/docs/routes.

The Format¶

The documentation written must strictly follow the custom format or else the route will be skipped in the generation process. The format is newline sensitive and consists of sections.

Sections¶

A section begins with the section name followed by : and a new line. The section ends when a new section begins or the docstring ends.

The only requirement of the documentation format is to have a summary line at the start, followed by sections afterwards. Section names are case insensitive. Section order is not important.

Because sections are line sensitive, some section lines have to follow a specific format.

The currently supported sections are as follows:

Request¶

Contains an example request that can be sent to this route.

Lines have no format, but it is important to use the first line as a base for indentation.

Request:
    POST /genotype_browser/preview/variants HTTP/1.1
    Host: example.com
    Content-Type: application/json
    Accept: text/event-stream

    {
      "datasetId": "iossifov_2014",
      "maxVariantsCount": 1000
    }

Response¶

Contains an example response that the API will return.

Lines have no format, but it is important to use the first line as a base for indentation.

Response:
    HTTP/1.1 200 OK
    Vary: Accept
    Content-Type: text/event-stream
    [

    [col1,col2,col3,col4.....]

    ]

Status codes¶

Lists all the response status codes and what they mean in the context of the route.

Lines follow a parametered format and must look like this:
{status code number}: {code description}

Status codes:
Request passed
Unauthorized
Dataset not found
Some specific internal error

URL parameters¶

Lists all URL parameters that can be passed to a request on this route.

Lines follow a parametered format and must look like this:
{url parameter name}: {parameter description}

URL parameters:
    dataset_id: ID of the requested dataset

Query parameters¶

Lists all query parameters that can be passed to a request on this route.

Lines follow a parametered format and must look like this:
{query parameter name}: {parameter description}

Query parameters:
    dataset_id: ID of the requested dataset

Request JSON parameters¶

Lists all parameters that can be passed to the request JSON body.

Lines follow a typed parameter format and must look like this:
{json parameter name} ({json parameter type}): {parameter description}

Request JSON parameters:
    dataset_id (string): ID of the requested dataset

Response JSON parameters¶

Lists all parameters that can be returned in the JSON body.

Lines follow a typed parameter format and must look like this:
{json parameter name} ({json parameter type}): {parameter description}

Response JSON parameters:
    studies (list): List of studies in dataset

The Tool¶

The generation tool is located at wdae/wdae/docs/api_docs_generator.py. When run with no arguments, it will regenerate the documentation for all routes automatically.

Arguments¶

--root-dir

The root directory from which to scan for views.py and urls.py files.

By default it will find and use wdae/wdae as a root directory.

--output-dir

The directory in which to place the generated .rst files.

By default it will be wdae/wdae/docs/routes.

--verbose, -v, -V

Sets the verbosity level of the tool.

After all arguments, you can list specific routes to document, instead of every single one found.

Manually generating the documentation¶

When writing new documentation, you should check whether it will be successfully generated.

First, activate the gpf conda environment.

conda activate gpf

Next, you need to run the documentation generation tool. With default arguments, it should find all the necessary routes.

api_docs_generator.py -vv

Optionally, you can generate the documentation only for a given folder.

api_docs_generator.py -vv genotype_browser

Note

It is recommended to use -vv and to specify the route when testing your documentation generation, as the output is detailed and will be littered with errors until all routes are documented.

Once the .rst files are generated, they should be placed in wdae/wdae/docs/routes if a different output_dir was specified when generating.

Now you need to build the documentation:

make html

Now open _build/html/index.html with your preferred browser.