Make docstrings use the Google docstring format, instead of pure Sphinx (much nicer)

Author: DanielOaks

basc_py4chan/board.py

@@ -10,8 +10,23 @@ def get_boards(board_name_list, *args, **kwargs):
     return [Board(name, *args, **kwargs) for name in board_name_list]
 
 class Board(object):
+    """Represents a 4chan board.
+
+    Attributes:
+        name (str): Name of this board, such as ``tg`` or ``k``
+    """
     def __init__(self, board_name, https=False, clean_comments=True,
                  api_url=URL['api'], session=None):
+        """Creates a :mod:`basc_py4chan.Board` object.
+
+        Args:
+            board_name (string): Name of the board, such as "tg" or "etc".
+            https (bool): Whether to use a secure connection to 4chan.
+            clean_comments (bool): Whether post objects will try to parse HTML comments
+                (HTML entities, tags and links) into "cleaned" plaintext.
+            api_url: Base 4chan API URL. This will be automatically set in all cases.
+            session: Existing requests.session object to use instead of our current one.
+        """
         self._board_name = board_name
         self._protocol = 'https://' if https else 'http://'
         self._clean_comments = clean_comments
@@ -33,12 +48,14 @@ def _get_json(self, path):
         return res.json()
 
     def get_thread(self, thread_id, update_if_cached=True):
-        """
-            Get a thread from 4chan via 4chan API.
+        """Get a thread from 4chan via 4chan API.
+
+        Args:
+            thread_id (int): Thread ID
+            update_if_cached (bool): Whether the thread should be updated if it's already in our cache
 
-            :param thread_id: Thread ID
-            :param update_if_cached: Should the thread be updated if it's found in the cache?
-            :return: Thread
+        Returns:
+            :class:`basc_py4chan.Thread`: Thread object
         """
         if thread_id in self._thread_cache:
             thread = self._thread_cache[thread_id]
@@ -55,11 +72,13 @@ def get_thread(self, thread_id, update_if_cached=True):
         return thread
 
     def thread_exists(self, thread_id):
-        """
-            Check if a thread exists, or is 404.
+        """Check if a thread exists or has 404'd.
 
-            :param thread_id: Thread ID
-            :return: bool
+        Args:
+            thread_id (int): Thread ID
+
+        Returns:
+            bool: Whether the given thread exists on this board.
         """
         return self._requests_session.head(self._thread_path % thread_id).ok
 
@@ -96,38 +115,48 @@ def _request_threads(self, page):
         return threads
 
     def get_threads(self, page=1):
-        """
-            Get all threads on a certain page. Pages are now indexed at 1, instead of 0.
-            If the thread is already in cache, return cached thread entry.
+        """Returns all threads on a certain page.
+
+        Gets a list of Thread objects for every thread on the given page. If a thread is
+        already in our cache, the cached version is returned and thread.want_update is
+        set to True on the specific thread object.
+
+        Pages on 4chan are indexed from 1 onwards.
+
+        Args:
+            page (int): Page to request threads for. Defaults to the first page.
 
-            Sets thread.want_update to True if the thread is being returned from the cache.
-            :param: page: Page to fetch thread from
-            :return: list[Thread]
+        Returns:
+            list: List of Thread objects representing the threads on the given page.
         """
         return self._request_threads(page)
 
     def get_all_thread_ids(self):
-        """
-            Return a list of all thread IDs.
+        """Return the ID of every thread on this board.
 
-            :return: list[int]
+        Returns:
+            list: List of IDs of every thread on this board.
         """
         json = self._get_json(ALL_THREADS)
         return [thread['no'] for page in json for thread in page['threads']]
 
     def get_all_threads(self, expand=False):
-        """
-            Return all threads on all pages.
+        """Return every thread on this board.
+
+        If not expanded, result is same as get_threads run across all board pages,
+        with last 3-5 replies included.
 
