docs: mwclient#302 recommend setting a user-agent

docs/source/index.rst

@@ -27,7 +27,8 @@ Quickstart
 
 .. code-block:: python
 
-    >>> site = mwclient.Site('en.wikipedia.org')
+    >>> user_agent = 'MyCoolTool/0.2 (xyz@example.org)'
+    >>> site = mwclient.Site('en.wikipedia.org', clients_useragent=user_agent)
     >>> page = site.pages[u'Leipäjuusto']
     >>> page.text()
     u'{{Unreferenced|date=September 2009}}\n[[Image:Leip\xe4juusto cheese with cloudberry jam.jpg|thumb|Leip\xe4juusto with [[cloudberry]] jam]]\n\'\'\'Leip\xe4juusto\'\'\' (bread cheese) or \'\'juustoleip\xe4\'\', which is also known in English as \'\'\'Finnish squeaky cheese\'\'\', is a fresh [[cheese]] traditionally made from cow\'s [[beestings]], rich milk from a cow that has recently calved.'

docs/source/user/connecting.rst

@@ -3,13 +3,24 @@
 Connecting to your site
 =======================
 
-Begin by importing the Site class:
+To connect to a MediaWiki site, you need to create a :class:`~mwclient.client.Site`
+object and pass it the hostname of the site you want to connect to. The hostname
+should not include the protocol (http or https) or the path to the API endpoint
+(see :ref:`endpoint`).
 
-    >>> from mwclient import Site
+.. code-block:: python
+
+    from mwclient import Site
 
-Then try to connect to a site:
+    user_agent = 'MyCoolTool/0.2 (xyz@example.org)'
+    site = Site('en.wikipedia.org', clients_useragent=user_agent)
 
-    >>> site = Site('test.wikipedia.org')
+.. warning::
+
+    The ``clients_useragent`` parameter, while optional, is highly recommended
+    and may be required by some sites, such as the Wikimedia wikis (e.g.
+    Wikipedia). Requests without a user agent may be rejected or rate-limited
+    by the site. See :ref:`user-agent` for more information.
 
 By default, mwclient will connect using https. If your site doesn't support
 https, you need to explicitly request http like so:
@@ -27,7 +38,7 @@ Wikimedia wikis. If you get a 404 Not Found or a
 :class:`mwclient.errors.InvalidResponse` error upon connecting, your site might
 use a different script path. You can specify it using the ``path`` argument:
 
-    >>> site = Site('my-awesome-wiki.org', path='/wiki/', )
+    >>> site = Site('my-awesome-wiki.org', path='/wiki/')
 
 .. _$wgScriptPath: https://www.mediawiki.org/wiki/Manual:$wgScriptPath
 
@@ -41,15 +52,19 @@ If you are connecting to a Wikimedia site, you should follow the
 The user agent should contain the tool name, the tool version
 and a way to contact you:
 
-    >>> ua = 'MyCoolTool/0.2 (xyz@example.org)'
-    >>> site = Site('test.wikipedia.org', clients_useragent=ua)
+    >>> user_agent = 'MyCoolTool/0.2 (xyz@example.org)'
+    >>> site = Site('test.wikipedia.org', clients_useragent=user_agent)
 
 It should follow the pattern
 ``{tool_name}/{tool_version} ({contact})``. The contact info can also
 be your user name and the tool version may be omitted:
 ``RudolphBot (User:Santa Claus)``.
 
 Note that MwClient appends its own user agent to the end of your string.
+The final user agent will look like this:
+
+    >>> site.clients_useragent
+    'MyCoolTool/0.2 (xyz@example.org) mwclient/0.8.0'
 
 .. _Wikimedia User-Agent policy: https://meta.wikimedia.org/wiki/User-Agent_policy
 

docs/source/user/page-ops.rst

@@ -3,10 +3,15 @@
 Page operations
 ===============
 
-Start by :ref:`connecting <connecting>` to your site:
+Start by :ref:`connecting <connecting>` to your site as described in the
+:ref:`Connecting to your site <connecting>` section.
 
-    >>> from mwclient import Site
-    >>> site = Site('en.wikipedia.org')
+.. code-block:: python
+
+    from mwclient import Site
+
+    user_agent = 'MyCoolTool/0.2 (xyz@example.org)'
+    site = Site('en.wikipedia.org', clients_useragent=user_agent)
 
 For information about authenticating, please see
 :ref:`the section on authenticating <auth>`.