Minor docs improvements and fixes

Author: tomasbedrich

docs/api.rst

@@ -10,6 +10,10 @@ Here you can find an overview of all avaliable classes and methods.
    For example: if you rely on some non-deprecated method in version 3.3, then it's fine to update
    once to 3.4. If the method gets deprecated in 3.4, then it will be removed in 3.5!
 
+.. automodule:: pycaching
+  :members: login
+
+
 Geocaching
 -------------------------------------------------------------------------------
 

docs/conf.py

@@ -23,6 +23,8 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.abspath('..'))
 
+from setup import info
+
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -62,9 +64,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '3.4'
+version = '.'.join(info['version'].split('.')[:2])
 # The full version, including alpha/beta/rc tags.
-release = '3.4'
+release = info['version']
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/index.rst

@@ -1,4 +1,11 @@
+===================================================================================================
+pycaching - Geocaching for Python
+===================================================================================================
+
+Source codes can be found at `GitHub repository <https://github.com/tomasbedrich/pycaching>`_.
+
 .. include:: ../README.rst
+    :start-after: _features:
     :end-before: _installation:
 
 

pycaching/__init__.py

@@ -8,7 +8,12 @@
 
 
 def login(username=None, password=None):
-    """Logs the user in. A shortcut for Geocaching().login()."""
+    """A shortcut for user login.
+
+    Create a :class:`.Geocaching` instance and try to login a user. See :meth:`.Geocaching.login`.
+
+    :return: Created :class:`.Geocaching` instance.
+    """
     g = Geocaching()
     g.login(username, password)
     return g

pycaching/cache.py

@@ -492,8 +492,8 @@ def load(self):
            This method is called automatically when you access a property which isn't yet filled in
            (so-called "lazy loading"). You don't have to call it explicitly.
 
