Docs basically done, need to revamp listentry interface probablyHEADmaster

2 files changed, 202 insertions, 12 deletions

diff --git a/docs/conf.py b/docs/conf.py
index 760ad19..0ac5971 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -29,11 +29,18 @@ exclude_patterns = ['*~']
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = 'sphinxdoc'
+html_theme_options = {
+  'sidebarwidth': 300
+}
+
 html_static_path = ['_static']
 
 python_display_short_literal_types = True
 
-intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
+intersphinx_mapping = {
+  'python': ('https://docs.python.org/3', None),
+  'requests': ('https://requests.readthedocs.io/en/latest/', None)
+}
 
 doctest_global_setup = """
 import bbss
diff --git a/docs/index.rst b/docs/index.rst
index 963c702..8e82f55 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -35,6 +35,11 @@ bbss.site
 
          Whether the site was generated from a default directory, or a user-supplied one
 
+      .. py:attribute:: root
+         :type: str
+
+         The base URL of the BBSS directory
+
       .. py:attribute:: has_sizes_txt
          :type: bool
 
@@ -50,6 +55,21 @@ bbss.site
 
          A list of friend sites found at the site
 
+     .. doctest::
+
+       >>> site = bbss.site.Site('aleteoryx.me')
+       >>> for size in site.sizes:
+       ...   print(f"{size.entry} @ {size.url()}")
+       ...   if size.exists():
+       ...     for button in size.get():
+       ...       print(f"===> {button.entry} @ {button.url()}")
+       ...   else:
+       ...     print("...doesn't seem to exist!")
+       ...
+       88x31 @ https://aleteoryx.me/BBSS/88x31/list.txt
+       ===> ame.gif @ https://aleteoryx.me/BBSS/88x31/ame.gif
+       ===> amev2.gif @ https://aleteoryx.me/BBSS/88x31/amev2.gif
+
 bbss.lists
 ==========
 
@@ -81,7 +101,7 @@ bbss.lists
 
    .. py:class:: ListFileEntry(entry, comment)
 
-      The base class for all listfile entries.
+      The base class for all listfile entries
 
       :param str entry: The main content of the entry
       :param comment: The comment, if present
@@ -89,7 +109,7 @@ bbss.lists
 
    .. py:class:: BaseListFile(contents)
 
-      The base class for all listfile representations.
+      The base class for all listfile representations
 
       It supports all the :py:class:`collections.abc.Sequence` operations, meaning it can be used like a list in most cases.
 
@@ -105,20 +125,12 @@ bbss.lists
 
    .. py:class:: ListFile(contents)
 
-      A representation of an arbitrary listfile.
+      A representation of an arbitrary listfile
 
       It supports all the :py:class:`collections.abc.Sequence` operations, meaning it can be used like a list in most cases.
 
       :param str contents: The contents of the source listfile
 
-      .. py:classmethod:: from_url(url)
-
-         Alternate constructor, which will attempt to download the listfile at ``url``.
-
-         :param str url: The URL to download from.
-         :return: A representation of the remote file, if available
-         :rtype: BaseListFile | None
-
       .. doctest::
 
          >>> contents = """
@@ -140,6 +152,177 @@ bbss.lists
            ``this is a comment on entry two''
          > entry 3
 
