aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authoralyx <alyx@aleteoryx.me>2023-12-24 17:12:56 -0500
committeralyx <alyx@aleteoryx.me>2023-12-24 17:12:56 -0500
commitdefde6070677e806c40d5891543848fcb2001ef5 (patch)
tree20a0a3976a0c7b522aef35d4298dcd951bed4b99 /docs
parent48f62aba8db8efe3a109837cda52d04b1b9aad5b (diff)
downloadbbss.py-defde6070677e806c40d5891543848fcb2001ef5.tar.gz
bbss.py-defde6070677e806c40d5891543848fcb2001ef5.tar.bz2
bbss.py-defde6070677e806c40d5891543848fcb2001ef5.zip
bbss.lists documented, doctests setup
Diffstat (limited to 'docs')
-rw-r--r--docs/conf.py18
-rw-r--r--docs/index.rst131
2 files changed, 124 insertions, 25 deletions
diff --git a/docs/conf.py b/docs/conf.py
index a851995..760ad19 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -2,7 +2,6 @@ import sys
import pathlib
sys.path.append(str(pathlib.PurePath(__file__).parent.parent.joinpath('src')))
-print(sys.path)
# Configuration file for the Sphinx documentation builder.
@@ -21,15 +20,26 @@ release = '0.1.0'
# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
-extensions = ['sphinx.ext.autodoc']
+extensions = ['sphinx.ext.doctest', 'sphinx.ext.intersphinx']
templates_path = ['_templates']
exclude_patterns = ['*~']
-autodoc_default_options = { "members": None }
-
# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
html_theme = 'sphinxdoc'
html_static_path = ['_static']
+
+python_display_short_literal_types = True
+
+intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
+
+doctest_global_setup = """
+import bbss
+import bbss.lists
+import bbss.buttons
+import bbss.friends
+import bbss.site
+import bbss.sizes
+"""
diff --git a/docs/index.rst b/docs/index.rst
index ec56a5d..963c702 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -18,39 +18,128 @@ bbss.site
.. py:module:: bbss.site
-.. py:class:: Site(domain: str[, path: str[, *, scheme: str = 'https']])
+ .. py:class:: Site(domain, path, *, scheme = 'https')
- `domain`
- The domain to check for BBSS files
+ A representation of some BBSS directory. On construction, all information about an individual site
+ is downloaded.
- `path`
- An optional subdirectory to treat as the root of the BBSS directory
+ :param str domain: The domain to check for BBSS files
- `scheme`
- What protocol to download over; can be either :python:`'http'` or :python:`'https'`
+ :param path: An optional subdirectory to treat as the root of the BBSS directory
+ :type path: str or None
+ :param scheme: What protocol to download over
+ :type scheme: 'http' | 'https'
- A representation of some BBSS directory. On construction, all information about an individual site
- is downloaded.
+ .. py:attribute:: default_path
+ :type: bool
- .. py:attribute:: default_path
- :type: bool
+ Whether the site was generated from a default directory, or a user-supplied one
- Whether the site was generated from a default directory, or a user-supplied one
+ .. py:attribute:: has_sizes_txt
+ :type: bool
- .. py:attribute:: has_sizes_txt
- :type: bool
+ Whether the BBSS directory contains a ``sizes.txt`` file
- Whether the BBSS directory contains a :code:`sizes.txt` file
+ .. py:attribute:: sizes
+ :type: bbss.sizes.SizeListFile
- .. py:attribute:: sizes
- :type: bbss.sizes.SizeListFile
+ A list of the sizes found at the site
- A list of the sizes found at the site
+ .. py:attribute:: friends
+ :type: Optional[bbss.friends.FriendListFile]
- .. py:attribute:: friends
- :type: Optional[bbss.friends.FriendListFile]
+ A list of friend sites found at the site
+
+bbss.lists
+==========
+
+.. py:module:: bbss.lists
+
+ .. py:function:: parse_listfile[T](contents, ctor)
+
+ Parses in the text of a listfile, and calls the passed constructor
+ function repeatedly to generate datastructures.
+
+ :param str contents: The contents of the listfile
+ :param ctor: The constructor for the internal datastructures
+ :type ctor: (str, str or None) -> T
+ :return: A list of T, containing the contents of the file
+ :rtype: list[T]
+
+ .. doctest::
+
+ >>> listfile = """
+ ... entry 1
+ ... ## this is a comment on entry two
+ ... entry 2
+ ... # omitted
+ ... entry 3
+ ... ## trailing comments are ignored
+ ... """
+ >>> bbss.lists.parse_listfile(listfile, lambda x, y: (x, y))
+ [('entry 1', None), ('entry 2', 'this is a comment on entry two'), ('entry 3', None)]
+
+ .. py:class:: ListFileEntry(entry, comment)
+
+ The base class for all listfile entries.
+
+ :param str entry: The main content of the entry
+ :param comment: The comment, if present
+ :type comment: str or None
+
+ .. py:class:: BaseListFile(contents)
+
+ 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.
+
+ :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
+
+ .. py:class:: ListFile(contents)
+
+ 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 = """
+ ... entry 1
+ ... ## this is a comment on entry two
+ ... entry 2
+ ... # omitted
+ ... entry 3
+ ... ## trailing comments are ignored
+ ... """
+ >>> listfile = bbss.lists.ListFile(contents)
+ >>> for entry in listfile:
+ ... print(">", entry.entry)
+ ... if entry.comment is not None:
+ ... print(f" ``{entry.comment}''")
+ ...
+ > entry 1
+ > entry 2
+ ``this is a comment on entry two''
+ > entry 3
- A list of friend sites found at the site
==================
Indices and tables