-        :raise PMOnlyException: If cache is PM only and current user is basic member.
-        :raise LoadError: If cache loading fails (probably because of not existing cache).
+        :raise .PMOnlyException: If cache is PM only and current user is basic member.
+        :raise .LoadError: If cache loading fails (probably because of not existing cache).
         """
         try:
             # pick url based on what info we have right now
@@ -578,7 +578,7 @@ def load_quick(self):
         the only loaded properties are: `name`, `type`, `state`, `size`, `difficulty`, `terrain`,
         `hidden`, `author`, `favorites` and `pm_only`.
 
-        :raise LoadError: If cache loading fails (probably because of not existing cache).
+        :raise .LoadError: If cache loading fails (probably because of not existing cache).
         """
         res = self.geocaching._request("http://tiles01.geocaching.com/map.details", params={
             "i": self.wp
@@ -609,7 +609,7 @@ def _logbook_get_page(self, page=0, per_page=25):
 
         :param int page: Logbook page to load.
         :param int per_page: Logs per page (used to calculate start index).
-        :raise LoadError: If loading fails.
+        :raise .LoadError: If loading fails.
         """
         res = self.geocaching._request("seek/geocache.logbook", params={
             "tkn": self._logbook_token,  # will trigger lazy_loading if needed
@@ -779,7 +779,7 @@ def from_filename(cls, filename):
     def from_string(cls, name):
         """Return a cache type from its human readable name.
 
-        :raise ValueError: If cache type cannot be determined.
+        :raise .ValueError: If cache type cannot be determined.
         """
         name = name.replace(" Geocache", "")  # with space!
         name = name.replace(" Cache", "")  # with space!
@@ -837,7 +837,7 @@ def from_filename(cls, filename):
     def from_string(cls, name):
         """Return a cache size from its human readable name.
 
-        :raise ValueError: If cache size cannot be determined.
+        :raise .ValueError: If cache size cannot be determined.
         """
         name = name.strip().lower()
 

pycaching/geo.py

@@ -37,7 +37,7 @@ def from_location(cls, geocaching, location):
         :param .Geocaching geocaching: Reference to :class:`.Geocaching` instance, used to do
             a geocoding request.
         :param str location: Location to geocode.
-        :raise GeocodeError: If location cannot be geocoded (not found).
+        :raise .GeocodeError: If location cannot be geocoded (not found).
         """
         res = geocaching._request("api/geocode", params={"q": location}, expect="json")
 
@@ -56,7 +56,7 @@ def from_string(cls, string):
         - :code:`N 6 52.861  W174   43.327`
 
         :param str string: Coordinates to parse.
-        :raise ValueError: If string cannot be parsed as coordinates.
+        :raise .ValueError: If string cannot be parsed as coordinates.
         """
 
         # Make it uppercase for consistency
@@ -90,7 +90,7 @@ def from_string(cls, string):
     def from_block(cls, block):
         """Return a new :class:`.Point` instance from :class:`.Block` instance.
 
-        :param Block block: UTFGrid block.
+        :param .Block block: UTFGrid block.
         """
         return cls.from_tile(block.tile, block.middle_point)
 

pycaching/geocaching.py

@@ -73,7 +73,9 @@ def login(self, username=None, password=None):
         and do some checks about currently logged user. As a last thing post the login form and
         check result.
 
-        :raise LoginFailedException: If login fails either because of bad credentials or
+        :param str username: User's username or :code:`None` to use data from credentials file.
+        :param str password: User's password or :code:`None` to use data from credentials file.
+        :raise .LoginFailedException: If login fails either because of bad credentials or
             non-existing credentials file.
         """
         if not username or not password:
@@ -139,7 +141,7 @@ def _load_credentials(self):
         it as a JSON and return credentials from it.
 
         :return: Tuple of username and password loaded from file.
-        :raise FileNotFoundError: If credentials file cannot be found.
+        :raise .FileNotFoundError: If credentials file cannot be found.
         """
         credentials_file = self._credentials_file
 
@@ -313,18 +315,21 @@ def get_cache(self, wp):
     def get_trackable(self, tid):
         """Return a :class:`.Trackable` object by its trackable ID.
 
-        :param str wp: Trackable ID.
+        :param str tid: Trackable ID.
         """
         return Trackable(self, tid)
 
-    def post_log(self, wp, text, type=LogType.found_it, date=datetime.date.today()):
+    def post_log(self, wp, text, type=LogType.found_it, date=None):
         """Post a log for cache.
 
         :param str wp: Cache waypoint.
         :param str text: Log text.
         :param .log.Type type: Type of log.
-        :param datetime.date date: Log date.
+        :param datetime.date date: Log date. If set to :code:`None`, :meth:`datetime.date.today`
+            is used instead.
         """
+        if not date:
+            date = datetime.date.today()
         l = Log(type=type, text=text, visited=date)
         self.get_cache(wp).post_log(l)
 

pycaching/log.py

@@ -124,7 +124,7 @@ class Type(enum.Enum):
     def from_string(cls, name):
         """Return a log type from its human readable name.
 
-        :raise ValueError: If log type cannot be determined.
+        :raise .ValueError: If log type cannot be determined.
         """
         name = name.strip().lower()
 

pycaching/trackable.py

@@ -160,7 +160,7 @@ def load(self):
            This method is called automatically when you access a property which isn't yet filled in
            (so-called "lazy loading"). You don't have to call it explicitly.
 
-        :raise LoadError: If trackable loading fails (probably because of not existing cache).
+        :raise .LoadError: If trackable loading fails (probably because of not existing cache).
         """
         # pick url based on what info we have right now
         if hasattr(self, "url"):

setup.py

@@ -38,10 +38,10 @@ def run(self):
 
 root = os.path.dirname(__file__) or "."
 
-with open(os.path.join(root, "README.rst")) as f:
+with open(os.path.join(root, "README.rst"), encoding="utf-8") as f:
     long_description = f.read()
 
-with open(os.path.join(root, "requirements.txt")) as f:
+with open(os.path.join(root, "requirements.txt"), encoding="utf-8") as f:
     requirements = list(filter(None, (row.strip() for row in f)))
 
 info = {
@@ -61,4 +61,5 @@ def run(self):
     "cmdclass":            {"test": NoseTestCommand, "lint": LintCommand},
 }
 
-setup(**info)
+if __name__ == "__main__":
+    setup(**info)