Skip to content

Commit c67503f

Browse files
maxtepkeevmaxtepkeev
committed
new documentation [ci skip]
1 parent b594eab commit c67503f

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

51 files changed

+4427
-2579
lines changed

‎CHANGELOG.rst‎

Lines changed: 122 additions & 80 deletions
Large diffs are not rendered by default.

‎LICENSE‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
Copyright 2017 Max Tepkeev
1+
Copyright 2017 Maxim Tepkeev
22

33
Licensed under the Apache License, Version 2.0 (the "License");
44
you may not use this file except in compliance with the License.

‎NOTICE‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
Python Redmine includes code from several Python libraries.
1+
Python-Redmine includes code from several Python libraries.
22

33
Requests License
44
================

‎README.rst‎

Lines changed: 24 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
Python Redmine
1+
Python-Redmine
22
==============
33

44
.. image:: https://badge.fury.io/py/python-redmine.svg
@@ -10,9 +10,9 @@ Python Redmine
1010
.. image:: https://img.shields.io/coveralls/maxtepkeev/python-redmine/master.svg
1111
:target: https://coveralls.io/r/maxtepkeev/python-redmine?branch=master
1212

13-
Python Redmine is a library for communicating with a `Redmine <http://www.redmine.org>`_
13+
Python-Redmine is a library for communicating with a `Redmine <http://www.redmine.org>`_
1414
project management application. Redmine exposes some of it's data via `REST API
15-
<http://www.redmine.org/projects/redmine/wiki/Rest_api>`_ for which Python Redmine provides
15+
<http://www.redmine.org/projects/redmine/wiki/Rest_api>`_ for which Python-Redmine provides
1616
a simple but powerful Pythonic API inspired by a well-known `Django ORM
1717
<https://docs.djangoproject.com/en/dev/topics/db/queries/>`_:
1818

@@ -52,51 +52,49 @@ a simple but powerful Pythonic API inspired by a well-known `Django ORM
5252
Features
5353
--------
5454

55-
* Supports 100% of Redmine API features
55+
* Supports 100% of Redmine API
56+
* Supports external Redmine plugins API
5657
* Supports Python 2.6, 2.7, 3.3 - 3.6, PyPy and PyPy3
58+
* Supports different request engines
59+
* Extendable via custom resources and custom request engines
5760
* Extensively documented
5861
* Provides ORM-style Pythonic API
62+
* And many more...
5963

6064
Installation
6165
------------
6266

63-
To install Python Redmine, simply:
67+
Standard Edition
68+
++++++++++++++++
69+
70+
The recommended way to install is from Python Package Index (PyPI) with `pip <http://www.pip-installer.org>`_:
6471

6572
.. code-block:: bash
6673
6774
$ pip install python-redmine
6875
69-
or:
70-
71-
.. code-block:: bash
76+
Pro Edition
77+
+++++++++++
7278

73-
$ easy_install python-redmine
79+
License for a Pro Edition can be bought
80+
`here <https://secure.avangate.com/order/checkout.php?PRODS=4708754&QTY=1&CART=1&CARD=1&DISABLE_SHORT_FORM_MOBILE=1>`_.
81+
You will receive an email with all the details regarding Pro Edition installation process.
7482

7583
Documentation
7684
-------------
7785

78-
Documentation is available at http://python-redmine.readthedocs.org.
86+
Documentation is available at https://python-redmine.com.
7987

8088
Contacts and Support
8189
--------------------
8290

83-
I will be glad to get your feedback, `pull requests <https://github.com/maxtepkeev/python-redmine/pulls>`_,
84-
`issues <https://github.com/maxtepkeev/python-redmine/issues>`_, whatever. Feel free to contact me for any
85-
questions.
86-
87-
Donations and Sponsorship
88-
-------------------------
89-
90-
If you like this project and want to support it you have 3 options:
91-
92-
#. Just give this project a star at the top of the `GitHub <https://github.com/maxtepkeev/python-redmine>`_
93-
repository. That doesn't cost you anything but makes the `author <https://github.com/maxtepkeev>`_ happier.
94-
#. You can express your gratitude via `Gratipay <https://gratipay.com/maxtepkeev/>`_.
95-
#. Become a sponsor. Contact me via ``tepkeev at gmail dot com`` if you are interested in becoming a sponsor
96-
and we will discuss the terms and conditions.
91+
Support for Standard Edition is provided via `GitHub <https://github.com/maxtepkeev/python-redmine/issues>`_
92+
only, while support for Pro Edition is provided both via `GitHub <https://github.com/maxtepkeev/python-redmine/issues>`_
93+
and [email protected]. Be sure to write from email that was specified during the purchase procedure.
9794

9895
Copyright and License
9996
---------------------
10097

101-
Python Redmine is licensed under Apache 2.0 license. Check the `LICENSE
102-
<https://github.com/maxtepkeev/python-redmine/blob/master/LICENSE>`_ for details.
98+
Python-Redmine Standard Edition is licensed under Apache 2.0 license. Python-Redmine Pro Edition is licensed
99+
under the Python-Redmine Pro Edition 1.0 license. Check the `License <https://python-redmine.com/license.html>`_
100+
for details.

