This repository has been archived by the owner on Nov 30, 2021. It is now read-only.
[WIP] ref(docs): doc changes #1314
Closed
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
added 10 commits
July 13, 2014 15:06
The client documentation should handle an internal link to client, while the client reference should also get its own. There are no known links to the client reference docs, so no other changes are necessary at this time.
This makes it such that when you reference the command in the documentation as ":ref:`deis_releases`", it shows up as "deis releases".
The developer guide was largely left unkempt for a long time. This PR brings back the developer guide up to snuff with the recent changes to Deis. It also links all referenced commands to the client reference docs, giving the reference guide some love.
One less word in the title makes it a bit more clear. Less is more!
Makes the name more clear for users as well as removing redundancy. They're already on the Deis documentation, so "user guide" makes more sense.
We are on the Deis docs, so using "Deis" in the title is a bit redundant. Switching the title to "Operations Guide" reflects what the documentation is trying to explain.
Using "Deis" in the title while inside the Deis documentation is redundant. Changing the title to "About" better reflects what this section is describing.
This refactors the docstrings such that they provide more useful
information to the user.
BREAKING CHANGES: the clusters:create option used to require a couple
CLI options: `--hosts` and `--auth`. Since these "options" were
mandatory, I promoted them to standalone arguments. For example, you
used to create a cluster like so:
$ deis clusters:create dev example.com --hosts=example.com,example2.com --auth=~/.ssh/deis
With the new syntax, it looks like:
$ deis clusters:create dev example.com example.com,example2.com ~/.ssh/deis
bacongobbler
changed the title
|
This has kind of expanded into a much larger PR than what was initially proposed... We already agreed upon the documentation titles, anywho. I'll break these bigger changes out into smaller PRs. |
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR changes the following documentation section titles:
"Understanding Deis" -> "About"
"Installing Deis" -> "Installation Guide"
"Using Deis" -> "User Guide"
"Managing Deis" -> "Operations Guide"
This is in reflection to #1050 (comment)
Using "Deis" in the title seemed redundant, as we are already on the Deis documentation. There are also some user guide changes as well, such as making commands link properly to the reference guide, giving the autodocs some love.
The client docstrings have also been refactored to make them more portable and easier to read on http://docs.deis.io/en/latest/reference/client/. One breaking change was introduced here, which was to the
clusters:createdocstring. See 0080a07 for more information. The angle brackets on parameters were removed, since docopt recommends CAPITAL LETTERS as parameters for docstrings. See https://github.com/docopt/docopt/blob/master/examples/arguments_example.pyMore changes to come soon:
Critique away! :)