At the Mountains of Tech Debt: Refactor our API doc generation script to be readable (#2109)

* Spacing cleanup

* Use contextlib.suppress instead except: pass

* Actually use the glob argument in Vfs.delete_glob

* Clearly document history and intent of vfs.py

* Add a top-level docstring explaining the build loop

* Add docstrings explaining intended usage in build scripts for IDE users

* Use StringIO instead of repeatedly concatenating strings

* Readability fixes for process_directory & imports

* Split and comment dir and file mappings in process_directory

* Make print statement include variable names

* Centralize & DRY update_quick_index.py Path consts

* ROOT -> REPO_ROOT

* Add ARCADE_ROOT constant

* Centralize the API doc folder into API_DOC_DIR constant

* Add Vfs.open_ctx for familiar with block syntax

* Move file inclusion into VirtualFile

* Add VirtualFile.include_file

* Replace usage of include_template in update_quick_index.py

* Remove include_template

* DRY the shared paths for utils into vfs.py

* Move shared paths into a utility class in vfs.py

* Comment the sys.path.insert lines explaining why we have those

* Use imports in existing scripts

* Improve Vfs deletion clarity with rename + doc

* Rename delete_glob

* Rephrase docstring to be clearer

* Remove extra str wrapping the shared API_DOC_DIR path

* Use future-style str | Path in Vfs

* Use future-style | annotations for paths

* Remove Union import

* Some commenting and reordering of files to match display order in API reference

* Whitespace

* Understandability helpers

* Move a dir from file_mapping to dir_mapping

* comment on awfulness

* enumerate start keyword trick

* Type-passing as a nasty tempt trick since we only write one type for now

* More clarification of nasty source

* Type tweak in vfs.py

* Annotate and comment Vfs.exists

* Comment out GL stuff that isn't actually used

* Typo fix

* Un-specialcase arcade.ArcadeContext in directory processing

* Move re-used constant dicts to top level instead of re-delcaring each iteration

* Fix scoping nonsense

* Remove top-level function used only once

* Fix ArcadeContext doc rendering

* Fix name in special casing rules

* Fix rendering indent

* Move the member up with the OpenGL commented out lines

* Use multiple assign instead of complex indexing chain

* Add some comments on structuring for dev purposes

* Remove commented-out GL items

* Use filter to simplify item skipping

* Add exclusion helper callable class

* Make exclusion list constant cased

* Use filter + callables to remove indent level and simplify code

* Simplify mega-if line

* Use empty tuple instead of recreating empty list

* Move confusingly named constant to main + dedent call

* Move quick index path to top-level constant

* Be explicitly clear about file modes in Vfs

* Stop passing in stuff we can get with .open(path, "a")

* Remove quick index file from signature of process_directory

* Use with block context manager in main()

* open(QUICK_INDEX_PATH, "a") inside process_directory

* Fix typo in Vfs logic

* Fix top-level scope of script

* Move main() call into if __name__ == "__main__" check

* Pass vfs into proces_directory

* Update process_directory docstring

* Clean up imports

* Remove mention of drawing support module

* Move regexes to top level constants

* Remove special-casing for type regexes

* Use negative lookahead feature in TYPE_RE

* Remove the if check making regexes non-interchangeable

* Make get_member_list configurable via keyword arg

* Add passable expressions via member_expressions keyword arg

* Change return type to a dict instead of named tuple

* Replace usage in process_directory

* Use Mapping of name -> Pattern instead of named groups

* Remove named group validation and enforcement

* Update docstring

* Refactor update_quick_index.py to use legible conf

* Add simple get_module_path function

* Rename declarations function to get_file_declarations

* Update get_file_declarations docstring

* Comment out type expression in defaults for now since we can't render those yet

* Fix broken declarations out and comment out ambiguous ones

* Remove apparent obsolete items fro mthe quick index config

* Expose Camera2D's page in the API doc

* Revert path changes to create_resources_listing.py

* Correct import path comment

* Cleanup + attempt to get things workinging fully

* Remove extra whitespace

* Comment fixes

* Path fixes for Vfs + update_quick_index.py

* Typo fix and phrasing for get_file_declarations

Author: pushfoo

doc/api_docs/arcade.rst

@@ -17,6 +17,7 @@ for the Python Arcade library. See also:
     api/drawing_primitives
     api/drawing_batch
     api/sprites
+    api/camera_2d
     api/sprite_list
     api/sprite_scenes
     api/text

util/create_resources_listing.py

@@ -7,8 +7,10 @@
 from pathlib import Path
 from typing import List
 
+# Ensure we get utility and arcade imports first
 sys.path.insert(0, str(Path(__file__).parent.resolve()))
 sys.path.insert(0, str(Path(__file__).parent.parent.resolve()))
+
 import arcade
 from vfs import Vfs