Tarball conversion

4 files changed, 152 insertions, 0 deletions

diff --git a/bzrlib/doc/__init__.py b/bzrlib/doc/__init__.py
new file mode 100644
index 0000000..7cd43c7
--- /dev/null
+++ b/bzrlib/doc/__init__.py
@@ -0,0 +1,38 @@
+# Copyright (C) 2005 Canonical Ltd
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+
+"""Documentation for bzrlib.
+
+See bzrlib.doc.api for api documentation and in the future bzrlib.doc.man
+for man page generation.
+"""
+
+from __future__ import absolute_import
+
+
+def load_tests(basic_tests, module, loader):
+    suite = loader.suiteClass()
+    # add the tests for this module (obviously none so far)
+    suite.addTests(basic_tests)
+
+    testmod_names = [
+        'bzrlib.doc.api',
+        ]
+
+    # add the tests for the sub modules
+    suite.addTests(loader.loadTestsFromModuleNames(testmod_names))
+
+    return suite
diff --git a/bzrlib/doc/api/__init__.py b/bzrlib/doc/api/__init__.py
new file mode 100644
index 0000000..6a7a9ec
--- /dev/null
+++ b/bzrlib/doc/api/__init__.py
@@ -0,0 +1,53 @@
+# Copyright (C) 2005, 2006 Canonical Ltd
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+
+"""API Documentation for bzrlib.
+
+This documentation is made up of doctest testable examples.
+
+Look for `bzrlib/doc/api/*.txt` to read it.
+
+This documentation documents the current best practice in using the library.
+For details on specific apis, see pydoc on the api, or read the source.
+"""
+
+from __future__ import absolute_import
+
+import doctest
+import os
+
+from bzrlib import tests
+
+def load_tests(basic_tests, module, loader):
+    """This module creates its own test suite with DocFileSuite."""
+
+    dir_ = os.path.dirname(__file__)
+    if os.path.isdir(dir_):
+        candidates = os.listdir(dir_)
+    else:
+        candidates = []
+    scripts = [candidate for candidate in candidates
+               if candidate.endswith('.txt')]
+    # since this module doesn't define tests, we ignore basic_tests
+    suite = doctest.DocFileSuite(*scripts)
+    # DocFileCase reduces the test id to the base name of the tested file, we
+    # want the module to appears there.
+    for t in tests.iter_suite_tests(suite):
+        def make_new_test_id():
+            new_id = '%s.DocFileTest(%s)' % ( __name__, t)
+            return lambda: new_id
+        t.id = make_new_test_id()
+    return suite
diff --git a/bzrlib/doc/api/branch.txt b/bzrlib/doc/api/branch.txt
new file mode 100644
index 0000000..0f6b7d2
--- /dev/null
+++ b/bzrlib/doc/api/branch.txt
@@ -0,0 +1,37 @@
+The Branch API in bzrlib provides creation and management of Branches.
+
+A Branch represents a series of commits and merges carried out by a user.
+
+Make a temporary directory for these tests:
+
+   >>> from bzrlib import osutils
+   >>> test_dir = osutils.mkdtemp(prefix='bzrlib_doc_api_branch_txt_')
+
+Branches are created by BzrDir's:
+
+   >>> from bzrlib.branch import Branch
+   >>> from bzrlib.bzrdir import BzrDir
+
+   >>> new_branch = BzrDir.create_branch_convenience(test_dir)
+
+Existing Branches can be opened directly:
+
+   >>> transport = new_branch.bzrdir.transport
+   >>> another_instance = Branch.open(transport.clone('..').base)
+
+or via the BzrDir:
+
+   >>> still_the_same_branch = new_branch.bzrdir.open_branch()
+
+A branch has a history of revisions on it:
+
+   >>> new_branch.last_revision()
+   'null:'
+
+We need to write some more documentation, showing
+push and pull operations. Cloning might also be nice.
+
+And finally, clean up:
+
+   >>> import shutil
+   >>> shutil.rmtree(test_dir)
diff --git a/bzrlib/doc/api/transport.txt b/bzrlib/doc/api/transport.txt
new file mode 100644
index 0000000..bbca6a1
--- /dev/null
+++ b/bzrlib/doc/api/transport.txt
@@ -0,0 +1,24 @@
+The Transport API in bzrlib provides URL based access to network resources.
+
+   >>> import os
+   >>> import sys
+   >>> from bzrlib.osutils import getcwd, dirname
+   >>> from bzrlib.urlutils import local_path_from_url
+   >>> import bzrlib.transport as transport
+   >>> if sys.platform == 'win32':
+   ...     root = transport.get_transport_from_url('file:///C:/')
+   ... else:
+   ...     root = transport.get_transport_from_url('file:///')
+   >>>
+
+Each Transport instance represents a single logical directory.
+
+   >>> dir = transport.get_transport_from_path(".")
+   >>> local_path_from_url(dir.base) == getcwd() + '/'
+   True
+
+You can change directories via the clone method:
+
+   >>> parent = dir.clone('..')
+   >>> local_path_from_url(parent.base) == (dirname(getcwd()).rstrip('/') + '/')
+   True