Merge branch 'docs-fixes' into origin/master

docs/_static/.gitignore

@@ -0,0 +1,2 @@
+# Dummy file used to keep this folder in VCS.
+!.gitignore

docs/usage/advanced/caching.rst

@@ -6,20 +6,20 @@ Most objects accessible through the PlanetSide 2 API are static, meaning that th
 
 Auraxium uses a caching system to reduce API load by keeping objects in memory past their initial lifetime. The next time this item is accessed, it is instead restored from cache without incurring any network traffic.
 
-This is done via a local `TLRU Cache`_ specific to each cacheable object type. This type of cache has two replacement mechanisms: The first acts like a stack, with items being moved to the top as they are reused, and the bottom ones being discarded as the cache reaches its size limit due to new items being added. This is also referred to as a "least recently used" (LRU) cache.
+This is done via a local `TLRU Cache`_ specific to each cacheable object type. TLRU caches have two replacement mechanisms: The first acts like a stack, with items being moved to the top as they are reused, and the bottom ones being discarded as the cache reaches its size limit due to new items being added. This is also referred to as a "least recently used" (LRU) cache.
 
-Additionally, cache items have a maximum lifetime to force updates for regularly used objects. This mostly ensures that semi-static objects are never too far out of date (such as outfit member counts, tags, or character names.
+Additionally, cache items have a maximum lifetime to force updates for regularly used objects. This mostly ensures that semi-static objects are never too far out of date (such as outfit member counts, tags, or character names).
 
 .. note::
 
    Restoring items from cache is currently only supported when using :meth:`Client.get_by_id <auraxium.Client.get_by_id>`.
 
-   For :class:`Named <auraxium.base.Named.get_by_name>` sub classes, the :meth:`Client.get_by_name <auraxium.Client.get_by_name>` method is similarly cached by locale. This means that looking up the same name in two different locales will create two separate cache entries.
+   For :class:`Named <auraxium.base.Named.get_by_name>` subclasses, the :meth:`Client.get_by_name <auraxium.Client.get_by_name>` method is similarly cached by locale. This means that looking up the same name in two different locales will create two separate cache entries.
 
-Customising Caches
+Customizing Caches
 ------------------
 
-Each PlanetSide 2 datatype is preconfigured with a suitable cache size and item lifetime. Factions, for example, are only updated once an hour. Characters are limited to a size of 256 and only last 30 seconds before they are repolled.
+Each PlanetSide 2 data type is preconfigured with a suitable cache size and item lifetime. Factions, for example, are only updated once an hour. Characters are limited to a size of 256 and only last 30 seconds before they are re-polled.
 
 You can override the default values at runtime using the :meth:`Cached.alter_cache <auraxium.base.Cached.alter_cache>` method:
 

docs/usage/advanced/queries.rst

@@ -1,5 +1,5 @@
 ==============================
-Optimising With Custom Queries
+Optimizing With Custom Queries
 ==============================
 
 This document covers how to improve performance for expensive requests that slow down your application.
@@ -8,14 +8,14 @@ It is therefore highly advisable to read the `Census API Primer`_ in the reposit
 
 .. note::
 
-   The optimisations explained herein are likely not needed unless you are sending out hundreds of requests a second and are already running into bottle necks.
+   The optimizations explained herein are likely not needed unless you are sending out hundreds of requests a second and are already running into bottlenecks.
 
 Motivation
 ==========
 
-The Auraxium object model makes the API more accessible and facilitates traversal of its relations, but in return gives up some of the flexibility of the original Daybreak Games Census API.
+The Auraxium object model makes the API more accessible and facilitates traversal of its relations, but in return gives up some flexibility of the original Daybreak Games Census API.
 
-One such optimisation are `Joins`_, a means of bundling multiple related queries into a single request, similar to how SQL joins allow returning data from multiple tables. This allows requesting a lot of data in a single query, like resolving particular statistics for outfit members of a particular rank.
+One such optimization are `Joins`_, a means of bundling multiple related queries into a single request, similar to how SQL joins allow returning data from multiple tables. This allows requesting a lot of data in a single query, like resolving particular statistics for outfit members of a particular rank.
 
 Due to their dynamic nature, joins are not available through the object model, but are fully supported by the :mod:`auraxium.census` module, which Auraxium uses to generate the URLs needed to access the Census API.
 
@@ -42,7 +42,7 @@ In this case, the created query is identical to this:
 
    query = auraxium.census.Query('character', character_id=5428072203494645969)
 
-This query can now be customised as per the :mod:`auraxium.census` module API.
+This query can now be customized as per the :mod:`auraxium.census` module API.
 
 For the purposes of this example, we will return the online status of all of a character's friends; an operation that is not possible in a single operation when using the object model:
 

docs/usage/basic/census.rst

@@ -4,15 +4,15 @@ Census URL Generator
 
 .. module:: auraxium.census
 
-The :mod:`auraxium.census` module provides a low-level Python wrapper around the PlanetSide 2 REST API. It is used internally by Auraxium to generate any URLs needed for traversal of the object model, but may also be used by advanced users to customise queries and increase performance of their apps.
+The :mod:`auraxium.census` module provides a low-level Python wrapper around the PlanetSide 2 REST API. It is used internally by Auraxium to generate any URLs needed for traversal of the object model, but may also be used by advanced users to customize queries and increase performance of their apps.
 
 The following pages cover the URL generator interface and usage, but the underlying REST endpoint's structure, functionality and limitations are outside the scope of this document. If you are unfamiliar with the Daybreak Game Company's Census API or would like a refresh, please refer to the `Census API Primer`_ in the repository Wiki.
 
 For an example of how to use the URL generator and custom queries in conjunction with the Auraxium object model, refer to the :doc:`../advanced/queries` page.
 
 .. note::
 
-   The URL generator is independent from the rest of the Auraxium package and may be imported separately. If your use case does not benefit from the object model or event streaming client, you can still use the URL generator on its own to keep your source code free of URL literals:
+   The URL generator is independent of the rest of the Auraxium package and may be imported separately. If your use case does not benefit from the object model or event streaming client, you can still use the URL generator on its own to keep your source code free of URL literals:
 
    .. code-block:: python3
 
@@ -72,7 +72,7 @@ The PlanetSide 2 API defines two distinct types of queries. The first is the mai
 
 To generate a URL from a query, run the :meth:`Query.url` method. By default, this uses the ``get`` query verb. This is the main endpoint used to retrieve data and supports the entire query interface, and will return actual matches for a given query. Alternatively, one can specify ``verb='count'`` to instead only return the number of potential matches. This is helpful when working with filtered data sets of unknown size, so that pagination or other custom formats can be used to display the requested data.
 
-Top level queries also support global flags (or `query commands`) that allow enable :meth:`case insensitive<Query.case>` string comparison, :meth:`sorting <Query.sort>` of results, or enable special query modes like :meth:`~Query.distinct`, illustrated below:
+Top level queries also support global flags (or `query commands`) that allow for :meth:`case insensitive<Query.case>` string comparison, :meth:`sorting <Query.sort>` of results, or enable special query modes like :meth:`~Query.distinct`, illustrated below:
 
 .. code-block:: python3
 
@@ -121,7 +121,7 @@ Joins are used to return data related to another query's return values as part o
 
 The relation between a join and its parent is defined by the :meth:`~JoinedQuery.set_fields` method. The joins data is then inserted into an extra field in the response, either named ``<parent_field>_join_<joined_collection>`` (default) or a custom name specified through the :meth:`JoinedQuery.set_inject_at` method.
 
-Joined queries can not be directly translated into a URL, the must be attached to a top level query instead. This can be done via the :meth:`QueryBase.add_join` (for existing joins) or :meth:`QueryBase.create_join` (for new joins) methods. The :meth:`JoinedQuery.serialise` method allows conersion of a :class:`JoinedQuery` into its URL-compatible, serialised format. This hook is used by the parent query when the top level query's :meth:`Query.url` method is called.
+Joined queries can not be directly translated into a URL, the must be attached to a top level query instead. This can be done via the :meth:`QueryBase.add_join` (for existing joins) or :meth:`QueryBase.create_join` (for new joins) methods. The :meth:`JoinedQuery.serialise` method allows conversion of a :class:`JoinedQuery` into its URL-compatible, serialized format. This hook is used by the parent query when the top level query's :meth:`Query.url` method is called.
 
 For more information on joined queries, pitfalls and examples, refer to the `Joined Queries`_ section of the aforementioned `Census API primer`_ Wiki article.
 
@@ -135,7 +135,7 @@ This conversion is done as part of the :meth:`Query.copy`/:meth:`JoinedQuery.cop
 Terms and search modifiers
 ==========================
 
-The key-value pairs used to filter queries (previously introduced as the query's `terms`) are represented by the :class:`SearchTerm` class, which provides facilities for parsing, serialising and formatting these terms for use in query strings.
+The key-value pairs used to filter queries (previously introduced as the query's `terms`) are represented by the :class:`SearchTerm` class, which provides facilities for parsing, serializing and formatting these terms for use in query strings.
 
 Terms can be added directly using a query's :meth:`QueryBase.add_term` method, or may alternatively be generated via keyword arguments as part of the query instantiation:
 

docs/usage/basic/event.rst

@@ -6,7 +6,7 @@ The PlanetSide 2 API supports streaming in-game events directly to your client.
 
 This is useful for obtaining real-time event data, but can also be used to gain access to data that would otherwise not be available through the REST API (see the `Examples`_ below).
 
-To gain access to event streaming functionality in Auraxium, you must use the :class:`auraxium.event.EventClient` class. This is a sub class of :class:`auraxium.Client` and still supports the full REST API.
+To gain access to event streaming functionality in Auraxium, you must use the :class:`auraxium.event.EventClient` class. This is a subclass of :class:`auraxium.Client` and still supports the full REST API.
 
 .. note::
 
@@ -46,7 +46,7 @@ Auraxium wraps the real-time event endpoint of the PlanetSide 2 API in an event
 Triggers
 --------
 
-Triggers are the main building block of the event streaming interface. They store what events to listen to (e.g. players deaths) and then execute an function when such an event is encountered (e.g. mock them in Discord).
+Triggers are the main building block of the event streaming interface. They store what events to listen to (e.g. players deaths) and then execute a function when such an event is encountered (e.g. mock them in Discord).
 
 In the case of the PlanetSide 2 event stream, this information is also used to dynamically generate or update the subscription messages needed to receive the appropriate payloads through the WebSocket API.
 
@@ -85,11 +85,11 @@ For the full set of features, instantiate the :class:`auraxium.event.Trigger` ma
 Conditions
 ----------
 
-Whether a trigger fires is mainly controlled by its events. However, sometimes you may have multiple triggers whos event definitions overlap to some extent.
+Whether a trigger fires is mainly controlled by its events. However, sometimes you may have multiple triggers who's event definitions overlap to some extent.
 
 To keep your event callbacks tidy and not cause unnecessary triggering of potentially expensive actions, you can additionally specify any number of conditions that must be met for the trigger to fire.
 
-Conditions are stored in the :attr:`Trigger.conditions <auraxium.event.Trigger.conditions>` list and are save to be modified or updated at any point.
+Conditions are stored in the :attr:`Trigger.conditions <auraxium.event.Trigger.conditions>` list and are safe to be modified or updated at any point.
 
 This list may contain synchronous callables or any object that evaluates to :obj:`bool`. Callables must take a single argument: the :class:`auraxium.event.Event` encountered.
 
@@ -154,7 +154,7 @@ Due to the dynamic nature of these events, they are not part of the :mod:`auraxi
 .. automethod:: auraxium.event.GainExperience.filter_experience
    :noindex:
 
-The strings generated by this method can then be used in place of :class:`auraxium.event.Event` sub classses to define triggers and conditions.
+The strings generated by this method can then be used in place of :class:`auraxium.event.Event` sub classes to define triggers and conditions.
 
 Examples
 ========

docs/usage/basic/getting-started.rst

@@ -42,7 +42,7 @@ You can also use the following commands to install the latest development build
 
 .. note::
 
-   When using pre-release versions of Auraxium as a dependency for your own packages, be sure to to pin the exact version used in ``setup.py`` or ``requirements.txt``.
+   When using pre-release versions of Auraxium as a dependency for your own packages, be sure to pin the exact version used in ``setup.py`` or ``requirements.txt``.
 
    The API for these versions should not be considered stable and could break your application with the next minor version upgrade.
 
@@ -51,14 +51,14 @@ Overview
 
 Auraxium can interface with the Daybreak Game Company's `Census API`_ in one of three ways. The first is the object model, which wraps the API's REST interface and allows accessing and navigating between specific pieces of data like character names or weapon statistics.
 
-The :class:`auraxium.event.EventClient` sub class additionally supports the event streaming interface, used to react to in-game events like continent locks or player deaths in next to real-time via a WebSocket connection.
+The :class:`auraxium.event.EventClient` subclass additionally supports the event streaming interface, used to react to in-game events like continent locks or player deaths in next to real-time via a WebSocket connection.
 
-Finally, the internal URL generator used to nevigate the object model can also be used on its own, allowing a high degree of customisation for the queries used. This lower-level access allows for optimisations not possible through the regular object-based REST interface.
+Finally, the internal URL generator used to navigate the object model can also be used on its own, allowing a high degree of customization for the queries used. This lower-level access allows for optimizations not possible through the regular object-based REST interface.
 
 Object Model
 ------------
 
-All API interactions are performed through :class:`auraxium.Client` or one of its sub classes. The class representations of in-game objects can be found in the :mod:`auraxium.ps2` module.
+All API interactions are performed through :class:`auraxium.Client` or one of its subclasses. The class representations of in-game objects can be found in the :mod:`auraxium.ps2` module.
 
 To retrieve in-game object instances, use :meth:`~auraxium.Client.get`, for single items, or :meth:`~auraxium.Client.find` for lists.
 
@@ -71,7 +71,7 @@ For more information on the available classes and the attributes they expose, re
 Event Stream
 ------------
 
-The :class:`auraxium.event.EventClient` sub class adds a trigger-action system allowing the user to trigger actions when certain in-game events occur:
+The :class:`auraxium.event.EventClient` subclass adds a trigger-action system allowing the user to trigger actions when certain in-game events occur:
 
 .. code-block:: python3
 
@@ -88,20 +88,20 @@ For more information on the event streaming system, refer to the :doc:`event str
 URL Generator
 -------------
 
-The URL generator used for low-level access to the PlanetSide 2 API resides in the :mod:`auraxium.census` sub module.
+The URL generator used for low-level access to the PlanetSide 2 API resides in the :mod:`auraxium.census` submodule.
 
-Note that this module is targeted at advanced users or ones familiar with the underlying Census API. An introduction into the module interface can be found :doc:`here <census>`.
+Note that this module is targeted at advanced users or anyone familiar with the underlying Census API. An introduction into the module interface can be found :doc:`here <census>`.
 
 Service IDs
 ===========
 
 The PlanetSide 2 API requires all client applications to register and use a service ID for all of its requests. Service IDs are used to identify your application and troubleshoot quality of service issues.
 
-You can apply for your own service ID `here <service ID signup>`_. The process is free and usually only takes an hour or two to complete.
+You can apply for your own service ID `here <service ID signup_>`_. The process is free and usually only takes an hour or two to complete.
 
 In Auraxium, the service ID is specified via the `service_id` argument of the :class:`auraxium.Client` instance.
 
-For casual use and development, the default ``s:example`` service ID is also avilable, but it is limited to 10 requests per minute per IP address.
+For casual use and development, the default ``s:example`` service ID is also available, but it is limited to 10 requests per minute and IP address.
 
 .. _Census API: https://census.daybreakgames.com/
 .. _Python: https://www.python.org/downloads/

docs/usage/basic/logging.rst

@@ -10,7 +10,7 @@ The following snippet will, if placed before your application code, log all but
 
    import logging
 
-   logging.basicConfnig(level=logging.INFO)
+   logging.basicConfig(level=logging.INFO)
 
 Alternatively, the following snippet is an example of a more comprehensive logging setup, only keeping warnings and errors in the console while still logging to disk at full resolution. This option is recommended for troubleshooting:
 

docs/usage/basic/rest.rst

@@ -15,7 +15,7 @@ Retrieving Data
 
 .. note::
 
-   The game-specific object representations for PlanetSide 2 reside in the :mod:`auraxium.ps2` submodule. Refer to the `Object Model Documentation <api/ps2.html>`_  for details.
+   The game-specific object representations for PlanetSide 2 reside in the :mod:`auraxium.ps2` submodule. Refer to the `Object Model Documentation <api/ps2.html>`_ for details.
 
 The :class:`auraxium.Client` class exposes several methods used to access the REST API data, like :meth:`~auraxium.Client.get()`, used to return a single match, or :meth:`~auraxium.Client.find()`, used to return a list of matching entries.
 
@@ -33,7 +33,7 @@ This means that repeatedly accessing an object through :meth:`~auraxium.Client.g
        async with auraxium.Client() as client:
 
            char = await client.get_by_name(ps2.Character, 'auroram')
-           print(char.name))
+           print(char.name)
            print(char.data.prestige_level)
 
            # NOTE: Any methods that might incur network traffic are asynchronous.