Documentation fixes

Documentation fixes

* Spec has been renamed and updated to match current agreed behaviour
* Implementation notes from the pas-start-machine-constraints branch have
  been removed due to complete irrelevance.
* Command documentation has been tidied up and fixed.

https://code.launchpad.net/~fwereade/juju/constraints-doc-updates/+merge/99912

Requires: https://code.launchpad.net/~fwereade/juju/warn-ignored-constraints/+merge/99861

(do not edit description out of merge proposal)

[fwereade, 2012-03-29 11:31:31]

Please take a look.

[hazmat, 2012-03-29 20:04:43]

needs some additional context on who this documentation is intended for devs or
users.

https://codereview.appspot.com/5946047/diff/1/docs/source/drafts/constraints.rst
File docs/source/drafts/constraints.rst (right):

https://codereview.appspot.com/5946047/diff/1/docs/source/drafts/constraints....
docs/source/drafts/constraints.rst:15: This feature allows us to deprecate the
temporary EC2 environment properties
who is us? the reader is likley a user of the feature. i'd move discussion of
deprecation and legacy to its own section.  is this doc meant for end user doc
or internals?

https://codereview.appspot.com/5946047/diff/1/docs/source/drafts/constraints....
docs/source/drafts/constraints.rst:104: to specify constraints against legacy
deployments will generate errors; however,
will generate errors on the cli to inform the user of their invalidity. at the
agent level their simply ignored.

[fwereade, 2012-03-30 11:25:08]

I've rewritten it to be more user-focused (which included dropping the
possible-enhancements section).

https://codereview.appspot.com/5946047/diff/1/docs/source/drafts/constraints.rst
File docs/source/drafts/constraints.rst (right):

https://codereview.appspot.com/5946047/diff/1/docs/source/drafts/constraints....
docs/source/drafts/constraints.rst:104: to specify constraints against legacy
deployments will generate errors; however,
On 2012/03/29 20:04:43, hazmat wrote:
> will generate errors on the cli to inform the user of their invalidity. at the
> agent level their simply ignored.

Thanks.

[fwereade, 2012-03-30 11:48:59]

Lbox has its knickers in a twist about some checksum mismatch; proposing again
direct into shadow-trunk-1204

[fwereade, 2012-03-30 12:20:01]

On 2012/03/30 11:48:59, fwereade wrote:
> Lbox has its knickers in a twist about some checksum mismatch; proposing again
> direct into shadow-trunk-1204

https://code.launchpad.net/~fwereade/juju/constraints-doc-updates/+merge/100115

https://codereview.appspot.com/5970047/

[hazmat, 2012-03-30 16:29:56]

there's some diff oddities against trunk, but this LGTM with some minors from
below.

https://codereview.appspot.com/5946047/diff/4001/docs/source/drafts/constrain...
File docs/source/drafts/constraints.rst (left):

https://codereview.appspot.com/5946047/diff/4001/docs/source/drafts/constrain...
docs/source/drafts/constraints.rst:10: story, we consider two possible cases:
s/we/there are two use cases to consider

https://codereview.appspot.com/5946047/diff/4001/docs/source/drafts/constrain...
docs/source/drafts/constraints.rst:24: We introduce "machine constraints", which
are used to encode an administrator's
s/We/Juju allows for these via

https://codereview.appspot.com/5946047/diff/4001/docs/source/drafts/constrain...
docs/source/drafts/constraints.rst:31: Constraints will be controlled with a new
command, `juju set-constraints`,
s/will/can

https://codereview.appspot.com/5946047/diff/4001/docs/source/drafts/constrain...
File docs/source/drafts/constraints.rst (right):

https://codereview.appspot.com/5946047/diff/4001/docs/source/drafts/constrain...
docs/source/drafts/constraints.rst:40: We also extend the syntax for `juju
deploy`, and `juju bootstrap`, such that
s/We also extend the syntax/Constraint support is enabled in ...

s/such that/via a --constraints parameter

https://codereview.appspot.com/5946047/diff/4001/docs/source/drafts/constrain...
docs/source/drafts/constraints.rst:46: Please note that there are no changes to
the `juju add-unit` command; juju is
s/there are no changes to the/there is no constraints support in the

https://codereview.appspot.com/5946047/diff/4001/docs/source/drafts/constrain...
docs/source/drafts/constraints.rst:56: register `ubuntu-series` and
`provider-type` constraints, to assist with image
Drop everything after the first sentence in this para, its an impl detail to
users.

https://codereview.appspot.com/5946047/diff/4001/docs/source/drafts/constrain...
docs/source/drafts/constraints.rst:79: "ec2-" prefix; we expect to expose
`arch`, `cpu`, `mem` and `instance-type`
please replace all personal pronouns with some appropriate form referencing
'juju' the product.

https://codereview.appspot.com/5946047/diff/4001/docs/source/drafts/constrain...
docs/source/drafts/constraints.rst:85: settings remain as a workaround for this
situation, until we develop a means of
/s until we develop a means of/future releases of juju will incorporate private
cloud ec2 apis to define use these constraints.

https://codereview.appspot.com/5946047/diff/4001/docs/source/drafts/constrain...
docs/source/drafts/constraints.rst:88: checking for existence of an `ec2-uri`
provider setting, which implies use of
i'm wondering if we should add some detection to this to detect amazon.com based
uris, as its perfectly valid to toss an ec2 region uri into this.

https://codereview.appspot.com/5946047/diff/4001/docs/source/drafts/constrain...
docs/source/drafts/constraints.rst:122: cli to inform users of their invalidity;
at the agent level they are simply
correcting my own phrasing here..

s/at the agent level/within the environment