diff --git a/CONTRIBUTING.md b/CONTRIBUTING.rst similarity index 99% rename from CONTRIBUTING.md rename to CONTRIBUTING.rst index 14a271ea..d9da2334 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.rst @@ -1,55 +1,56 @@ All functionality should be available in pure Python. Optional C implementations may be written for performance reasons, but should never replace the Python implementation. The C implementations should follow the kernel/git coding style. Where possible include updates to NEWS along with your improvements. New functionality and bug fixes should be accompanied by matching unit tests. Coding style ------------ Where possible, please follow PEP8 with regard to coding style. Furthermore, triple-quotes should always be """, single quotes are ' unless using " would result in less escaping within the string. Public methods, functions and classes should all have doc strings. Please use epydoc style docstrings to document parameters and return values. You can generate the documentation by running "make doc". Running the tests ----------------- To run the testsuite, you should be able to simply run "make check". This will run the tests using unittest. - $ make check +:: + $ make check Tox configuration is also present as well as a Travis configuration file. String Types ------------ Like Linux, Git treats filenames as arbitrary bytestrings. There is no prescribed encoding for these strings, and although it is fairly common to use UTF-8, any raw byte strings are supported. For this reason, Dulwich internally treats git-based filenames as bytestrings. It is up to the Dulwich API user to encode and decode them if necessary. In the future, the porcelain may accept unicode strings and convert them to bytestrings as necessary on the fly (using sys.getfilesystemencoding()). * git-repository related filenames: bytes * object sha1 digests (20 bytes long): bytes * object sha1 hexdigests (40 bytes long): str (bytestrings on python2, strings on python3) Merge requests -------------- Please either send pull requests to the maintainer (jelmer@jelmer.uk) or create new pull requests on GitHub. Licensing --------- All contributions should be made under the same license that Dulwich itself comes under: both Apache License, version 2.0 or later and GNU General Public License, version 2.0 or later. diff --git a/README.md b/README.rst similarity index 75% rename from README.md rename to README.rst index 8b99b8ec..73695898 100644 --- a/README.md +++ b/README.rst @@ -1,94 +1,94 @@ [![Build Status](https://travis-ci.org/dulwich/dulwich.png?branch=master)](https://travis-ci.org/dulwich/dulwich) [![Windows Build status](https://ci.appveyor.com/api/projects/status/mob7g4vnrfvvoweb?svg=true)](https://ci.appveyor.com/project/jelmer/dulwich/branch/master) This is the Dulwich project. It aims to provide an interface to git repos (both local and remote) that doesn't call out to git directly but instead uses pure Python. -**Main website**: [www.dulwich.io](https://www.dulwich.io/) +**Main website**: **License**: Apache License, version 2 or GNU General Public License, version 2 or later. The project is named after the part of London that Mr. and Mrs. Git live in in the particular Monty Python sketch. Installation ------------ By default, Dulwich' setup.py will attempt to build and install the optional C extensions. The reason for this is that they significantly improve the performance since some low-level operations that are executed often are much slower in CPython. If you don't want to install the C bindings, specify the --pure argument to setup.py:: $ python setup.py --pure install or if you are installing from pip:: $ pip install dulwich --global-option="--pure" Note that you can also specify --global-option in a -[requirements.txt](https://pip.pypa.io/en/stable/reference/pip_install/#requirement-specifiers) +`requirements.txt `_ file, e.g. like this:: dulwich --global-option=--pure Getting started --------------- Dulwich comes with both a lower-level API and higher-level plumbing ("porcelain"). For example, to use the lower level API to access the commit message of the -last commit: +last commit:: >>> from dulwich.repo import Repo >>> r = Repo('.') >>> r.head() '57fbe010446356833a6ad1600059d80b1e731e15' >>> c = r[r.head()] >>> c >>> c.message 'Add note about encoding.\n' -And to print it using porcelain: +And to print it using porcelain:: >>> from dulwich import porcelain >>> porcelain.log('.', max_entries=1) -------------------------------------------------- commit: 57fbe010446356833a6ad1600059d80b1e731e15 Author: Jelmer Vernooij Date: Sat Apr 29 2017 23:57:34 +0000 Add note about encoding. Further documentation --------------------- The dulwich documentation can be found in docs/ and -[on the web](https://www.dulwich.io/docs/). +`on the web `_. The API reference can be generated using pydoctor, by running "make pydoctor", -or [on the web](https://www.dulwich.io/apidocs). +or `on the web `_. Help ---- -There is a *#dulwich* IRC channel on the [Freenode](https://www.freenode.net/), and -[dulwich-announce](https://groups.google.com/forum/#!forum/dulwich-announce) -and [dulwich-discuss](https://groups.google.com/forum/#!forum/dulwich-discuss) +There is a *#dulwich* IRC channel on the `Freenode `_, and +`dulwich-announce `_ +and `dulwich-discuss `_ mailing lists. Contributing ------------ -For a full list of contributors, see the git logs or [AUTHORS](AUTHORS). +For a full list of contributors, see the git logs or `AUTHORS `_. -If you'd like to contribute to Dulwich, see the [CONTRIBUTING](CONTRIBUTING.md) -file and [list of open issues](https://github.com/dulwich/dulwich/issues). +If you'd like to contribute to Dulwich, see the `CONTRIBUTING `_ +file and `list of open issues `_. Supported versions of Python ---------------------------- At the moment, Dulwich supports (and is tested on) CPython 2.7, 3.4, 3.5, 3.6 and Pypy.