Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

initial files for the quickfort blueprint library #1625

Merged
merged 3 commits into from Aug 20, 2020

Conversation

myk002
Copy link
Member

@myk002 myk002 commented Aug 16, 2020

#499
add a few small examples based on the original python quickfort examples and one large-scale end-to-end complete fort blueprint of my own design, which I've been refining for a few years now but just named "Dreamfort" now that I'm releasing it to the public. The dreamfort set of blueprints was my main test case for the packaging and usability features I've been writing recently:

  1. meta blueprints to handle sequences of related blueprints that can be applied one right after another
  2. help messages that tell the user what to do next
  3. hidden blueprints that can be executed by meta blueprints but don't clog up the quickfort list output
  4. unified orders and statistics across all the blueprints that a meta blueprint applies to coalesce the orders on the manager screen and reduce the number of redundant statistics shown to the user after a blueprint is applied.
  5. quickfort list filtering so you can just get the sequence of blueprints that you're interested in at the moment.
  6. multi-blueprint files so sets of blueprints can be packaged together in one spreadsheet sheet or .cvs file (like this one is)
  7. a blueprint addressing syntax that will work regardless of whether the blueprints are in separate sheets or one .cvs file

I'm checking in the large-scale blueprint as a .csv instead of the source .xlsx files because nobody likes binaries (or, in this case, compressed xml) in their source trees. It also gives all the blueprints the same prefix this way, which is nice. And it's half the file size.

I've made the source .xlsx files publicly accessible, with a link in the blueprint help text: https://drive.google.com/drive/folders/1iS90EEVqUkxTeZiiukVj1pLloZqabKuP?usp=sharing

The command for generating the dreamfort.csv file from the source .xlsx files is documented in the .csv file as well:
for fname in dreamfort*.xlsx; do xlsx2csv -a -E Notes -p '' $fname; done | sed 's/,*$//'

The xlsx2csv utility is from https://github.com/dilshod/xlsx2csv/

My only fear is that the example is too complex. There are several overlapping steps as different zlevels progress through development. I added a lot of help text, both as an introductory walkthrough and as "what do I do next" messages, but there may be opportunities to cut out non-essential steps to simplify. I'm looking forward to feedback on this, either in this review or from the public.

Copy link
Member

@lethosor lethosor left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it looks good. Appreciate the comments in the CSV files (and the use of CSV files here). Do those comments show up when users are working with quickfort, or do they need to inspect the file?

I may not be the best judge of what's too complicated when it comes to the blueprints themselves, so I'd be happy to get feedback from others.

@myk002
Copy link
Member Author

myk002 commented Aug 18, 2020

Do those comments show up when users are working with quickfort, or do they need to inspect the file?

Thanks! Comments show up in the quickfort list output, and messages() show up after the blueprint is run.

@myk002
Copy link
Member Author

myk002 commented Aug 18, 2020

btw, I think the buildmaster sphinx test is flaky. I've had it fail a number of times where the documentation hasn't even been touched. This PR, for example, doesn't touch any files that sphinx reads, but that's where the failure is. I can merge latest develop to force the tests to run again and see if that passes.

@lethosor
Copy link
Member

Sphinx is known to be flaky - there's one error in particular about serialization depth that comes up sometimes. It's a combination of an old Sphinx version and the Buildmaster environment, I think. GitHub Actions uses Sphinx 3, while Buildmaster uses 1.8 (due to using an older Python version). If you need a build to be re-run, @BenLubar can usually do that. Otherwise, I'll double-check any failing tests, so you don't need to worry about them - Buildmaster isn't required to pass before merging.

@lethosor lethosor merged commit 058f550 into DFHack:develop Aug 20, 2020
@lethosor lethosor added this to In progress in 0.47.04-r3 via automation Aug 21, 2020
@lethosor lethosor moved this from In progress to Done in 0.47.04-r3 Aug 21, 2020
@myk002 myk002 deleted the quickfort_library branch August 21, 2020 05:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
No open projects
0.47.04-r3
  
Done
Development

Successfully merging this pull request may close these issues.

None yet

2 participants