+      .. py:classmethod:: from_url(url)
+
+         Alternate constructor, which will attempt to download the listfile at ``url``.
+
+         :param str url: The URL to download from.
+         :return: A representation of the remote file, if available
+         :rtype: BaseListFile | None
+
+bbss.buttons
+============
+
+.. py:module:: bbss.buttons
+
+   .. py:class:: ButtonListFileEntry(entry, comment, root)
+
+      A representation of a button image
+
+      :param str entry: The button's filename
+      :param comment: The comment for this button
+      :type comment: str or None
+      :param str root: The URL that this button is a child of
+
+      .. py:method:: url()
+
+         :return: The URL of the button file
+         :rtype: str
+
+      .. py:method:: exists()
+
+         :return: Whether the button actually exists on the server
+         :rtype: bool
+
+      .. py:method:: get()
+
+         :return: The HTTP response from trying to ``GET`` the button
+         :rtype: requests.Response
+
+   .. py:class:: ButtonListFile(contents)
+
+      A representation of a list of buttons
+
+      It supports all the :py:class:`collections.abc.Sequence` operations, meaning it can be used like a list in most cases.
+
+      :param str contents: The contents of the source listfile
+
+      .. py:classmethod:: from_url(url)
+
+         Alternate constructor, which will attempt to download the listfile at ``url``.
+
+         :param str url: The URL to download from.
+         :return: A representation of the remote button list, if available
+         :rtype: ButtonListFile | None
+
+         .. doctest::
+
+            >>> buttons = bbss.buttons.ButtonListFile \
+            ...             .from_url("https://aleteoryx.me/BBSS/88x31/list.txt")
+            >>> for button in buttons:
+            ...   print(button.url())
+            ...
+            https://aleteoryx.me/BBSS/88x31/ame.gif
+            https://aleteoryx.me/BBSS/88x31/amev2.gif
+
+bbss.sizes
+============
+
+.. py:module:: bbss.sizes
+
+   .. py:class:: SizeListFileEntry(entry, comment, root)
+
+      A representation of a given size for buttons
+
+      :param str entry: The actual size
+      :param comment: The comment for this size
+      :type comment: str or None
+      :param str root: The BBSS directory that this size is within
+
+      .. py:method:: url()
+
+         :return: The URL of the size's button list
+         :rtype: str
+
+      .. py:method:: exists()
+
+         :return: Whether the size's button list file exists
+         :rtype: bool
+
+      .. py:method:: get()
+
+         :return: The actual button list, if available
+         :rtype: bbss.buttons.ButtonListFile
+
+      .. py:method:: dims()
+
+         :return: The dimensions of the size, ``(x, y)``, if they can be parsed from the name
+         :rtype: (int, int) or None
+
+   .. py:class:: SizeListFile(contents)
+
+      A representation of a list of button sizes
+
+      It supports all the :py:class:`collections.abc.Sequence` operations, meaning it can be used like a list in most cases.
+
+      :param str contents: The contents of the source listfile
+
+      .. py:classmethod:: from_url(url)
+
+         Alternate constructor, which will attempt to download the listfile at ``url``
+
+         :param str url: The URL to download from.
+         :return: A representation of the remote size list, if available
+         :rtype: ButtonListFile | None
+
+bbss.friends
+============
+
+.. py:module:: bbss.friends
+
+   .. py:class:: FriendListFileEntry(entry, comment)
+
+      A representation of a friend site
+
+      :param str entry: The actual size
+      :param comment: The comment for this size
+      :type comment: str or None
+
+      .. py:attribute:: url
+         :type: str
+
+         The URL of the size's button list
+
+      .. py:attribute:: domain
+         :type: str
+
+         The domain of the friend site
+
+      .. py:attribute:: scheme
+         :type: str
+
+         The scheme of the friend site
+
+      .. py:attribute:: path
+         :type: str
+
+         The optional path of the remote BBSS directory
+
+      .. py:method:: exists()
+
+         :return: Whether the size's button list file exists
+         :rtype: bool
+
+      .. py:method:: get()
+
+         :return: The remote site
+         :rtype: bbss.site.Size
+
+   .. py:class:: FriendListFile(contents)
+
+      A representation of a list of friend sites
+
+      It supports all the :py:class:`collections.abc.Sequence` operations, meaning it can be used like a list in most cases.
+
+      :param str contents: The contents of the source listfile
+
+      .. py:classmethod:: from_url(url)
+
+         Alternate constructor, which will attempt to download the listfile at ``url``
+
+         :param str url: The URL to download from.
+         :return: A representation of the remote friend list, if available
+         :rtype: ButtonListFile | None
 
 ==================
 Indices and tables