Docs: Consolidate reference material

README.md

@@ -26,7 +26,7 @@
 mwclient is a lightweight Python client library to the
 [MediaWiki API](https://mediawiki.org/wiki/API)
 which provides access to most API functionality.
-It works with Python 2.7, 3.3 and above,
+It works with Python 2.7 as well as 3.4 and above,
 and supports MediaWiki 1.16 and above.
 For functions not available in the current MediaWiki,
 a `MediaWikiVersionError` is raised.
@@ -50,15 +50,15 @@ Please see the [changelog
 document](https://github.com/mwclient/mwclient/blob/master/CHANGELOG.md)
 for a list of changes.
 
-## Getting started
+## Documentation
 
-See the
-[user guide](http://mwclient.readthedocs.io/en/latest/user/index.html)
-to get started using mwclient.
+Up-to-date documentation is hosted [at Read the Docs](http://mwclient.readthedocs.io/en/latest/).
+It includes a user guide to get started using mwclient, a reference guide,
+implementation and development notes.
 
-For more information, see the
-[REFERENCE.md](https://github.com/mwclient/mwclient/blob/master/REFERENCE.md) file
-and the [documentation on the wiki](https://github.com/mwclient/mwclient/wiki).
+There is also some documentation on the [GitHub wiki](https://github.com/mwclient/mwclient/wiki)
+that hasn't been ported yet.
+If you want to help, you're welcome!
 
 ## Contributing
 
@@ -106,24 +106,3 @@ $ make html
 When writing docstrings, try to adhere to the
 [Google style](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html).
 
-# Implementation notes
-
-Most properties and generators accept the same parameters as the API,
-without their two-letter prefix. Exceptions to this rule:
-
-- `Image.imageinfo` is the imageinfo of the latest image.
-   Earlier versions can be fetched using `imagehistory()`
-- `Site.all*`: parameter `[ap]from` renamed to `start`
-- `categorymembers` is implemented as `Category.members`
-- `deletedrevs` is `deletedrevisions`
-- `usercontribs` is `usercontributions`
-- First parameters of `search` and `usercontributions`
-  are `search` and `user` respectively
-
-Properties and generators are implemented as Python generators.
-Their limit parameter is only an indication
-of the number of items in one chunk.
-It is not the total limit.
-Doing `list(generator(limit = limit))` will return ALL items of generator,
-and not be limited by the limit value.
-Default chunk size is generally the maximum chunk size.

REFERENCE.md

-This file is intended to be a reference to mwclient.
-The current version is mwclient 0.6.5.
-
-The mwclient framework provides access to the MediaWiki API.
-It provides the functions of the MediaWiki API in a Pythonic manner.
-
-## Sites ##
-The `Site` object is the most important class.
-It represents a MediaWiki site.
-Its constructor accepts various arguments,
-of which the first two, `host` and `path`, are the most important.
-They represent respectively
-the hostname without protocol
-and the root directory where `api.php` is located.
-The path parameter should end with a slash, /.
-Protocols other than HTTP and HTTPS are currently not supported.
-
-```python
-#http
-site = mwclient.Site(host, path = '/w/', ...)
-
-#https
-site = mwclient.Site(('https', host), path = '/w/', ...)
-```
-
-### Pages ###
-Sites provide access to pages via various generators and the Pages object.
-The base Page object is called Page
-and from that derive Category and Image.
-When the page is retrieved via `Site.Pages` or a generator,
-it will check automatically which of those three specific types
-should be returned.
-To get a page by its name, call `Site.Pages` as a scriptable object:
-
-```python
-page = site.Pages['Template:Stub']
-image = site.Pages['Image:Wiki.png'] # This will return an Image object
-image2 = site.Images['Wiki.png'] # The same image
-```
-
-Alternatively, `Site.Images` and `Site.Categories` are provided,
-which do exactly the same as `Site.Pages`,
-except that they require the page name without its namespace prefixed.
-
-#### PageProperties ####
-The `Page` object provides many generators available in the API.
-In addition to the page properties listed in the API documentation,
-also the lists backlinks and embedded in are members of the Page object. For more information about using generators
-see the section on generators below.
-
-`Category` objects provide an extra function, `members`
-to list all members of a category.
-The Category object can also be used itself
-as an iterator yielding all its members.
-
-```python
-#list pages in Category:Help by name
-category = site.Pages['Category:Help']
-for page in category:
-	print page.name
-```
-
-`Image` objects have additional functions `imagehistory` and `imageusage`
-which represent the old versions of the image and its usage, respectively.
-`Image.download` returns a file object to the full size image.
-
-```python
-fr = image.download()
-fw = open('Wiki.png', 'rb')
-while True:
-	s = fr.read(4096)
-	if not s: break
-	fw.write(s)
-fr.close() # Always close those file objects !!!
-fw.close()
-```
-
-#### Editing pages ####
-Call `Page.text()` to retrieve the page content.
-Use `Page.save(text, summary = u'', ...)` to save the page.
-If available, `Page.save` uses the API to edit,
-but falls back to the old way if the write API is not available.
-
-## Generators ##
-
-## Exceptions ##
-
-## Implementation notes ##
-Most properties and generators accept the same parameters as the API,
-without their two-letter prefix.
-Exceptions:
-* `Image.imageinfo` is the `imageinfo` of the *latest* image.
-Earlier versions can be fetched using `imagehistory()`
-* `Site.all*`: parameter `(ap)from` renamed to `start`
-* `categorymembers` is implemented as `Category.members`
-* `deletedrevs` is `deletedrevisions`
-* `usercontribs` is `usercontributions`
-* First parameters of `search` and `usercontributions`
-  are `search` and `user`, respectively
-
-Properties and generators are implemented as Python generators.
-Their limit parameter is only an indication
-of the number of items in one chunk.
-It is not the total limit.
-Doing `list(generator(limit = limit))` will return
-ALL items of generator, and not be limited by the limit value.
-Use `list(generator(max_items = max_items))`
-to limit the amount of items returned.
-Default chunk size is generally the maximum chunk size.
-
-## Links ##
-* Project page at GitHub: https://github.com/mwclient/mwclient
-* More in-depth documentation on the GitHub wiki: 
-https://github.com/mwclient/mwclient/wiki
-* MediaWiki API documentation: https://mediawiki.org/wiki/API

docs/source/reference/page.rst

@@ -3,3 +3,6 @@
 
 .. autoclass:: mwclient.page.Page
    :members:
+
+.. autoclass:: mwclient.listing.Category
+   :members:

docs/source/user/files.rst

@@ -44,6 +44,17 @@ See the :class:`API reference <mwclient.image.Image>` for more options.
     To check if a file exists locally *or* in a shared repo, you could test if
     ``image.imageinfo != {}``.
 
+Downloading a file
+------------------
+
+The :meth:`Image.download() <mwclient.image.Image.download>` method can be used to download
+the full size file. Pass it a file object and it will stream the image to it,
+avoiding the need for keeping the whole file in memory:
+
+    >>> file = site.images['Example.jpg']
+    >>> with open('Example.jpg', 'wb') as fd:
+    ...     image.download(fd)
+
 Uploading a file
 ----------------
 

docs/source/user/implementation-notes.rst

+.. _`implementation-notes`:
+
+Implementation notes
+====================
+
+Most properties and generators accept the same parameters as the API, without their two-letter prefix.
+Some notable exceptions:
+
+* ``Image.imageinfo`` is the imageinfo of the latest image. Earlier versions can be fetched using ``imagehistory()``.
+* ``Site.all*``: parameter ``(ap)from`` renamed to ``start``
+* ``categorymembers`` is implemented as ``Category.members``
+* ``deletedrevs`` is ``deletedrevisions``
+* ``usercontribs`` is ``usercontributions``
+* First parameters of ``search`` and ``usercontributions`` are ``search`` and ``user``, respectively
+
+Properties and generators are implemented as Python generators. Their limit parameter is only an indication of the number of items in one chunk. It is not the total limit. Doing ``list(generator(limit = limit))`` will return ALL items of generator, and not be limited by the limit value. Use ``list(generator(max_items = max_items))`` to limit the amount of items returned. Default chunk size is generally the maximum chunk size.
+
+Page objects
+------------
+
+The base Page object is called ``Page``
+and from that derive ``Category`` and ``Image``.
+When the page is retrieved via ``Site.pages`` or a generator,
+it will check automatically which of those three specific types
+should be returned.
+
+For convenience, ``Site.images`` and ``Site.categories`` are also provided.
+These do exactly the same as `Site.Pages`, except that they require the page name
+without its namespace prefixed.
+
+    >>> page = site.Pages['Template:Stub']   # a Page object
+    >>> image = site.Pages['Image:Wiki.png'] # an Image object
+    >>> image = site.Images['Wiki.png']      # the same Image object
+    >>> cat = site.Pages['Category:Python']  # a Category object
+    >>> cat = site.Images['Python']          # the same Category object

docs/source/user/index.rst

@@ -14,3 +14,4 @@ classes contained in the package, see the :ref:`reference`.
    connecting
    page-ops
    files
+   implementation-notes

docs/source/user/page-ops.rst

@@ -14,7 +14,7 @@ For information about authenticating, please see
 Editing or creating a page
 --------------------------
 
-To get the wikitext for a specific page:
+To get the content of a specific page:
 
     >>> page = site.pages['Greater guinea pig']
     >>> text = page.text()
@@ -61,6 +61,21 @@ is handled under the hood so you don't have to worry about it.
     ...     dt = datetime.fromtimestamp(mktime(revision['timestamp']))
     ...     print '{}'.format(dt.strftime('%F %T'))
 
+Categories
+----------
+
+Categories can be retrieved in the same way as pages, but you can also use
+:meth:`Site.categories() <mwclient.client.Site.categories>` and skip the namespace prefix.
+The returned :class:`Category <mwclient.listing.Category>` object
+supports the same methods as the :class:`Page <mwclient.page.Page>`
+object, but also provides an extra function, :meth:`members() <mwclient.listing.Category.members>`,
+to list all members of a category.
+
+The Category object can also be used itself as an iterator to yield all its members:
+
+    >>> category = site.categories['Python']
+    >>> for page in category:
+    >>>     print(page.name)
 
 Other page operations
 ---------------------