‎docs/_static/css/python-redmine.css‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
div.body p, div.body dd, div.body li, div.body blockquote {
2+
-moz-hyphens: none;
3+
-ms-hyphens: none;
4+
-webkit-hyphens: none;
5+
hyphens: none;
6+
}
7+
8+
a.reference.external.image-reference {
9+
text-decoration: none;
10+
border-bottom: 0;
11+
}
12+
13+
pre {
14+
padding-left: 15px;
15+
}
16+
17+
dl pre, blockquote pre {
18+
margin-left: -30px;
19+
padding-left: 15px;
20+
}
21+
22+
dl dl pre, li pre {
23+
margin-left: 0;
24+
padding-left: 15px;
25+
}
26+
27+
pre, tt {
28+
font-size: 14px;
29+
}
30+
31+
dl.method {
32+
font-size: 16px;
33+
}
34+
35+
.highlight .go {
36+
color: #888888;
37+
}
38+
39+
ol.parent {
40+
margin-top: 17px;
41+
margin-left: 0;
42+
}
43+
44+
ol.parent>li {
45+
margin-bottom: 10px;
46+
}
47+
48+
ol.multinum {
49+
counter-reset: item;
50+
}
51+
52+
ol.multinum.parent {
53+
counter-reset: item;
54+
}
55+
56+
ol.multinum>li {
57+
display: block;
58+
}
59+
60+
ol.multinum>li:before {
61+
content: counters(item, ".") ". ";
62+
counter-increment: item;
63+
}
64+
65+
.feature-matrix {
66+
width: 100%;
67+
margin-bottom: 24px;
68+
}
69+
70+
.feature-matrix td {
71+
background-color: #f3f6f6;
72+
padding: 10px 5px;
73+
border: 1px solid #e1e4e5;
74+
}
75+
76+
.feature-matrix th {
77+
font-weight: normal;
78+
padding: 10px 5px;
79+
border: 1px solid #e1e4e5;
80+
}
81+
82+
.feature-matrix .edition {
83+
background-color: #f3f6f6;
84+
font-weight: bold;
85+
text-align: center;
86+
}
87+
88+
.feature-matrix .invisible-cell {
89+
border: 0;
90+
}
91+
92+
.feature-matrix .group {
93+
padding-left: 10px;
94+
font-weight: bold;
95+
}
96+
97+
.feature-matrix .feature {
98+
padding-left: 10px;
99+
}
100+
101+
.feature-matrix .implemented {
102+
background-color: #e3f6e7;
103+
color: #3d8940;
104+
text-align: center;
105+
}
106+
107+
.feature-matrix .not-implemented {
108+
background-color: #fff0f2;
109+
color: #b02d37;
110+
text-align: center;
111+
}

‎docs/_static/img/logo.png‎

41.7 KB
Loading

‎docs/_templates/searchbox.html‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{%- if pagename != "search" and builder != "singlehtml" %}
2+
<div id="searchbox" style="display: none">
3+
<h3>{{ _('Quick search') }}</h3>
4+
<form class="search" action="{{ pathto('search') }}" method="get">
5+
<input type="text" name="q" style="width: 150px" />
6+
<input type="submit" value="{{ _('Go') }}" />
7+
<input type="hidden" name="check_keywords" value="yes" />
8+
<input type="hidden" name="area" value="default" />
9+
</form>
10+
</div>
11+
<script type="text/javascript">$('#searchbox').show(0);</script>
12+
{%- endif %}

‎docs/advanced/custom_resources.rst‎

Lines changed: 25 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,30 @@
11
Custom Resources
22
================
33

4-
.. versionadded:: 0.5.0
5-
6-
Sometimes there is a need to redefine a resource behaviour to achieve the needed goal. Python
7-
Redmine provides a feature for such a case called custom resources. Basically this is just a
8-
normal class inheritance made especially for Python Redmine.
4+
Sometimes there is a need to redefine a resource behaviour to achieve the needed goal.
5+
Python-Redmine provides a feature for such a case called custom resources. Basically this
6+
is just a normal class inheritance made especially for Python-Redmine.
97

108
Configuration
119
-------------
1210

13-
To take advantage of this feature you need to tell Python Redmine where to search for your
14-
custom resources. This should be done with a ``custom_resource_paths`` argument passed to
11+
To take advantage of this feature you need to tell Python-Redmine where to search for your
12+
custom resources. This should be done with a ``resource_paths`` argument passed to
1513
the Redmine object which accepts a list or tuple of module paths which contain your custom
1614
resources:
1715

1816
.. code-block:: python
1917
20-
redmine = Redmine('https://redmine.url', custom_resource_paths=('foo.bar', 'bar.baz', 'foo.baz'))
18+
redmine = Redmine('https://redmine.url', resource_paths=('foo.bar', 'bar.baz', 'foo.baz'))
2119
2220
.. note::
2321

