sanic/docs/contributing.md

# Contributing

Thank you for your interest! Sanic is always looking for contributors. If you
don't feel comfortable contributing code, adding docstrings to the source files
is very appreciated.

## Running tests

* `python -m pip install pytest`
* `python -m pytest tests`

## Documentation

Sanic's documentation is built
using [sphinx](http://www.sphinx-doc.org/en/1.5.1/). Guides are written in
Markdown and can be found in the `docs` folder, while the module reference is
automatically generated using `sphinx-apidoc`.

To generate the documentation from scratch:

```bash
sphinx-apidoc -fo docs/_api/ sanic
sphinx-build -b html docs docs/_build
```

The HTML documentation will be created in the `docs/_build` folder.

## Warning

One of the main goals of Sanic is speed. Code that lowers the performance of
Sanic without significant gains in usability, security, or features may not be
merged. Please don't let this intimidate you! If you have any concerns about an
idea, open an issue for discussion and help.

**Previous:** [Sanic extensions](extensions.md)
Clarify, reformat, and add to documentation guides (#318) * Reorder and clarify the 'Request Data' guide, adding a section on RequestParameters * Clarify routing guide, adding introduction and HTTP types sections * Clarify the use-cases of middleware * Clean up formatting in the exceptions guide and add some common exceptions. * Fix formatting of blueprints and add use-case example. * Clarify the class-based views guide * Clarify and fix formatting of cookies guide * Clarify static files guide * Clarify the custom protocols guide. * Add more information to the deploying guide * Fix broken list in the community extensions list. * Add introduction and improve warning to contributing guide * Expand getting started guide * Reorder guides and add links between them * Standardise heading capitalisation 2017-01-20 03:18:52 +00:00			`# Contributing`
Added tests and middleware, and improved documentation 2016-10-14 11:23:48 +01:00
Clarify, reformat, and add to documentation guides (#318) * Reorder and clarify the 'Request Data' guide, adding a section on RequestParameters * Clarify routing guide, adding introduction and HTTP types sections * Clarify the use-cases of middleware * Clean up formatting in the exceptions guide and add some common exceptions. * Fix formatting of blueprints and add use-case example. * Clarify the class-based views guide * Clarify and fix formatting of cookies guide * Clarify static files guide * Clarify the custom protocols guide. * Add more information to the deploying guide * Fix broken list in the community extensions list. * Add introduction and improve warning to contributing guide * Expand getting started guide * Reorder guides and add links between them * Standardise heading capitalisation 2017-01-20 03:18:52 +00:00			`Thank you for your interest! Sanic is always looking for contributors. If you`
			`don't feel comfortable contributing code, adding docstrings to the source files`
			`is very appreciated.`
Added tests and middleware, and improved documentation 2016-10-14 11:23:48 +01:00
Basic documentation 2016-10-14 12:51:08 +01:00			`## Running tests`
Clarify, reformat, and add to documentation guides (#318) * Reorder and clarify the 'Request Data' guide, adding a section on RequestParameters * Clarify routing guide, adding introduction and HTTP types sections * Clarify the use-cases of middleware * Clean up formatting in the exceptions guide and add some common exceptions. * Fix formatting of blueprints and add use-case example. * Clarify the class-based views guide * Clarify and fix formatting of cookies guide * Clarify static files guide * Clarify the custom protocols guide. * Add more information to the deploying guide * Fix broken list in the community extensions list. * Add introduction and improve warning to contributing guide * Expand getting started guide * Reorder guides and add links between them * Standardise heading capitalisation 2017-01-20 03:18:52 +00:00
Added tests and middleware, and improved documentation 2016-10-14 11:23:48 +01:00			* `python -m pip install pytest`
			* `python -m pytest tests`

Use Sphinx for documentation. This commit creates configuration files and an index page for documentation using Sphinx. The recommonmark package is used to enable Markdown support for Sphinx, using the Common Mark specification. This means that the current documentation doesn't need to be rewritten. 2016-12-25 09:20:48 +00:00			`## Documentation`

Clarify, reformat, and add to documentation guides (#318) * Reorder and clarify the 'Request Data' guide, adding a section on RequestParameters * Clarify routing guide, adding introduction and HTTP types sections * Clarify the use-cases of middleware * Clean up formatting in the exceptions guide and add some common exceptions. * Fix formatting of blueprints and add use-case example. * Clarify the class-based views guide * Clarify and fix formatting of cookies guide * Clarify static files guide * Clarify the custom protocols guide. * Add more information to the deploying guide * Fix broken list in the community extensions list. * Add introduction and improve warning to contributing guide * Expand getting started guide * Reorder guides and add links between them * Standardise heading capitalisation 2017-01-20 03:18:52 +00:00			`Sanic's documentation is built`
			`using [sphinx](http://www.sphinx-doc.org/en/1.5.1/). Guides are written in`
			Markdown and can be found in the `docs` folder, while the module reference is
			automatically generated using `sphinx-apidoc`.
Use Sphinx for documentation. This commit creates configuration files and an index page for documentation using Sphinx. The recommonmark package is used to enable Markdown support for Sphinx, using the Common Mark specification. This means that the current documentation doesn't need to be rewritten. 2016-12-25 09:20:48 +00:00
			`To generate the documentation from scratch:`

			```bash
Update documentation generation instructions. 2017-01-19 22:32:08 +00:00			`sphinx-apidoc -fo docs/_api/ sanic`
Use Sphinx for documentation. This commit creates configuration files and an index page for documentation using Sphinx. The recommonmark package is used to enable Markdown support for Sphinx, using the Common Mark specification. This means that the current documentation doesn't need to be rewritten. 2016-12-25 09:20:48 +00:00			`sphinx-build -b html docs docs/_build`
			```

			The HTML documentation will be created in the `docs/_build` folder.

Basic documentation 2016-10-14 12:51:08 +01:00			`## Warning`
Clarify, reformat, and add to documentation guides (#318) * Reorder and clarify the 'Request Data' guide, adding a section on RequestParameters * Clarify routing guide, adding introduction and HTTP types sections * Clarify the use-cases of middleware * Clean up formatting in the exceptions guide and add some common exceptions. * Fix formatting of blueprints and add use-case example. * Clarify the class-based views guide * Clarify and fix formatting of cookies guide * Clarify static files guide * Clarify the custom protocols guide. * Add more information to the deploying guide * Fix broken list in the community extensions list. * Add introduction and improve warning to contributing guide * Expand getting started guide * Reorder guides and add links between them * Standardise heading capitalisation 2017-01-20 03:18:52 +00:00
			`One of the main goals of Sanic is speed. Code that lowers the performance of`
			`Sanic without significant gains in usability, security, or features may not be`
			`merged. Please don't let this intimidate you! If you have any concerns about an`
			`idea, open an issue for discussion and help.`

Fixes doc link extensions from .html to .md Whoops! Totally missed that all the links pointed to `.html` files instead of `.md` files 2017-01-20 03:24:08 +00:00			`Previous: [Sanic extensions](extensions.md)`