From 0d9bb14f40c7903aac5be58ff40aa1f813876ead Mon Sep 17 00:00:00 2001 From: Richard Wall Date: Tue, 1 Oct 2013 16:17:24 +0100 Subject: some narrative documentation explaining how to set up a development environment --- docs/contributing.rst | 81 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) (limited to 'docs') diff --git a/docs/contributing.rst b/docs/contributing.rst index b4c72ba4..4f089fed 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -73,8 +73,89 @@ So, specifically: - No blank line at the end. - Use Sphinx parameter/attribute documentation `syntax`_. +Development +----------- + +Working on ``cryptography`` requires the installation of a small number of +development dependencies. +The list of development dependencies can be found in ``requirements-dev.txt``. +We recommend that you install these using ``virtualenv`` and ``pip``. +The following example shows how to create a ``cryptography`` development +environment on Linux: + +.. code-block:: sh + + cd ~/projects + git clone git@github.com:/cryptography.git + cd cryptography + mkdir -p ~/.virtualenvs/cryptography + virtualenv --no-site-packages ~/.virtualenvs/cryptography + source ~/.virtualenvs/cryptography/bin/activate + pip install -r requirements-dev.txt + pip install -e . + +You are now ready to run the tests and build the documentation. +Those steps are described in the next sections. + +Testing +------- + +``cryptography`` unit tests are found in the ``tests`` directory. +They are designed to be run using `pytest`_ as follows + +.. code-block:: sh + + py.test tests + ... + 4294 passed in 15.24 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. +Here is an example: + +.. code-block:: sh + + tox -l + ... + py33 + + tox -e py33 + ... + py33: commands succeeded + congratulations :) + +``tox`` can also be used to build the ``cryptography`` documentation. +That is described in the next section. + +Building Documentation +---------------------- + +``cryptography`` documentation is stored in the ``docs`` directory. +It is written in ``ReST`` and built using ``sphinx``. + +The simplest way to build the documentation is to use ``tox``. +The following example shows how to build the documentation using ``tox``: + +.. code-block:: sh + + tox -e doc + ... + py33: commands succeeded + congratulations :) + +The HTML documentation can now be found in the ``docs/_build/html`` +sub-directory. + +.. code-block:: sh + + firefox docs/_build/html/index.html + .. _`GitHub`: https://github.com/alex/cryptography .. _`our mailing list`: https://mail.python.org/mailman/listinfo/cryptography-dev .. _`PEP 8`: http://www.peps.io/8/ .. _`syntax`: http://sphinx-doc.org/domains.html#info-field-lists +.. _`pytest`: http://pytest.org -- cgit v1.2.3 From c3d1eb5eda5bb18109c7a401b062730489be2367 Mon Sep 17 00:00:00 2001 From: Richard Wall Date: Tue, 1 Oct 2013 16:29:07 +0100 Subject: add some more links --- docs/contributing.rst | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) (limited to 'docs') diff --git a/docs/contributing.rst b/docs/contributing.rst index 4f089fed..a77ed849 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -79,7 +79,7 @@ Development Working on ``cryptography`` requires the installation of a small number of development dependencies. The list of development dependencies can be found in ``requirements-dev.txt``. -We recommend that you install these using ``virtualenv`` and ``pip``. +We recommend that you install these using `virtualenv`_ and `pip`_. The following example shows how to create a ``cryptography`` development environment on Linux: @@ -112,7 +112,7 @@ They are designed to be run using `pytest`_ as follows 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 +For this we use `tox`_, which will automatically create a `virtualenv`_ for each supported Python version and run the tests. Here is an example: @@ -127,23 +127,23 @@ Here is an example: py33: commands succeeded congratulations :) -``tox`` can also be used to build the ``cryptography`` documentation. +`tox`_ can also be used to build the ``cryptography`` documentation. That is described in the next section. Building Documentation ---------------------- ``cryptography`` documentation is stored in the ``docs`` directory. -It is written in ``ReST`` and built using ``sphinx``. +It is written in `ReST`_ and built using `sphinx`_. -The simplest way to build the documentation is to use ``tox``. -The following example shows how to build the documentation using ``tox``: +The simplest way to build the documentation is to use `tox`_. +The following example demonstrates how: .. code-block:: sh tox -e doc ... - py33: commands succeeded + docs: commands succeeded congratulations :) The HTML documentation can now be found in the ``docs/_build/html`` @@ -158,4 +158,9 @@ sub-directory. .. _`our mailing list`: https://mail.python.org/mailman/listinfo/cryptography-dev .. _`PEP 8`: http://www.peps.io/8/ .. _`syntax`: http://sphinx-doc.org/domains.html#info-field-lists -.. _`pytest`: http://pytest.org +.. _`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 +.. _`ReST`: http://docutils.sourceforge.net/rst.html -- cgit v1.2.3 From 40cde82b2e3e4f791f9d7d931b8c926da1eaca07 Mon Sep 17 00:00:00 2001 From: Richard Wall Date: Tue, 1 Oct 2013 20:20:15 +0100 Subject: Address review comments. Better headings. More documentation build options --- docs/contributing.rst | 97 +++++++++++++++++++++++++++++++-------------------- 1 file changed, 60 insertions(+), 37 deletions(-) (limited to 'docs') diff --git a/docs/contributing.rst b/docs/contributing.rst index a77ed849..0f5cdfac 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -73,39 +73,34 @@ So, specifically: - No blank line at the end. - Use Sphinx parameter/attribute documentation `syntax`_. -Development ------------ +Development Environment +----------------------- Working on ``cryptography`` requires the installation of a small number of development dependencies. -The list of development dependencies can be found in ``requirements-dev.txt``. -We recommend that you install these using `virtualenv`_ and `pip`_. -The following example shows how to create a ``cryptography`` development -environment on Linux: +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:: sh - cd ~/projects - git clone git@github.com:/cryptography.git - cd cryptography - mkdir -p ~/.virtualenvs/cryptography - virtualenv --no-site-packages ~/.virtualenvs/cryptography - source ~/.virtualenvs/cryptography/bin/activate - pip install -r requirements-dev.txt - pip install -e . + # 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. -Those steps are described in the next sections. -Testing -------- +Running Tests +------------- -``cryptography`` unit tests are found in the ``tests`` directory. -They are designed to be run using `pytest`_ as follows +``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:: sh - py.test tests + py.test ... 4294 passed in 15.24 seconds @@ -113,31 +108,30 @@ 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. -Here is an example: +each supported Python version and run the tests. For example: .. code-block:: sh - tox -l + tox ... - py33 - - tox -e py33 - ... - py33: commands succeeded - congratulations :) + 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`_ can also be used to build the ``cryptography`` documentation. -That is described in the next section. +You may not have all the required Python versions installed, +in which case you will see one or more ``InterpreterNotFound`` errors. Building Documentation ---------------------- -``cryptography`` documentation is stored in the ``docs`` directory. -It is written in `ReST`_ and built using `sphinx`_. +``cryptography`` documentation is stored in the ``docs/`` directory. +It is written in `Restructured Text`_ and rendered using `sphinx`_. -The simplest way to build the documentation is to use `tox`_. -The following example demonstrates how: +The simplest way to build the documentation is to use `tox`_. For example: .. code-block:: sh @@ -146,13 +140,42 @@ The following example demonstrates how: docs: commands succeeded congratulations :) -The HTML documentation can now be found in the ``docs/_build/html`` +The HTML documentation can now be found in the ``docs/_build/html/`` sub-directory. .. code-block:: sh firefox docs/_build/html/index.html +You can also build non-HTML documentation and run various documentation tests +by running ``make`` in the ``docs/`` directory. +Just type ``make`` to see the available options: + +.. code-block:: sh + + make + ... + Please use `make ' where is one of + html to make standalone HTML files + dirhtml to make HTML files named index.html in directories + singlehtml to make a single large HTML file + pickle to make pickle files + json to make JSON files + htmlhelp to make HTML files and a HTML help project + qthelp to make HTML files and a qthelp project + devhelp to make HTML files and a Devhelp project + epub to make an epub + latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter + latexpdf to make LaTeX files and run them through pdflatex + text to make text files + man to make manual pages + texinfo to make Texinfo files + info to make Texinfo files and run them through makeinfo + gettext to make PO message catalogs + changes to make an overview of all changed/added/deprecated items + linkcheck to check all external links for integrity + doctest to run all doctests embedded in the documentation (if enabled) + .. _`GitHub`: https://github.com/alex/cryptography .. _`our mailing list`: https://mail.python.org/mailman/listinfo/cryptography-dev @@ -163,4 +186,4 @@ sub-directory. .. _`virtualenv`: https://pypi.python.org/pypi/virtualenv .. _`pip`: https://pypi.python.org/pypi/pip .. _`sphinx`: https://pypi.python.org/pypi/sphinx -.. _`ReST`: http://docutils.sourceforge.net/rst.html +.. _`Restructured Text`: http://docutils.sourceforge.net/rst.html -- cgit v1.2.3 From 7d4ca1efc4a353023613aa20a2ddfd657939f31b Mon Sep 17 00:00:00 2001 From: Richard Wall Date: Tue, 1 Oct 2013 21:10:45 +0100 Subject: address dreids review comments --- docs/contributing.rst | 48 +++++++----------------------------------------- 1 file changed, 7 insertions(+), 41 deletions(-) (limited to 'docs') diff --git a/docs/contributing.rst b/docs/contributing.rst index 0f5cdfac..8007e6b6 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -86,8 +86,8 @@ install ``cryptography`` in ``editable`` mode. For example: .. code-block:: sh # Create a virtualenv and activate it - pip install --requirement dev-requirements.txt - pip install --editable . + $ pip install --requirement dev-requirements.txt + $ pip install --editable . You are now ready to run the tests and build the documentation. @@ -100,7 +100,7 @@ and are designed to be run using `pytest`_. .. code-block:: sh - py.test + $ py.test ... 4294 passed in 15.24 seconds @@ -112,7 +112,7 @@ each supported Python version and run the tests. For example: .. code-block:: sh - tox + $ tox ... ERROR: py26: InterpreterNotFound: python2.6 py27: commands succeeded @@ -131,50 +131,16 @@ Building Documentation ``cryptography`` documentation is stored in the ``docs/`` directory. It is written in `Restructured Text`_ and rendered using `sphinx`_. -The simplest way to build the documentation is to use `tox`_. For example: +Use `tox`_ to build the documentation. For example: .. code-block:: sh - tox -e doc + $ tox -e docs ... docs: commands succeeded congratulations :) -The HTML documentation can now be found in the ``docs/_build/html/`` -sub-directory. - -.. code-block:: sh - - firefox docs/_build/html/index.html - -You can also build non-HTML documentation and run various documentation tests -by running ``make`` in the ``docs/`` directory. -Just type ``make`` to see the available options: - -.. code-block:: sh - - make - ... - Please use `make ' where is one of - html to make standalone HTML files - dirhtml to make HTML files named index.html in directories - singlehtml to make a single large HTML file - pickle to make pickle files - json to make JSON files - htmlhelp to make HTML files and a HTML help project - qthelp to make HTML files and a qthelp project - devhelp to make HTML files and a Devhelp project - epub to make an epub - latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter - latexpdf to make LaTeX files and run them through pdflatex - text to make text files - man to make manual pages - texinfo to make Texinfo files - info to make Texinfo files and run them through makeinfo - gettext to make PO message catalogs - changes to make an overview of all changed/added/deprecated items - linkcheck to check all external links for integrity - doctest to run all doctests embedded in the documentation (if enabled) +The HTML documentation index can now be found at ``docs/_build/html/index.html`` .. _`GitHub`: https://github.com/alex/cryptography -- cgit v1.2.3 From 166cbd3947cd4416fe7b48f1525853563cd1125f Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Tue, 1 Oct 2013 13:30:29 -0700 Subject: Reflow some paragraphs in the contributing docs --- docs/contributing.rst | 24 +++++++++++------------- 1 file changed, 11 insertions(+), 13 deletions(-) (limited to 'docs') diff --git a/docs/contributing.rst b/docs/contributing.rst index 8007e6b6..9dd14c23 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -77,11 +77,9 @@ Development Environment ----------------------- 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: +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:: sh @@ -94,9 +92,9 @@ 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: +``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:: sh @@ -122,14 +120,14 @@ each supported Python version and run the tests. For example: 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. +You may not have all the required Python versions installed, in which case you +will see one or more ``InterpreterNotFound`` errors. Building Documentation ---------------------- -``cryptography`` documentation is stored in the ``docs/`` directory. -It is written in `Restructured Text`_ and rendered using `sphinx`_. +``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: @@ -152,4 +150,4 @@ The HTML documentation index can now be found at ``docs/_build/html/index.html`` .. _`virtualenv`: https://pypi.python.org/pypi/virtualenv .. _`pip`: https://pypi.python.org/pypi/pip .. _`sphinx`: https://pypi.python.org/pypi/sphinx -.. _`Restructured Text`: http://docutils.sourceforge.net/rst.html +.. _`reStructured Text`: http://docutils.sourceforge.net/rst.html -- cgit v1.2.3