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: stackoverflow.com/questions/74

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.

This is absolutely maddening when you have a general development process checklist (preprocessing, build, static analysis, style checking, testing, autodocumentation, packaging, ...) and none of the tools work because they all assume different conventions depending on their release date and/or developer pique.

- Explicit is better than implicit.
- Simple is better than complex.
- Special cases aren't special enough to break the rules.
- In the face of ambiguity, refuse the temptation to guess.
- There should be one-- and preferably only one --obvious way to do it.
- If the implementation is hard to explain, it's a bad idea.

Where have I read those aphorisms before?...

Oh, right: peps.python.org/pep-0020/

Follow

@arclight

> Explicit is better than implicit.

Me: *looks at Python's type system*
Also me: 😂

Sign in to participate in the conversation
Qoto Mastodon

QOTO: Question Others to Teach Ourselves
An inclusive, Academic Freedom, instance
All cultures welcome.
Hate speech and harassment strictly forbidden.