Better Documentation...

[fusion94]

To the uninitiated the docs are kind of confusing as to how to use properly with Octopress 3. Or it could be for someone not already familiar with Octopress.

For example if the only thing required for the git method is git_url then that should be the only option displayed in _deploy.yml. It's fine to display the other options but they should be commented out with a note as to their default state/purpose. The same holds true for the other methods as well.

This could be accomplished with a standard format of _deploy.yml where the user needs to set the variables required for the method the user choses.

something similar to this:

method: git
site_dir: _site
git_url: git@github.com:Bytesfree/bytesfree.github.io.git
git_branch: master

# if using the rsync method to deploy please note that you'll need to uncomment the
# method and remote_path options below.

# method: rsync
# remote_path:      #Remote destination's document root. REQUIRED
# user:             #ssh user, e.g user@host.com no default
# port:             #ssh port, defaults to 22
# exclude_file:     #Path to a file containing rsync exclusions. no default
# exclude:          #Inline list of rsync exclusions. no default
# include:          #Inline list of inclusions to override exclusions. no default
# delete:           #Delete files in destination not found in source. defaults to false

[parkr]

There's yet a lot of work to do on the docs. We're working on it but they'll likely come after the code has been fully fleshed out. Being documentation-first wouldn't work well for us. Thanks for your issue though!

[fusion94]

@parkr as a software developer myself i totally get that. Did want to raise this as a placeholder so that it doesn't get forgotten.

[imathis]

@fusion94 Thanks very much for posting this. My thinking is that I'd much rather have people rely on the CLI to generate the appropriate set of options in a YAML file than have a single file which contains them all. Given that exclude, and include only work with rsync it makes the YAML file for git a bit more confusing if they are in there and commented out. I'm not sure if you saw the init task or not, but octopress deploy init git will create a _deploy.yml file with only what you need for git deployment. The same goes for the AWS stuff. What do you think?

[fusion94]

@imathis I used the cli/init task to generate my git configs. My thoughts were that it generated correctly but if there are options that aren't required then those options should have been commented out by default. By leaving them in an active state (even though the values passed are empty) users are going to fill in values into there even though they aren't required.

For example I just ran $ octopress deploy --init rsync and got this:

------------------
method: rsync
site_dir: _site
user: 
port: 
remote_path: 
delete:
------------------

since method, site_dir and remote_path are the only items that need to contain values I'd rather see that generated file look more like this:

------------------
method: rsync
site_dir: _site
# user: 
# port: 
remote_path: 
# delete:
------------------

Am I making sense at all?

[imathis]

Yes! Good call. I'll work on commenting out optional settings and adding relevant comments to the YAML. I expect most uses of rsync won't want to copy locally, even though user is optional, I'm a bit worried that commenting it out will lead to people not noticing it. I'd comment out port, remote_path and delete though. Think that works? I'll try to have a PR up soon.