ripariancommit merge - Documentation

[ripariancommit]

This patchset is a merge of my documentation feature branch. It is based on the same refs as #23, and they represent the first 14 commits.

Changes

• Adds sphinx-based project documentation under the :docs/ directory.
  • For API documentation, I primarily rely on the sphinx autodoc plugin.
  • You can check out the published docs on my repo (https://ripariancommit.github.io/rule34Py/index.html), if it helps to review the contents.
• Adds complete module, class, and method documentation throughout the rule34Py package, in the Google python style.
• Adds a top-level Makefile, to provide easier entrypoints for building the project, running the tests, and linting.
• Moves developer-focused user content either into a new Developer Guide (in the docs) or a Contributing Guide (in the docs).
• Deprecates the old docs README.
• Converts the downloader example into a tutorial in the docs.
• Adds a PR check github workflow, that should check that each repo PR builds the docs.
  • Naturally, I intend to extend this into running the unit tests and whatever other PR validation we want to do.
• Adds a gh-pages workflow to build and publish the GH pages on each push (or merge) into the master ref.
• Adds a linter - ruff - which seems to be the new hotness in python linting, and was helpful to lint my docstrings.
  • At the moment, I only have the documentation-related rules enabled. But I will enable the others in future patchsets.
• Adds a user-guide for how to clear Cloudflare captchas using the featuers in Revitalize the client module (part 2 / 2) #23.

No changelog changes for this PR - because nothing here should impact users.

Testing

This patchset does not contain any intentional functional changes to the core module (apart from the contents of patchset #23).

• With this change, all existing unit tests still pass.

(.venv) [0] $ make check
PYTHONPATH=rule34Py/.. python3 -m pytest tests/unit/
==================================================================== test session starts =====================================================================
platform linux -- Python 3.13.2, pytest-8.3.5, pluggy-1.5.0 -- <snip>/rule34Py/.venv/bin/python3
cachedir: .pytest_cache
rootdir: <snip>/rule34Py/tests
configfile: pytest.ini
collected 29 items                                                                                                                                           

tests/unit/test_html.py::test_ICamePage_init PASSED                                                                                                    [  3%]
tests/unit/test_html.py::test_ICamePage_top_chart_from_html PASSED                                                                                     [  6%]
tests/unit/test_html.py::test__PoolHistoryPage__events_from_html PASSED                                                                                [ 10%]
tests/unit/test_html.py::test__PoolPage__pool_from_html PASSED                                                                                         [ 13%]
tests/unit/test_html.py::test_TagMapPage_init PASSED                                                                                                   [ 17%]
tests/unit/test_html.py::test_TagMapPage_map_points_from_html PASSED                                                                                   [ 20%]
tests/unit/test_html.py::test_TopTagsPage PASSED                                                                                                       [ 24%]
tests/unit/test_html.py::test_TopTagsPage_top_tags_from_html PASSED                                                                                    [ 27%]
tests/unit/test_module.py::test_version PASSED                                                                                                         [ 31%]
tests/unit/test_readme.py::test_module_import PASSED                                                                                                   [ 34%]
tests/unit/test_readme.py::test_get_comments PASSED                                                                                                    [ 37%]
tests/unit/test_readme.py::test_get_post PASSED                                                                                                        [ 41%]
tests/unit/test_readme.py::test_icame PASSED                                                                                                           [ 44%]
tests/unit/test_readme.py::test_search PASSED                                                                                                          [ 48%]
tests/unit/test_readme.py::test_get_pool PASSED                                                                                                        [ 51%]
tests/unit/test_rule34Py.py::test_rule34Py_get_comments PASSED                                                                                         [ 55%]
tests/unit/test_rule34Py.py::test_rule34Py_get_pool PASSED                                                                                             [ 58%]
tests/unit/test_rule34Py.py::test_rule34Py_get_post PASSED                                                                                             [ 62%]
tests/unit/test_rule34Py.py::test_rule34Py_icame PASSED                                                                                                [ 65%]
tests/unit/test_rule34Py.py::test_rule34Py_iter_search PASSED                                                                                          [ 68%]
tests/unit/test_rule34Py.py::test__rule34Py__user_agent PASSED                                                                                         [ 72%]
tests/unit/test_rule34Py.py::test_rule34Py_random_post PASSED                                                                                          [ 75%]
tests/unit/test_rule34Py.py::test_rule34Py_random_post_id PASSED                                                                                       [ 79%]
tests/unit/test_rule34Py.py::test__rule34Py__request_limiter PASSED                                                                                    [ 82%]
tests/unit/test_rule34Py.py::test_rule34Py_search PASSED                                                                                               [ 86%]
tests/unit/test_rule34Py.py::test_rule34Py_tag_map PASSED                                                                                              [ 89%]
tests/unit/test_rule34Py.py::test_rule34Py_tagmap PASSED                                                                                               [ 93%]
tests/unit/test_rule34Py.py::test_rule34Py_top_tags PASSED                                                                                             [ 96%]
tests/unit/test_rule34Py.py::test_rule34Py_version PASSED                                                                                              [100%]

==================================================================== 29 passed in 26.05s =====================================================================

Process

1. This patchset should be pulled after Revitalize the client module (part 2 / 2) #23 . If necessary I can rebase it after the former is merged, to make pulling easier.
2. Before this patchset is merged, @b3yc0d3 should go into the mainline repo settings and enable the github pages feature. Then, on-merge I think the gh-pages workflow trigger in it should activate and automatically publish the gh-pages content to the gh-pages ref as on my repo. I didn't have to do anything else with tokens or otherwise. It just worked. :)