diff options
| -rw-r--r-- | docs/api.rst | 11 | ||||
| -rw-r--r-- | docs/development.rst | 127 | ||||
| -rw-r--r-- | docs/index.rst | 4 | ||||
| -rw-r--r-- | docs/install.rst | 13 | ||||
| -rw-r--r-- | docs/intro.rst | 22 | ||||
| -rw-r--r-- | docs/quickstart.rst | 4 | ||||
| -rw-r--r-- | fabfile.py | 6 |
7 files changed, 166 insertions, 21 deletions
diff --git a/docs/api.rst b/docs/api.rst index 28f3f70..ce169b7 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -3,7 +3,7 @@ API === -.. module:: flask +.. module:: tablib This part of the documentation covers all the interfaces of Tablib. For parts where Tablib depends on external libraries, we document the most @@ -12,15 +12,16 @@ important right here and provide links to the canonical documentation. Dataset Object -------------- -.. module:: tablib - .. autoclass:: Dataset - :members: :inherited-members: + Databook Object --------------- .. autoclass:: Databook - :members: :inherited-members: + + + +Now, go start some :ref:`Tablib Development <development>`.
\ No newline at end of file diff --git a/docs/development.rst b/docs/development.rst index 7a574c6..e608ddc 100644 --- a/docs/development.rst +++ b/docs/development.rst @@ -5,14 +5,137 @@ Development Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. - +.. _future: Future of Tablib ---------------- Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. +.. _design: Design Considerations --------------------- -Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
\ No newline at end of file +Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. + + +.. _scm: +Source Control +-------------- + +Git. + + +.. _newformats: +Adding New Formats +------------------ + +Don't. + + +.. _testing: +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 certian that every version released is fully operational. When developing a new feature for Tablib, be sure to write proper tests for it as well. + + +Running the Test Suite +++++++++++++++++++++++ + +When developing a feature for Tablib, the easiest way to test your changes for potential issues is to simply run the test suite directly. :: + + $ ./test_tablib.py + + +`Hudson CI`_, amongst other tools, supports Java's xUnit testing report format. Nose_ allows us to generate our own xUnit reports. + +Installing nose is simple. :: + + $ pip install nose + +Once installed, we can generate our xUnit report with a single command. :: + + $ nosetests test_tablib.py --with-xunit + +This will generate a **nosetests.xml** file, which can then be analyzed. + +.. _Nose: http://somethingaboutorange.com/mrl/projects/nose/ + +Extending the Test Suite +++++++++++++++++++++++++ + +Example: :: + + import tablib.formats.sql.test_sql + + +.. _hudson: +Continuous Integration +---------------------- + +Every commit made to the **develop** branch is automatically tested and inspected upon receipt with `Hudson CI`_. If you have access to the main respository and broke the build, you will receive an email accordingly. + +Anyone may view the build status and history at any time. + + http://git.kennethreitz.com/ci/ + + +If you are trustworthy and plan to contribute to tablib on a regular basis, please contact `Kenneth Reitz`_ to get an account on the Hudson Server. + + +Additional reports will also be included here in the future, including PEP 8 checks and stress reports for extremely large datasets. + +.. _`Hudson CI`: http://hudson.dev.java.net +.. _`Kenneth Reitz`: http://kennethreitz.com/contact-me/ + + +.. _docs: +Building the Docs +----------------- + +Documentation is written in the powerful, flexible, and standard Python documentation format, `reStructured Text`_. +Documentation builds are powered by powerful Pocoo project, Sphinx_. The :ref:`API Documentation <api>` is mostly documented inline throught the module. + +The Docs live in ``tablib/docs``. In order to build them, you will first need to install Sphinx. :: + + $ pip install sphinx + + +Then, to build an HTML version of the docs, simply run the following from the **docs** directory: :: + + $ make html + +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 **ebpub**, **latex**, **json**, *&c* similarly. + +.. admonition:: GitHub Pages + + To push the documentation up to `GitHub Pages`_, you will first need to run `sphinx-to-github`_ against your ``docs/_build/html`` directory. + + GitHub Pages are powered by an HTML generation system called Jeckyl_, which is configured to ignore files and folders that begin with "``_``" (*ie.* **_static**). + + + + + + + and `sphinx-to-github`_. :: + + Installing sphinx-to-github is simple. :: + + $ pip install sphinx-to-github + + Running it against the docs is even simpler. :: + + $ sphinx-to-github _build/html + + Move the resulting files to the **gh-pages** branch of your repository, and push it up to GitHub. + +.. _`reStructured Text`: http://docutils.sourceforge.net/rst.html +.. _Sphinx: http://sphinx.pocoo.org +.. _`GitHub Pages`: http://pages.github.com +.. _Jeckyl: http://github.com/mojombo/jekyll +.. _`sphinx-to-github`: http://github.com/michaeljones/sphinx-to-github + +Make sure to check out the :ref:`API Documentation <api>`.
\ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 75cbbe2..ff757a6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -22,9 +22,9 @@ Welcome to Tablib's docuemtation. .. * :ref:`search` -Tablib is a format-agnostic tabular dataset library, written in Python. It allows you to import, export, and manipulate tabular data sets. +Tablib is a format-agnostic tabular dataset library, written in Python. It allows you to import, export, and manipulate tabular data sets. Oh, and it's :ref:`MIT Lisenced <mit>`. -I recommend you start off with `Installation`. +I recommend you start off with :ref:`Installation <install>`. User's Guide ------------ diff --git a/docs/install.rst b/docs/install.rst index d1cacbf..c8cc48b 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -1,10 +1,11 @@ .. _install: - Installation ============ -This part of the documentation covers the installation of Tablib. The first step to using any software package is getting it properly installed. Please read this section carefully, or you may miss out on some nice :ref:`speed enhancments <speed>`.. +This part of the documentation covers the installation of Tablib. The first step to using any software package is getting it properly installed. Please read this section carefully, or you may miss out on some nice :ref:`speed enhancments <speed>`. + +.. _installing: Installing Tablib ----------------- @@ -18,8 +19,8 @@ Or, if you must: :: But, you really shouldn't do that. -.. _speed: +.. _speed: Speed Extentions ---------------- @@ -37,7 +38,7 @@ If you're using Python 2.5 (currently unsupported), you should also install the - +.. _pythonsupport: Pythons Supported ----------------- @@ -49,7 +50,7 @@ At this time, the following Python platforms are officially supported: Support for other Pythons will be rolled out soon. - +.. _updates: Staying Updated --------------- @@ -62,3 +63,5 @@ When a new version is available, upgrading is simple. :: $ pip install tablib --upgrade + +Now, go get a :ref:`Quick Start <quickstart>`.
\ No newline at end of file diff --git a/docs/intro.rst b/docs/intro.rst index bfa8a3e..b9c5f78 100644 --- a/docs/intro.rst +++ b/docs/intro.rst @@ -7,13 +7,27 @@ This part of the documentation covers all the interfaces of Tablib. For parts where Tablib depends on external libraries, we document the most important right here and provide links to the canonical documentation. + Why Tablib? ----------- -Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. +Why not? + +It Should Be Easy +----------------- + + +.. _mit: +MIT License +----------- + +A large number of open source projects you find today are `GPL Licensed`_. While the GPL certianly has essential applications, it should most certianly not be your go-to license for you next open source project. + +A project that was released as GPL cannot be usd in any commercial product without the product itself also being offered as open source. The MIT and BSD licenses are fantastic alternatives to this *major* problem. +Tablib is released under terms of `The MIT License`_. -Boiler Plate is Bad -------------------- +.. _`GPL Licensed`: http://www.opensource.org/licenses/gpl-license.php +.. _`The MIT License`: http://www.opensource.org/licenses/mit-license.php -Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. +Now, go :ref:`Install Tablib <install>`.
\ No newline at end of file diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 419ac82..1c613a3 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -17,4 +17,6 @@ Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor Advanced Usage -------------- -Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
\ No newline at end of file +Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. + +Now, go check out the :ref:`API Documentation <api>` or begin :ref:`Tablib Development <development>`.
\ No newline at end of file @@ -10,6 +10,8 @@ def scrub(): def docs(): """Build docs.""" os.system('make html') - os.system('cd _build/html') - os.system('git commit -am \'documentation update\'') + os.chdir('_build/html') + os.system('sphinxtogithub .') + os.system('git add -A') + os.system('git commit -m \'documentation update\'') os.system('git push origin gh-pages')
\ No newline at end of file |