From 0aee9169e65520a94222afeff9c1391ed8ee351a Mon Sep 17 00:00:00 2001 From: Sophie Kirschner Date: Fri, 5 May 2017 08:30:47 -0400 Subject: [PATCH] Improvements to documentation --- docs/introduction.md | 14 +++++++------- docs/modding.md | 19 ++++++++++--------- 2 files changed, 17 insertions(+), 16 deletions(-) diff --git a/docs/introduction.md b/docs/introduction.md index cfb1a2b..bfc1b11 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -6,24 +6,24 @@ The steps given here are specifically for Windows, but the procedure on other op - In order to keep everything working as smoothly as possible, you should copy your Dwarf Fortress directory to another location before messing about with PyDwarf. Navigate to the directory containing your Dwarf Fortress folder, copy it, and paste it somewhere. It may be easiest to place the copy in the same location and append `_original` to the end of the directory's name. After doing this you might, for example, have a folder at `C:/df_40_24_win` and another at `C:/df_40_24_win_original`. -- If you haven't already, you'll need to download PyDwarf and extract the archive somewhere. It much doesn't matter where, though I recommend you *don't* put it inside your Dwarf Fortress directory. The most important files located in here are named `manager.py`, which is for actually running PyDwarf, and `config.json`, for telling it precisely what to do when it runs. +- If you haven't already, you'll need to download PyDwarf and extract the archive somewhere. It much doesn't matter where, though I recommend you *don't* put it inside your Dwarf Fortress directory. The most important files located in here are named `manager.py`, which is for actually running PyDwarf, and `config.yaml`, for telling it precisely what to do when it runs. - You'll want to open the `config.yaml` file, located in PyDwarf's root directory, with a text editor such as Notepad. And then you'll be looking at a yaml file. It assigns several parameters in the format of `name: value` and the most important ones right now are the ones named `input`, `output`, `backup`, and `scripts`. You can see that most of the values are simple text, but `scripts` in particular is assigned a sequence of values. -- PyDwarf also supports json configuration files, and loading configuration from a Python module. The default places PyDwarf looks for these are `config.json` and `override.py`, respectively, located in its root directory. For examples of what these files might look like you can check out the files in `docs/config/`. +- PyDwarf also supports json configuration files, and loading configuration from a Python module. The default places PyDwarf looks for these are `config.json` and `override.py`, respectively, located in its root directory. For examples of what these files might look like you can check out the files in `docs/config/`. (But you probably don't need to worry about this.) - Set the value for `input`, which is a file path, to the location of that copy of Dwarf Fortress you made in a previous step. This tells PyDwarf where to read your files from so that they can be worked upon by various mods. For example, this file path might be something like `C:/df_40_24_win_original`. -- And set the value for `output`, which is also a file path, to the location of the Dwarf Fortress folder that you play with. This is where PyDwarf will write your files to when it's finished modifying them. This path might look like `C:/df_40_24_win`. +- And set the value for `output`, which is also a file path, to the location of the Dwarf Fortress folder that you play with. This is where PyDwarf will write your files to when it's finished modifying them. This path might look like `C:/df_40_24_win`. You need to have separate input and output directories because *PyDwarf's changes to the output directory cannot be undone!* You need the original folder in case you don't like PyDwarf's changes, or in case you want to re-run PyDwarf with different settings. -- As well as the value for `backup`, another file path, to somewhere for the Dwarf Fortress files to be backed up to. This could be something like the name of the `input` folder with `_backup` appended. This helps to ensure that if something weird goes wrong - and don't worry, it really shouldn't - then you'll still have a copy of your original files lying around somewhere. The path might look like `C:/df_40_24_win_backup`. +- Set the value for `backup`, too, which is another file path, to somewhere for the Dwarf Fortress files to be backed up to. This could be something like the name of the `input` folder with `_backup` appended. This helps to ensure that if something weird goes wrong with your original, inputted folder - and don't worry, it really shouldn't - then you'll still have a copy of your original files lying around somewhere. The path might look like `C:/df_40_24_win_backup`. -- And the really fun part is the `scripts` parameter. Here names of scripts are given in the order that they should be run. It's also possible to pass arguments to scripts here, which change the way it behaves. One way to get a list of the available scripts is to run `python manager.py --list`, and one way to see documentation regarding one of these scripts to describe its purpose and usage is to run `python manager.py --meta script.name`, where `script.name` is the name of the script you want to see. +- And the really fun part is the `scripts` parameter. Here names of scripts are given in the order that they should be run. It's also possible to pass arguments to scripts here, which can customize the way they behave. Check out the example config file for how to do that! One way to get a list of the available scripts is to run `python manager.py --list`, and one way to see documentation regarding a particular one of these scripts a description of its purpose and usage is to run `python manager.py --meta script.name`, where `script.name` is the name of the script you want to see. - For the sake of example, you can try adding an item to the list of `scripts`. The line you add would, if you wanted to add the script `pineapple.subplants`, look like this: ` - pineapple.subplants`. Be sure to indent it the same as the other items in the list! Here's a helpful and [much more thorough guide](http://symfony.com/doc/current/components/yaml/yaml_format.html) on how to use yaml. -- Installing new mods for PyDwarf is really simple if you want to use one that didn't come packaged with it. Simply place the uncompressed files, which should include at least one with a name like `pydwarf.scriptname.py`, anywhere in the `scripts` directory located within PyDwarf's root directory. If you had installed a mod named `this.is.a.script`, for example, you could tell PyDwarf to include it by adding it in the same way as the previous script: In the `scripts` list of `config.json`, you'd add a line to the list that looks like ` - this.is.a.script`. +- Installing new mods for PyDwarf is really simple if you want to use one that didn't come packaged with it. Simply place the uncompressed files, which should include at least one file with a name like `pydwarf.scriptname.py`, anywhere in the `scripts` directory located within PyDwarf's root directory. If you had installed a mod named `this.is.a.script`, for example, you could tell PyDwarf to include it by adding it in the same way as the previous script: In the `scripts` list of `config.yaml`, you'd add a line to the list that looks like ` - this.is.a.script`. - And finally, to actually run PyDwarf and apply the mods, run `python manager.py`. It will helpfully tell you if anything went wrong and, if so, what exactly happened. But PyDwarf is a piece of work and sometimes those errors may be hard to understand. If you're not sure how to fix it, you can always post in the [GitHub issue tracker](https://github.com/pineapplemachine/PyDwarf/issues) or the [Bay12 forum topic](http://www.bay12forums.com/smf/index.php?topic=150857.msg6239158#msg6239158) to ask for help. -- After running `manager.py`, if everything went smoothly, you're all done! Now you can run Dwarf Fortress and generate a new world to see the changes take effect. +- After running `manager.py`, if everything went smoothly, you're all done! Now you can run Dwarf Fortress and generate a new world to see the changes take effect. \ No newline at end of file diff --git a/docs/modding.md b/docs/modding.md index 284ede8..28c8f3f 100644 --- a/docs/modding.md +++ b/docs/modding.md @@ -20,7 +20,7 @@ client-170:PyDwarf pineapple$ python >>> emptydir = raws.dir() ``` -Realistically, you're not going to be so interested in an empty `raws.dir` object. In almost all cases you'll actually want to load it from somewhere. Let's actually load our Dwarf Fortress directory as a `raws.dir`. +Realistically, you're not going to be so interested in an empty `raws.dir` object. In almost all cases you'll actually want to load it from somewhere. Let's actually load our actual Dwarf Fortress directory as a `raws.dir` instance. ``` python >>> df = raws.dir('df_osx_40_23') @@ -45,7 +45,7 @@ It's also possible to add files to or remove them from a `raws.dir` using its `a #### raws.reffile -These files are pretty simple: When a `raws.dir` is loaded for some directory these are files it remembers the location so that when its output is written it can just copy the file over. Without intervention, PyDwarf will never look at the contents of these files. +These files are pretty simple: When a `raws.dir` is loaded for some directory these are files it remembers the location of so that when its output is written it can just copy the file over. Without intervention, PyDwarf will never look at or modify the contents of these files. #### raws.binfile @@ -113,9 +113,9 @@ Each token has a number of important attributes. So you've familiarized yourself with how PyDwarf keeps track of all this data and now you're ready to have a go yourself. But where do you start? How do you tell PyDwarf to find that one specific token for you? -Anything that can contain raws data - `raws.dir`, `raws.rawfile`, `raws.token` objects, and a few more - has access to a number of methods to make finding what you need easier. Most of them are abstractions of a base `query` method, which is for finding a token or tokens which meet some condition. +Anything that can contain raws data - including `raws.dir`, `raws.rawfile`, `raws.token` objects, and a few more - has access to a number of methods to make finding what you need easier. Most of them are abstractions of a base `query` method, which is for finding a token or tokens which meet some condition. -Here you can see just how the `query` method works. Don't expect to be using it much if at all, but know that the methods you will be using all use this method to do most of their work. +Here you can see just how the `query` method works. Don't expect to be using it much if at all, but know that the methods you will be using frequently all use this method to do most of their work. The definition of the `query` method looks like this. @@ -177,14 +177,14 @@ raw/objects/creature_standard.txt We can do this because we know that the `[CREATURE:DWARF]` token we want will always appear after an `[OBJECT:CREATURE]` token in some file. So first we used a query to get all the `[OBJECT:CREATURE]` headers, then we used the `each` method of `raws.tokencollection` to find the `[CREATURE:DWARF]` token which followed one of those headers. -You could also do something like this, since you know what file the token is in, but it's not the best practice. What if a mod you installed moved the `[CREATURE:DWARF]` definition to a different file? +You could also do something like this, since you know what file the token is in, but it's not the best practice. What if a mod you installed moved the `[CREATURE:DWARF]` definition to a different file? What if Toady renamed the file in a future update? ``` python >>> print df['raw/objects/creature_standard.txt'].get('CREATURE:DWARF') [CREATURE:DWARF] ``` -Fortunately, you won't have to worry about this stuff. PyDwarf helpfully provides methods that concern themselves about all these caveats so that you don't have to. You could have found that token just like this, using the `getobj` method. +Fortunately, you won't have to worry about this stuff. PyDwarf helpfully provides methods that concern themselves about all these caveats so that you don't have to. You could have found that token just like this, using the `getobj` method. Don't you feel silly now, having gone through all that unnecessary trouble? ``` python >>> dwarf = df.getobj('CREATURE:DWARF') @@ -289,10 +289,10 @@ def myscript(df, token='AQUIFER'): return pydwarf.success() ``` -You can assign some value to anything you want in that decorator! You could write `@pydwarf.urist(foo = 'bar')` if you felt so inclined and then wehn PyDwarf was asked to provide information about your script, it would go ahead and tell you that foo is equal to bar. But there are several things other than `foo` that PyDwarf gives special treatment to. Here are the really important ones. +You can assign some value to anything you want in that decorator! You could write `@pydwarf.urist(foo = 'bar')` if you felt so inclined and then when PyDwarf was asked to provide information about your script, it would go ahead and tell you that foo is equal to bar. But there are several things other than `foo` that PyDwarf gives special treatment to. Here are the really important ones. * `name` gives your script a name, and that should be something descriptive. You might be wondering what dots and `mynamespace` mean when they're in there. Everything preceding the final dot is the namespace, and everything following is the name. The namespace is for organization, makes it so both PyDwarf and users of your script can tell how it might be related to others. For the scripts packaged with PyDwarf, the namespace corresponds to the author of the script. So, for example, all the scripts in the `pineapple` namespace were written by yours truly. -* `version` identifies the verison of your script. If you were to improve and rerelease your script you might want to increment the version number for the new script. +* `version` identifies the verison of your script. If you were to improve and rerelease your script you might want to increment the version number for the new script to make it easy for people to tell which is the newer script. * `author` tells people who actually wrote the script. * `description` is to help people understand the purpose of your script. It should, of course, be as descriptive as possible. * `arguments` describes the purpose of each of your script's arguments, in case it accepts any. @@ -342,6 +342,7 @@ client-170:PyDwarf pineapple$ grep AQUIFER /Users/pineapple/Desktop/games/df/df_ [SOIL_OCEAN][AQUIFER] [SOIL_OCEAN][AQUIFER] client-170:PyDwarf pineapple$ grep AQUIFER /Users/pineapple/Desktop/games/df/df_osx_40_24/raw/objects/inorganic_stone_soil.txt +client-170:PyDwarf pineapple$ ``` -Congratulations on making your first mod with PyDwarf! I hope things go smoothly for you from here. In case you want much more in-depth documentation you can always refer to the [html docs](index.html), and you can post in the GitHub repository's [issue tracker](https://github.com/pineapplemachine/PyDwarf/issues) or on the [Bay12 forum topic](http://www.bay12forums.com/smf/index.php?topic=150857.0). +Congratulations on making your first mod with PyDwarf! I hope things go smoothly for you from here. In case you want more in-depth documentation you can always refer to the [html docs](index.html), and you can post in the GitHub repository's [issue tracker](https://github.com/pineapplemachine/PyDwarf/issues) or on the [Bay12 forum topic](http://www.bay12forums.com/smf/index.php?topic=150857.0). \ No newline at end of file