From 0839aa858f41f71b292c387f6bc3641083b965bc Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Tue, 11 Feb 2014 22:36:51 -0600 Subject: reorganize contributing into development section --- docs/development/getting-started.rst | 84 ++++++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 docs/development/getting-started.rst (limited to 'docs/development/getting-started.rst') diff --git a/docs/development/getting-started.rst b/docs/development/getting-started.rst new file mode 100644 index 00000000..b367119e --- /dev/null +++ b/docs/development/getting-started.rst @@ -0,0 +1,84 @@ +Getting Started +=============== + +Working on ``cryptography`` requires the installation of a small number of +development dependencies. These are listed in ``dev-requirements.txt`` and they +can be installed in a `virtualenv`_ using `pip`_. Once you've installed the +dependencies, install ``cryptography`` in ``editable`` mode. For example: + +.. code-block:: console + + $ # Create a virtualenv and activate it + $ pip install --requirement dev-requirements.txt + $ pip install --editable . + +You are now ready to run the tests and build the documentation. + +Running Tests +~~~~~~~~~~~~~ + +``cryptography`` unit tests are found in the ``tests/`` directory and are +designed to be run using `pytest`_. `pytest`_ will discover the tests +automatically, so all you have to do is: + +.. code-block:: console + + $ py.test + ... + 62746 passed in 220.43 seconds + +This runs the tests with the default Python interpreter. + +You can also verify that the tests pass on other supported Python interpreters. +For this we use `tox`_, which will automatically create a `virtualenv`_ for +each supported Python version and run the tests. For example: + +.. code-block:: console + + $ tox + ... + ERROR: py26: InterpreterNotFound: python2.6 + py27: commands succeeded + ERROR: pypy: InterpreterNotFound: pypy + ERROR: py32: InterpreterNotFound: python3.2 + py33: commands succeeded + docs: commands succeeded + pep8: commands succeeded + +You may not have all the required Python versions installed, in which case you +will see one or more ``InterpreterNotFound`` errors. + + +Explicit Backend Selection +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +While testing you may want to run tests against a subset of the backends that +cryptography supports. Explicit backend selection can be done via the +``--backend`` flag. This flag should be passed to ``py.test`` with a comma +delimited list of backend names. To use it with ``tox`` you must pass it as +``tox -- --backend=openssl``. + +Building Documentation +~~~~~~~~~~~~~~~~~~~~~~ + +``cryptography`` documentation is stored in the ``docs/`` directory. It is +written in `reStructured Text`_ and rendered using `Sphinx`_. + +Use `tox`_ to build the documentation. For example: + +.. code-block:: console + + $ tox -e docs + ... + docs: commands succeeded + congratulations :) + +The HTML documentation index can now be found at +``docs/_build/html/index.html``. + +.. _`pytest`: https://pypi.python.org/pypi/pytest +.. _`tox`: https://pypi.python.org/pypi/tox +.. _`virtualenv`: https://pypi.python.org/pypi/virtualenv +.. _`pip`: https://pypi.python.org/pypi/pip +.. _`sphinx`: https://pypi.python.org/pypi/Sphinx +.. _`reStructured Text`: http://sphinx-doc.org/rest.html -- cgit v1.2.3 From 450cd0252b4e8e53d574b18a5ad274c2ac32cca6 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Tue, 11 Feb 2014 22:46:39 -0600 Subject: fix some indentation and a missing newline --- docs/development/getting-started.rst | 38 ++++++++++++++++++------------------ 1 file changed, 19 insertions(+), 19 deletions(-) (limited to 'docs/development/getting-started.rst') diff --git a/docs/development/getting-started.rst b/docs/development/getting-started.rst index b367119e..d2d13a15 100644 --- a/docs/development/getting-started.rst +++ b/docs/development/getting-started.rst @@ -8,9 +8,9 @@ dependencies, install ``cryptography`` in ``editable`` mode. For example: .. code-block:: console - $ # Create a virtualenv and activate it - $ pip install --requirement dev-requirements.txt - $ pip install --editable . + $ # Create a virtualenv and activate it + $ pip install --requirement dev-requirements.txt + $ pip install --editable . You are now ready to run the tests and build the documentation. @@ -23,9 +23,9 @@ automatically, so all you have to do is: .. code-block:: console - $ py.test - ... - 62746 passed in 220.43 seconds + $ py.test + ... + 62746 passed in 220.43 seconds This runs the tests with the default Python interpreter. @@ -35,15 +35,15 @@ each supported Python version and run the tests. For example: .. code-block:: console - $ tox - ... - ERROR: py26: InterpreterNotFound: python2.6 - py27: commands succeeded - ERROR: pypy: InterpreterNotFound: pypy - ERROR: py32: InterpreterNotFound: python3.2 - py33: commands succeeded - docs: commands succeeded - pep8: commands succeeded + $ tox + ... + ERROR: py26: InterpreterNotFound: python2.6 + py27: commands succeeded + ERROR: pypy: InterpreterNotFound: pypy + ERROR: py32: InterpreterNotFound: python3.2 + py33: commands succeeded + docs: commands succeeded + pep8: commands succeeded You may not have all the required Python versions installed, in which case you will see one or more ``InterpreterNotFound`` errors. @@ -68,10 +68,10 @@ Use `tox`_ to build the documentation. For example: .. code-block:: console - $ tox -e docs - ... - docs: commands succeeded - congratulations :) + $ tox -e docs + ... + docs: commands succeeded + congratulations :) The HTML documentation index can now be found at ``docs/_build/html/index.html``. -- cgit v1.2.3 From 18962cc15b8562e46ea8b6f60fb5072c344d9b12 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Tue, 11 Feb 2014 22:54:40 -0600 Subject: add explicit backend selection examples in a code block --- docs/development/getting-started.rst | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) (limited to 'docs/development/getting-started.rst') diff --git a/docs/development/getting-started.rst b/docs/development/getting-started.rst index d2d13a15..412f0545 100644 --- a/docs/development/getting-started.rst +++ b/docs/development/getting-started.rst @@ -55,8 +55,13 @@ Explicit Backend Selection While testing you may want to run tests against a subset of the backends that cryptography supports. Explicit backend selection can be done via the ``--backend`` flag. This flag should be passed to ``py.test`` with a comma -delimited list of backend names. To use it with ``tox`` you must pass it as -``tox -- --backend=openssl``. +delimited list of backend names. + + +.. code-block:: console + + $ tox -- --backend=openssl + $ py.test --backend=openssl,commoncrypto Building Documentation ~~~~~~~~~~~~~~~~~~~~~~ -- cgit v1.2.3