diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 1db3cdd4..00000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,141 +0,0 @@ -# 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. - -We are committed to providing a friendly, safe and welcoming environment for all, -regardless of gender, sexual orientation, disability, ethnicity, religion, -or similar personal characteristic. -Our [code of conduct](./CONDUCT.md) sets the standards for behavior. - -## Installation - -To develop on sanic (and mainly to just run the tests) it is highly recommend to -install from sources. - -So assume you have already cloned the repo and are in the working directory with -a virtual environment already set up, then run: - -```bash -pip3 install -e . ".[dev]" -``` - -# Dependency Changes - -`Sanic` doesn't use `requirements*.txt` files to manage any kind of dependencies related to it in order to simplify the -effort required in managing the dependencies. Please make sure you have read and understood the following section of -the document that explains the way `sanic` manages dependencies inside the `setup.py` file. - -| Dependency Type | Usage | Installation | -| ------------------------------------------| -------------------------------------------------------------------------- | --------------------------- | -| requirements | Bare minimum dependencies required for sanic to function | pip3 install -e . | -| tests_require / extras_require['test'] | Dependencies required to run the Unit Tests for `sanic` | pip3 install -e '.[test]' | -| extras_require['dev'] | Additional Development requirements to add contributing | pip3 install -e '.[dev]' | -| extras_require['docs'] | Dependencies required to enable building and enhancing sanic documentation | pip3 install -e '.[docs]' | - -## Running all tests -To run the tests for Sanic it is recommended to use tox like so: - -```bash -tox -``` -See it's that simple! - -`tox.ini` contains different environments. Running `tox` without any arguments will -run all unittests, perform lint and other checks. - -## Run unittests : -`tox` environment -> `[testenv]` - -To execute only unittests, run `tox` with environment like so: - -```bash -tox -e py36 -v -- tests/test_config.py -# or -tox -e py37 -v -- tests/test_config.py -``` - -## Run lint checks : -`tox` environment -> `[testenv:lint]` - -Permform `flake8`, `black` and `isort` checks. -```bash -tox -e lint -``` - -## Run other checks : -`tox` environment -> `[testenv:check]` - -Perform other checks. -```bash -tox -e check -``` - -# Code Style -To maintain the code consistency, Sanic uses following tools. - -1. [isort](https://github.com/timothycrosley/isort) -2. [black](https://github.com/python/black) -2. [flake8](https://github.com/PyCQA/flake8) - - -## isort -`isort` sorts Python imports. It divides imports into three -categories sorted each in alphabetical order. - 1. built-in - 2. third-party - 3. project-specific - -## black -`black` is a Python code formatter. - -## flake8 -`flake8` is a Python style guide that wraps following tools into one. -1. PyFlakes -2. pycodestyle -3. Ned Batchelder's McCabe script - -`isort`, `black` and `flake8` checks are performed during `tox` lint checks. - -Refer [tox](https://tox.readthedocs.io/en/latest/index.html) documentation for more details. - -## Pull requests! - -So the pull request approval rules are pretty simple: -1. All pull requests must pass unit tests. -2. All pull requests must be reviewed and approved by at least - one current collaborator on the project. -3. All pull requests must pass flake8 checks. -4. All pull requests must be consistent with the existing code. -5. If you decide to remove/change anything from any common interface - a deprecation message should accompany it. -6. If you implement a new feature you should have at least one unit - test to accompany it. -7. An example must be one of the following: - * Example of how to use Sanic - * Example of how to use Sanic extensions - * Example of how to use Sanic and asynchronous library - -## 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. diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 00000000..5d969477 --- /dev/null +++ b/CONTRIBUTING.rst @@ -0,0 +1,252 @@ + +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. + +We are committed to providing a friendly, safe and welcoming environment for all, +regardless of gender, sexual orientation, disability, ethnicity, religion, +or similar personal characteristic. +Our `code of conduct <./CONDUCT.md>`_ sets the standards for behavior. + +Installation +------------ + +To develop on sanic (and mainly to just run the tests) it is highly recommend to +install from sources. + +So assume you have already cloned the repo and are in the working directory with +a virtual environment already set up, then run: + +.. code-block:: bash + + pip3 install -e . ".[dev]" + +Dependency Changes +------------------ + +``Sanic`` doesn't use ``requirements*.txt`` files to manage any kind of dependencies related to it in order to simplify the +effort required in managing the dependencies. Please make sure you have read and understood the following section of +the document that explains the way ``sanic`` manages dependencies inside the ``setup.py`` file. + +.. list-table:: + :header-rows: 1 + + * - Dependency Type + - Usage + - Installation + * - requirements + - Bare minimum dependencies required for sanic to function + - ``pip3 install -e .`` + * - tests_require / extras_require['test'] + - Dependencies required to run the Unit Tests for ``sanic`` + - ``pip3 install -e '.[test]'`` + * - extras_require['dev'] + - Additional Development requirements to add contributing + - ``pip3 install -e '.[dev]'`` + * - extras_require['docs'] + - Dependencies required to enable building and enhancing sanic documentation + - ``pip3 install -e '.[docs]'`` + + +Running all tests +----------------- + +To run the tests for Sanic it is recommended to use tox like so: + +.. code-block:: bash + + tox + +See it's that simple! + +``tox.ini`` contains different environments. Running ``tox`` without any arguments will +run all unittests, perform lint and other checks. + +Run unittests +------------- + +``tox`` environment -> ``[testenv]` + +To execute only unittests, run ``tox`` with environment like so: + +.. code-block:: bash + + tox -e py36 -v -- tests/test_config.py + # or + tox -e py37 -v -- tests/test_config.py + +Run lint checks +--------------- + +``tox`` environment -> ``[testenv:lint]`` + +Permform ``flake8``\ , ``black`` and ``isort`` checks. + +.. code-block:: bash + + tox -e lint + +Run other checks +---------------- + +``tox`` environment -> ``[testenv:check]`` + +Perform other checks. + +.. code-block:: bash + + tox -e check + +Run Static Analysis +------------------- + +``tox`` environment -> ``[testenv:security]`` + +Perform static analysis security scan + +.. code-block:: bash + + tox -e security + +Run Documentation sanity check +------------------------------ + +``tox`` environment -> ``[testenv:docs]`` + +Perform sanity check on documentation + +.. code-block:: bash + + tox -e docs + + +Code Style +---------- + +To maintain the code consistency, Sanic uses following tools. + + +#. `isort `_ +#. `black `_ +#. `flake8 `_ + +isort +***** + +``isort`` sorts Python imports. It divides imports into three +categories sorted each in alphabetical order. + + +#. built-in +#. third-party +#. project-specific + +black +***** + +``black`` is a Python code formatter. + +flake8 +****** + +``flake8`` is a Python style guide that wraps following tools into one. + + +#. PyFlakes +#. pycodestyle +#. Ned Batchelder's McCabe script + +``isort``\ , ``black`` and ``flake8`` checks are performed during ``tox`` lint checks. + +Refer `tox `_ documentation for more details. + +Pull requests +------------- + +So the pull request approval rules are pretty simple: + +#. All pull requests must have a changelog details associated with it. +#. All pull requests must pass unit tests. +#. All pull requests must be reviewed and approved by at least one current collaborator on the project. +#. All pull requests must pass flake8 checks. +#. All pull requests must be consistent with the existing code. +#. If you decide to remove/change anything from any common interface a deprecation message should accompany it. +#. If you implement a new feature you should have at least one unit test to accompany it. +#. An example must be one of the following: + + * Example of how to use Sanic + * Example of how to use Sanic extensions + * Example of how to use Sanic and asynchronous library + + +Changelog +--------- + +It is mandatory to add documentation for Change log as part of your Pull request when you fix/contribute something +to the ``sanic`` community. This will enable us in generating better and well defined change logs during the +release which can aid community users in a great way. + +.. note:: + + Single line explaining the details of the PR in brief + + Detailed description of what the PR is about and what changes or enhancements are being done. + No need to include examples or any other details here. But it is important that you provide + enough context here to let user understand what this change is all about and why it is being + introduced into the ``sanic`` codebase. + + Make sure you leave an line space after the first line to make sure the document rendering is clean + + +.. list-table:: + :header-rows: 1 + + * - Contribution Type + - Changelog file name format + - Changelog file location + * - Features + - .feature.rst + - ``changelogs`` + * - Bugfixes + - .bugfix.rst + - ``changelogs`` + * - Improved Documentation + - .doc.rst + - ``changelogs`` + * - Deprecations and Removals + - .removal.rst + - ``changelogs`` + * - Miscellaneous internal changes + - .misc.rst + - ``changelogs`` + + +Documentation +------------- + +Sanic's documentation is built +using `sphinx `_. 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: + +.. code-block:: bash + + sphinx-apidoc -fo docs/_api/ sanic + sphinx-build -b html docs docs/_build + + # There is a simple make command provided to ease the work required in generating + # the documentation + make docs + +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. diff --git a/README.rst b/README.rst index c7d22cbc..e3d65138 100644 --- a/README.rst +++ b/README.rst @@ -142,4 +142,4 @@ Questions and Discussion Contribution ------------ -We are always happy to have new contributions. We have `marked issues good for anyone looking to get started `_, and welcome `questions on the forums `_. Please take a look at our `Contribution guidelines `_. +We are always happy to have new contributions. We have `marked issues good for anyone looking to get started `_, and welcome `questions on the forums `_. Please take a look at our `Contribution guidelines `_. diff --git a/changelogs/1631.doc.rst b/changelogs/1631.doc.rst new file mode 100644 index 00000000..03ffaedd --- /dev/null +++ b/changelogs/1631.doc.rst @@ -0,0 +1,6 @@ +Documentation infrastructure changes + +- Enable having a single common `CHANGELOG` file for both GitHub page and documentation +- Fix Sphinix deprecation warnings +- Fix documentation warnings due to invalid `rst` indentation +- Enable common contribution guidelines file across GitHub and documentation via `CONTRIBUTING.rst` \ No newline at end of file diff --git a/docs/sanic/contributing.rst b/docs/sanic/contributing.rst index a7001b5c..ac7b6bcf 100644 --- a/docs/sanic/contributing.rst +++ b/docs/sanic/contributing.rst @@ -1,93 +1 @@ -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. - -Installation ------------- - -To develop on sanic (and mainly to just run the tests) it is highly -recommend to install from sources. - -So assume you have already cloned the repo and are in the working -directory with a virtual environment already set up, then run: - -.. code:: bash - - pip3 install -e '.[dev]' - -Dependency Changes ------------------- - -``Sanic`` doesn't use ``requirements*.txt`` files to manage any kind of dependencies related to it in order to simplify the -effort required in managing the dependencies. Please make sure you have read and understood the following section of -the document that explains the way ``sanic`` manages dependencies inside the ``setup.py`` file. - -+------------------------+-----------------------------------------------+--------------------------------+ -| Dependency Type | Usage | Installation | -+========================+===============================================+================================+ -| requirements | Bare minimum dependencies required for sanic | ``pip3 install -e .`` | -| | to function | | -+------------------------+-----------------------------------------------+--------------------------------+ -| tests_require / | Dependencies required to run the Unit Tests | ``pip3 install -e '.[test]'`` | -| extras_require['test'] | for ``sanic`` | | -+------------------------+-----------------------------------------------+--------------------------------+ -| extras_require['dev'] | Additional Development requirements to add | ``pip3 install -e '.[dev]'`` | -| | for contributing | | -+------------------------+-----------------------------------------------+--------------------------------+ -| extras_require['docs'] | Dependencies required to enable building and | ``pip3 install -e '.[docs]'`` | -| | enhancing sanic documentation | | -+------------------------+-----------------------------------------------+--------------------------------+ -| extras_require['all'] | Dependencies required to perform all sanic | ``pip3 install -e '.[docs]'`` | -| | development activities including documenting | | -+------------------------+-----------------------------------------------+--------------------------------+ - - -Running tests -------------- - -To run the tests for sanic it is recommended to use tox like so: - -.. code:: bash - - tox - -See it’s that simple! - -Pull requests! --------------- - -So the pull request approval rules are pretty simple: - -* All pull requests must pass unit tests -* All pull requests must be reviewed and approved by at least one current collaborator on the project -* All pull requests must pass flake8 checks -* If you decide to remove/change anything from any common interface a deprecation message should accompany it. -* If you implement a new feature you should have at least one unit test to accompany it. - -Documentation -------------- - -Sanic’s documentation is built using `sphinx`_. 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: - -.. code:: 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. - -.. _sphinx: http://www.sphinx-doc.org/en/1.5.1/ \ No newline at end of file +.. include:: ../../CONTRIBUTING.rst