24-
The ordering is very important. Python Redmine will search for the resources in this order:
22+
The ordering is very important. Python-Redmine will search for the resources in this order:
2523

26-
#. foo.bar
27-
#. bar.baz
28-
#. foo.baz
29-
#. redmine.resources
24+
#. foo.bar
25+
#. bar.baz
26+
#. foo.baz
27+
#. redminelib.resources
3028

3129
Existing Resources
3230
------------------
@@ -36,36 +34,36 @@ The list of existing resource class names that can be inherited from is availabl
3634
Creation
3735
--------
3836

39-
To create a custom resource choose which resource behavior you want to change, e.g. Project:
37+
To create a custom resource choose which resource behavior you want to change, e.g. WikiPage:
4038

4139
.. code-block:: python
4240
43-
from redminelib.resources import Project
41+
from redminelib.resources import WikiPage
4442
45-
class CustomProject(Project):
46-
pass
43+
class CustomWikiPage(WikiPage):
44+
pass
4745
4846
Name
4947
----
5048

51-
Python Redmine converts underscore to camelcase when it tries to import the resource, that means
49+
Python-Redmine converts underscore to camelcase when it tries to import the resource, which means
5250
that it is important to follow this convention to make everything work properly, e.g when you do:
5351

5452
.. code-block:: python
5553
56-
custom_wiki_page = redmine.custom_wiki_page.get('Foo')
54+
custom_wiki_page = redmine.custom_wiki_page.get('Foo')
5755
58-
Python Redmine is searching for a resource class named CustomWikiPage in the modules defined via
59-
the ``custom_resource_paths`` argument on Redmine object instantiation.
56+
Python-Redmine is searching for a resource class named CustomWikiPage in the modules defined via
57+
the ``resource_paths`` argument on Redmine object instantiation.
6058

6159
Methods and Attributes
6260
----------------------
6361

64-
All existing resources are derived from a ``Resource`` class which you usually won't inherit from
65-
directly unless you want to add support for a new resource which Python Redmine doesn't support.
62+
All existing resources are derived from a ``BaseResource`` class which you usually won't inherit from
63+
directly unless you want to add support for a new resource which Python-Redmine doesn't support.
6664
Below you will find methods and attributes which can be redefined in your custom resource:
6765

68-
.. autoclass:: redmine.resources.Resource
69-
:members: __init__, __getattr__, __setattr__, refresh, pre_create, post_create, pre_update, post_update, save, encode, decode, bulk_encode, bulk_decode
70-
:undoc-members:
71-
:private-members:
66+
.. autoclass:: redminelib.resources.BaseResource
67+
:members: __getattr__, __setattr__, decode, encode, bulk_decode, bulk_encode, raw, refresh, pre_create, post_create, pre_update, post_update, pre_delete, post_delete, save, delete, export
68+
:undoc-members:
69+
:private-members:

‎docs/advanced/external_auth.rst‎

Lines changed: 11 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,16 @@
11
External Authentication
22
=======================
33

4-
.. versionadded:: 0.6.0
5-
6-
It is possible to use Python Redmine as a provider for external authentication based on the
4+
It is possible to use Python-Redmine as a provider for external authentication based on the
75
Redmine user database, e.g. imagine you are making a website and you want to only authenticate
86
your users if they provide the same login/password they use to login to Redmine:
97

108
.. code-block:: python
119
12-
username = 'john' # username comes from the POST request on form submit
13-
password = 'qwerty' # password comes from the POST request on form submit
10+
username = 'john' # username comes from the POST request on form submit
11+
password = 'qwerty' # password comes from the POST request on form submit
1412
15-
user = Redmine('https://redmine.url', username=username, password=password).auth()
13+
user = Redmine('https://redmine.url', username=username, password=password).auth()
1614
1715
If authentication succeeded, ``user`` variable will contain details about the current user, if
1816
there was an error during authentication proccess, an ``AuthError`` exception will be thrown.
@@ -22,12 +20,12 @@ intercept ``AuthError`` exception and do what you need, for example:
2220

2321
.. code-block:: python
2422
25-
from redminelib.exceptions import AuthError
23+
from redminelib.exceptions import AuthError
2624
27-
username = 'john' # username comes from the POST request on form submit
28-
password = 'qwerty' # password comes from the POST request on form submit
25+
username = 'john' # username comes from the POST request on form submit
26+
password = 'qwerty' # password comes from the POST request on form submit
2927
30-
try:
31-
user = Redmine('https://redmine.url', username=username, password=password).auth()
32-
except AuthError:
33-
raise Exception('Invalid login or password provided')
28+
try:
29+
user = Redmine('https://redmine.url', username=username, password=password).auth()
30+
except AuthError:
31+
raise Exception('Invalid login or password provided')

‎docs/advanced/index.rst‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,9 @@ Advanced Usage
22
==============
33

44
.. toctree::
5-
:maxdepth: 1
5+
:maxdepth: 1
66

7-
custom_resources
8-
external_auth
9-
working_with_files
7+
request_engines
8+
custom_resources
9+
external_auth
10+
working_with_files

0 commit comments

Comments
 (0)