From 48f62aba8db8efe3a109837cda52d04b1b9aad5b Mon Sep 17 00:00:00 2001 From: alyx Date: Sun, 24 Dec 2023 02:25:26 -0500 Subject: Fixed import cycle, began on docs. --- .gitignore | 2 ++ docs/Makefile | 20 +++++++++++++++++ docs/conf.py | 35 ++++++++++++++++++++++++++++++ docs/index.rst | 61 ++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/make.bat | 35 ++++++++++++++++++++++++++++++ src/bbss/__init__.py | 2 ++ src/bbss/buttons.py | 2 +- src/bbss/friends.py | 10 ++++----- src/bbss/site.py | 16 +++++++------- src/bbss/sizes.py | 4 ++-- 10 files changed, 171 insertions(+), 16 deletions(-) create mode 100644 docs/Makefile create mode 100644 docs/conf.py create mode 100644 docs/index.rst create mode 100644 docs/make.bat diff --git a/.gitignore b/.gitignore index 16edc5d..3bef7b8 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,5 @@ *~ /dist __pycache__ +_build +*.swp diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..a851995 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,35 @@ +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. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'bbss.py' +copyright = '2023, Aleteoryx' +author = 'Aleteoryx' +release = '0.1.0' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = ['sphinx.ext.autodoc'] + +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'] diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..ec56a5d --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,61 @@ +.. bbss.py documentation master file, created by + sphinx-quickstart on Tue Dec 5 20:26:05 2023. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +.. role:: python(code) + :language: python + +======= +bbss.py +======= + +For more information on BBSS itself, look `here `_. +This is a simple python module to allow for quickly scraping or exploring BBSS directories on sites. + +bbss.site +========= + +.. py:module:: bbss.site + +.. py:class:: Site(domain: str[, path: str[, *, scheme: str = 'https']]) + + `domain` + The domain to check for BBSS files + + `path` + An optional subdirectory to treat as the root of the BBSS directory + + `scheme` + What protocol to download over; can be either :python:`'http'` or :python:`'https'` + + A representation of some BBSS directory. On construction, all information about an individual site + is downloaded. + + .. py:attribute:: default_path + :type: bool + + Whether the site was generated from a default directory, or a user-supplied one + + .. py:attribute:: has_sizes_txt + :type: bool + + Whether the BBSS directory contains a :code:`sizes.txt` file + + .. py:attribute:: sizes + :type: bbss.sizes.SizeListFile + + A list of the sizes found at the site + + .. py:attribute:: friends + :type: Optional[bbss.friends.FriendListFile] + + A list of friend sites found at the site + +================== +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..32bb245 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/src/bbss/__init__.py b/src/bbss/__init__.py index 98e45f5..79b2d1d 100644 --- a/src/bbss/__init__.py +++ b/src/bbss/__init__.py @@ -1,2 +1,4 @@ __all__ = ["lists", "buttons", "friends", "site", "sizes", "DEFAULT_PATHS"] DEFAULT_PATHS = ["/BBSS", "/.well-known/BBSS", "/badges", "/buttons", ""] + +from . import lists, buttons, friends, site, sizes diff --git a/src/bbss/buttons.py b/src/bbss/buttons.py index 77ddcf4..1def010 100644 --- a/src/bbss/buttons.py +++ b/src/bbss/buttons.py @@ -1,4 +1,4 @@ -from .lists import BaseListFile, ListFileEntry, parse_listfile +from bbss.lists import BaseListFile, ListFileEntry, parse_listfile from dataclasses import dataclass from typing import Optional, Self from collections.abc import Sequence diff --git a/src/bbss/friends.py b/src/bbss/friends.py index d0aa884..6afdfcd 100644 --- a/src/bbss/friends.py +++ b/src/bbss/friends.py @@ -1,6 +1,6 @@ -from .lists import BaseListFile, ListFileEntry, parse_listfile -from .site import Site -from . import DEFAULT_PATHS +from bbss.lists import BaseListFile, ListFileEntry, parse_listfile +import bbss.site as site +from bbss import DEFAULT_PATHS from dataclasses import dataclass from typing import cast, Optional from collections.abc import Sequence @@ -41,8 +41,8 @@ class FriendListFileEntry(ListFileEntry): return True return False - def get(self) -> Site: - return Site(self.domain, self.path, scheme = self.scheme) + def get(self) -> "site.Site": + return site.Site(self.domain, self.path, scheme = self.scheme) class FriendListFile(BaseListFile[FriendListFileEntry]): def __init__(self, contents: str): diff --git a/src/bbss/site.py b/src/bbss/site.py index 7e8871f..134ee8b 100644 --- a/src/bbss/site.py +++ b/src/bbss/site.py @@ -1,6 +1,6 @@ -from .sizes import SizeListFile -from .friends import FriendListFile -from . import DEFAULT_PATHS +from bbss.sizes import SizeListFile +import bbss.friends as friends +from bbss import DEFAULT_PATHS from typing import Optional from collections.abc import Sequence import requests @@ -25,17 +25,17 @@ class Site: if path is not None: if not check_path(path): - raise Exception("Oh noes there's nothing.") + raise Exception("No BBSS data found at user-supplied location!") else: - self.using_default = False + self.default_path = False else: for potential in DEFAULT_PATHS: if check_path(potential): path = potential - self.using_default = True + self.default_path = True break else: - raise Exception("Oh noes there's nothing(no path specified).") + raise Exception("No BBSS data found at default locations!") self.root = base + path @@ -46,6 +46,6 @@ class Site: self.has_sizes_txt = False self.sizes = SizeListFile("88x31", self.root) - self.friends = FriendListFile.from_url(self.root + "/friends.txt") + self.friends = friends.FriendListFile.from_url(self.root + "/friends.txt") __all__ = ["Site"] diff --git a/src/bbss/sizes.py b/src/bbss/sizes.py index 0451458..f71a94c 100644 --- a/src/bbss/sizes.py +++ b/src/bbss/sizes.py @@ -1,5 +1,5 @@ -from .lists import BaseListFile, ListFileEntry, parse_listfile -from .buttons import ButtonListFile +from bbss.lists import BaseListFile, ListFileEntry, parse_listfile +from bbss.buttons import ButtonListFile from dataclasses import dataclass from typing import Optional, Self from collections.abc import Sequence -- cgit v1.2.3-70-g09d2