Playing a 2018 remaster of the 2004 release of Bard's Tale IV and it's not doing my rapid-onset carpal tunnel syndrome any favors. What starts out as a tawdry adventure of bilking barmaids and insulting the locals turns into a cross-country dungeon crawl filled with smart-assery and song-and-dance numbers. It's worth suffering through the adolescent parts to get to the ending. Even remastered and run on recent hardware, it still lags like hell during certain visual effects. The second playthrough, you see a ton of telegraphing the ending but it's still very satisfying see the endgame play out.
I spent a few hours restructuring my languishing Python Proficiency Exam. Locked down dependencies and managed the virtual environment with Poetry (Python package names are essentially random making finding a package that does <X> needlessly difficult). Still trying to get sphinx configs arranged properly so I can generate docs from the source code. Python package structure is also effectively random and unnecessarily difficult. "Flat is better than nested" is an excuse to dump everything in a pile, like teenager's laundry. "There should be one-- and preferably only one --obvious way to do it." doesn't apply to project directory structure, build, test, and auxiliary tools, or their configuration.
Whatever. I have sphinx autodoc almost configured; it really expects all your source to be in a single laundry pile and telling it how to find structured sources is elusive. I punted for tonight after marginal progress; at least the project dir doesn't look like it was ravaged by looters
With fresh eyes and a web search, I've unsatisfactorily worked around Sphinx's inability to autodocument my source tree.
The workaround came from SO: https://stackoverflow.com/questions/74787850/generating-documentation-for-multiple-folders-with-sphinx
Props to the OP for documenting how they modified their setup.
Now, the bad parts:
1) This is a typical Cargo Cult solution. I just did what someone else did, nobody can explain how it works, but it does so now I perform this ritual act in order that the Big Silver Bird brings us riches. Praise John Frum!
2) Reviewer #1 writes: "sphinx and Python projects are usually structured with a common package name [...] and subpackages are created under it as necessary [...]. The structure shown above departs from the standard, so it might be trickier than usual to get this working."
Is there a reference to this standard because I have been searching for one for about a decade and have not found anything resembling a standard project directory tree. Providing a configurable default tree is more than simple courtesy - sphinx and many other tools assume a particular project tree structure and - as in this case - don't provide clear up-front guidance on how to configure the tool to handle projects that don't have the implied standard structure.
Depending on the author's preferred build/packaging setup tool (snerk), there are *some* common layouts for libraries.
For actual tools/apps/whatever that one is supposed to be able to download and actually use, not so much.
If you do find one that isn't complete head-up-arse gibberish, I'd love to see it.
@nullifidian IIRC cookiecutter has a whole library of project configurations. There's still no default, sensible or otherwise. Both PyScaffold and cookiecutter are third-party tools, not part of language core, and neither of them explain what they're going to do before they do it. I suppose they're great if you already have a project convention but (last I used them), neither give you any guidance as to which layout is better for certain projects. Python has Opinions about everything else - why not this?