diff options
Diffstat (limited to 'docs/development.rst')
| -rw-r--r-- | docs/development.rst | 87 |
1 files changed, 56 insertions, 31 deletions
diff --git a/docs/development.rst b/docs/development.rst index 3ab05d5..5dcd920 100644 --- a/docs/development.rst +++ b/docs/development.rst @@ -43,10 +43,11 @@ control machine. The repository is publicly accessible. - ``git clone git://github.com/kennethreitz/tablib.git`` +.. code-block:: console -The project is hosted on **GitHub**. + git clone git://github.com/kennethreitz/tablib.git +The project is hosted on **GitHub**. GitHub: http://github.com/kennethreitz/tablib @@ -55,10 +56,9 @@ The project is hosted on **GitHub**. Git Branch Structure ++++++++++++++++++++ -Feature / Hotfix / Release branches follow a `Successful Git Branching Model`_ . Git-flow_ is a great tool for managing the repository. I highly recommend it. +Feature / Hotfix / Release branches follow a `Successful Git Branching Model`_ . +Git-flow_ is a great tool for managing the repository. I highly recommend it. -``develop`` - The "next release" branch. Likely unstable. ``master`` Current production release (|version|) on PyPi. @@ -86,11 +86,14 @@ Tablib welcomes new format additions! Format suggestions include: Coding by Convention ++++++++++++++++++++ -Tablib features a micro-framework for adding format support. The easiest way to understand it is to use it. So, let's define our own format, named *xxx*. +Tablib features a micro-framework for adding format support. +The easiest way to understand it is to use it. +So, let's define our own format, named *xxx*. 1. Write a new format interface. - :class:`tablib.core` follows a simple pattern for automatically utilizing your format throughout Tablib. Function names are crucial. + :class:`tablib.core` follows a simple pattern for automatically utilizing your format throughout Tablib. + Function names are crucial. Example **tablib/formats/_xxx.py**: :: @@ -116,17 +119,18 @@ Tablib features a micro-framework for adding format support. The easiest way to ... # returns True if given stream is parsable as xxx -.. admonition:: Excluding Support - + .. admonition:: Excluding Support - If the format excludes support for an import/export mechanism (*eg.* :class:`csv <tablib.Dataset.csv>` excludes :class:`Databook <tablib.Databook>` support), simply don't define the respective functions. Appropriate errors will be raised. + If the format excludes support for an import/export mechanism (*e.g.* + :class:`csv <tablib.Dataset.csv>` excludes + :class:`Databook <tablib.Databook>` support), + simply don't define the respective functions. + Appropriate errors will be raised. -2. +2. Add your new format module to the :class:`tablib.formats.available` tuple. - Add your new format module to the :class:`tablib.formats.available` tuple. - -3. - Add a mock property to the :class:`Dataset <tablib.Dataset>` class with verbose `reStructured Text`_ docstring. This alleviates IDE confusion, and allows for pretty auto-generated Sphinx_ documentation. +3. Add a mock property to the :class:`Dataset <tablib.Dataset>` class with verbose `reStructured Text`_ docstring. + This alleviates IDE confusion, and allows for pretty auto-generated Sphinx_ documentation. 4. Write respective :ref:`tests <testing>`. @@ -136,22 +140,33 @@ Tablib features a micro-framework for adding format support. The easiest way to Testing Tablib -------------- -Testing is crucial to Tablib's stability. This stable project is used in production by many companies and developers, so it is important to be certain that every version released is fully operational. When developing a new feature for Tablib, be sure to write proper tests for it as well. +Testing is crucial to Tablib's stability. +This stable project is used in production by many companies and developers, +so it is important to be certain that every version released is fully operational. +When developing a new feature for Tablib, be sure to write proper tests for it as well. + +When developing a feature for Tablib, +the easiest way to test your changes for potential issues is to simply run the test suite directly. -When developing a feature for Tablib, the easiest way to test your changes for potential issues is to simply run the test suite directly. :: +.. code-block:: console - $ ./test_tablib.py + $ ./test_tablib.py -`Jenkins CI`_, amongst other tools, supports Java's xUnit testing report format. Nose_ allows us to generate our own xUnit reports. +`Jenkins CI`_, amongst other tools, supports Java's xUnit testing report format. +Nose_ allows us to generate our own xUnit reports. -Installing nose is simple. :: +Installing nose is simple. - $ pip install nose +.. code-block:: console -Once installed, we can generate our xUnit report with a single command. :: + $ pip install nose - $ nosetests test_tablib.py --with-xunit +Once installed, we can generate our xUnit report with a single command. + +.. code-block:: console + + $ nosetests test_tablib.py --with-xunit This will generate a **nosetests.xml** file, which can then be analyzed. @@ -165,7 +180,9 @@ This will generate a **nosetests.xml** file, which can then be analyzed. Continuous Integration ---------------------- -Every commit made to the **develop** branch is automatically tested and inspected upon receipt with `Travis CI`_. If you have access to the main repository and broke the build, you will receive an email accordingly. +Every commit made to the **develop** branch is automatically tested and inspected upon receipt with `Travis CI`_. +If you have access to the main repository and broke the build, +you will receive an email accordingly. Anyone may view the build status and history at any time. @@ -182,19 +199,27 @@ Additional reports will also be included here in the future, including :pep:`8` Building the Docs ----------------- -Documentation is written in the powerful, flexible, and standard Python documentation format, `reStructured Text`_. -Documentation builds are powered by the powerful Pocoo project, Sphinx_. The :ref:`API Documentation <api>` is mostly documented inline throughout the module. +Documentation is written in the powerful, flexible, +and standard Python documentation format, `reStructured Text`_. +Documentation builds are powered by the powerful Pocoo project, Sphinx_. +The :ref:`API Documentation <api>` is mostly documented inline throughout the module. + +The Docs live in ``tablib/docs``. +In order to build them, you will first need to install Sphinx. + +.. code-block:: console -The Docs live in ``tablib/docs``. In order to build them, you will first need to install Sphinx. :: + $ pip install sphinx - $ pip install sphinx +Then, to build an HTML version of the docs, simply run the following from the ``docs`` directory: -Then, to build an HTML version of the docs, simply run the following from the **docs** directory: :: +.. code-block:: console - $ make html + $ make html -Your ``docs/_build/html`` directory will then contain an HTML representation of the documentation, ready for publication on most web servers. +Your ``docs/_build/html`` directory will then contain an HTML representation of the documentation, +ready for publication on most web servers. You can also generate the documentation in **epub**, **latex**, **json**, *&c* similarly. |