-            If not expanded, result is same as get_threads run across all board pages,
-            with last 3-5 replies included.
+        Uses the catalog when not expanding, and uses the flat thread ID listing
+        at /{board}/threads.json when expanding for more efficient resource usage.
 
-            Uses the catalog when not expanding, and uses the flat thread ID listing
-            at /{board}/threads.json when expanding for more efficient resource usage.
+        If expanded, all data of all threads is returned with no omitted posts.
 
-            If expanded, all data of all threads is returned with no omitted posts.
-            :param: expand: Whether or not to expand threads
-            :return: list[Thread]
+        Args:
+            expand (bool): Whether to download every single post of every thread.
+                If enabled, this option can be very slow and bandwidth-intensive.
+
+        Returns:
+            list: List of Thread objects representing every thread on this board.
         """
         if not expand:
             return self._request_threads(CATALOG)
@@ -138,27 +167,19 @@ def get_all_threads(self, expand=False):
         return filter(None, threads)
 
     def refresh_cache(self, if_want_update=False):
-        """
-            Update all threads currently stored in the cache.
-        """
+        """Update all threads currently stored in our cache."""
         for thread in self._thread_cache.values():
             if if_want_update:
                 if not thread.want_update:
                     continue
             thread.update()
 
     def clear_cache(self):
-        """
-            Remove everything currently stored in the cache.
-        """
+        """Remove everything currently stored in our cache."""
         self._thread_cache.clear()
 
     @property
     def name(self):
-        """
-            Board name that this board represents.
-            :return: string
-        """
         return self._board_name
 
     def __repr__(self):

docs/conf.py

@@ -13,6 +13,16 @@
 
 import sys, os
 
+# on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org
+on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+
+if not on_rtd:  # only import and set the theme if we're building docs locally
+    import sphinx_rtd_theme
+    html_theme = 'sphinx_rtd_theme'
+    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
+# otherwise, readthedocs.org uses their theme by default, so no need to specify it
+
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
@@ -26,7 +36,7 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.coverage', 'sphinx.ext.autodoc', 'sphinx.ext.viewcode']
+extensions = ['sphinx.ext.coverage', 'sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinxcontrib.napoleon']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -92,7 +102,7 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+# html_theme = 'default'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

docs/index.rst

@@ -1,21 +1,14 @@
-.. BASC-py4chan documentation master file, created by
-   sphinx-quickstart on Fri Dec  5 08:19:29 2014.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+BASC-py4chan - 4chan Python Library
+===================================
+BASC-py4chan is a Python library that gives access to the 4chan API and an object-oriented way to browse and get board and thread information quickly and easily.
 
-Welcome to BASC-py4chan's documentation!
-========================================
+Originally written by `Edgeworth <https://github.com/e000/py-4chan>`_, the library has been adopted and extended by `Bibliotheca Anonoma <https://github.com/bibanon>`_.
+
+We're currently writing up the documentation for this module, so stick with us while we flesh out the library documentation and the rest of it!
 
 Contents:
 
 .. toctree::
    :maxdepth: 2
 
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-
+   library/board

docs/library/board.rst

@@ -16,6 +16,20 @@ Here is a sample application that grabs and uses Board information, :file:`examp
 .. module:: basc_py4chan
 .. autoclass:: basc_py4chan.Board
 
+    .. automethod:: basc_py4chan.Board.__init__
+
     .. automethod:: basc_py4chan.Board.thread_exists
 
     .. automethod:: basc_py4chan.Board.get_thread
+
+    .. automethod:: basc_py4chan.Board.get_threads
+
+    .. automethod:: basc_py4chan.Board.get_all_threads
+
+    .. automethod:: basc_py4chan.Board.get_all_thread_ids
+
+    .. automethod:: basc_py4chan.Board.refresh_cache
+
+    .. automethod:: basc_py4chan.Board.clear_cache
+
+    .. autoattribute:: basc_py4chan.Board.name

requirements.txt

@@ -1 +1,2 @@
 requests
+sphinxcontrib-napoleon