Feature #2505
closedRecurring: Update doc site to ensure it is internally consistent and accurately reflects the current behavior of the software.
Added by Tom Clegg over 10 years ago. Updated over 10 years ago.
Description
TODO:
- Fix unnecessary monospace for names of programs (notably SSH and git).
- Standardize capitalization of "SSH" and "Git" when used as names rather than commands typed in a terminal (those seem to be the accepted use / official home page spellings, respectively)
- Spelling of MD5 is MD5, not md5
Related issues
Updated by Brett Smith over 10 years ago
It would also be good to settle on a typographical convention for attribute names in JSON. Do we "quote them", monospace them
, or "both"
?
Updated by Tom Clegg over 10 years ago
- Description updated (diff)
- Instructions for making tests run should move from README to
doc?public wiki
- Add recipe for installing ruby 2.1 (including
apt-get install zlib1g-dev gettext bison libssl-dev libreadline-dev
before building ruby) apt-get install libpq-dev sqlite3 libsqlite3-dev build-essential
beforebundle install
Updated by Tom Clegg over 10 years ago
In API reference, there's a "Methods" boilerplate on each "schema" page which should move to the appropriate "methods" page.
Updated by Tom Clegg over 10 years ago
"Queue" section in schema->jobs should move to the Jobs API methods page.
If we do respond to POST /arvados/v1/jobs/queue
... that's a bug, right?
Updated by Tom Clegg over 10 years ago
--format=uuid
argument is missing (2x) at http://doc.arvados.org/install/create-standard-objects.html
prefix=`arv --format=uuid user current | cut -d- -f1`
Updated by Tom Clegg over 10 years ago
Install docs should include a recipe for setting up postgres database/user. I think this is all that's needed:
sudo apt-get install postgresql sudo -u postgres createuser --createdb --encrypted --pwprompt arvados
Updated by Tom Clegg over 10 years ago
http://doc.arvados.org/install/create-standard-objects.html also needs read -rd
gunk for keep_disk part:
read -rd $'\000' keepdisk <<EOF; arv keep_disk create --keep-disk "$keepdisk"
Updated by Tom Clegg over 10 years ago
- no_reuse is inside the "job" parameter but isn't part of the job resource. It is attached to the create method and should be documented there.
- The other attributes of a Job resource should be documented on the Job resource page instead (and most are, but content differs slightly and should be merged).
Read #2176 before getting too far into this one.
Updated by Tom Clegg over 10 years ago
Remove use of where
parameter in tutorials and examples.
Updated by Tom Clegg over 10 years ago
- Should cover the bugs/changes listed above, except "typographical convention for attribute names in JSON"
- Doesn't include the other bug report subtasks
- Changed the jobs.create API make a bit more sense, in order to make jobs.create API docs make a bit more sense
Updated by Tim Pierce over 10 years ago
Review:
General note: when we say "git commit tag, branch or hash" are we really talking about a git revision, and can we supply any kind of revision supported by the git back end? If so, we should use that term, so it's more accurate and git veterans will know what's going on.
- doc/api/methods/jobs.html.textile.liquid
- Suggestion: include a tag or branch in the example arguments to
exclude_script_versions
- The documentation and examples for the Job methods still refer to arguments that have been removed from the method documentation, e.g.
script_version
,parameters
,nondeterministic
. - grammar pedant: "more than one of candidate jobs"
- Suggestion: include a tag or branch in the example arguments to
- doc/api/methods/virtual_machines.html.textile.liquid
get_all_logins
andlogins
- Suggestion: document
logins
first, and then explain thatget_all_logins
performs the result of alogins
query for every VM known to the system. - As long as we're updating this, let's document the format of the return value for
logins
andget_all_logins
, even if it's just a JSON object with obvious field names.
- Suggestion: document
- doc/install/install-api-server.html.textile.liquid
- Are we not recommending that users install RVM when building/installing the API server?
Updated by Tom Clegg over 10 years ago
Tim Pierce wrote:
Review:
General note: when we say "git commit tag, branch or hash" are we really talking about a git revision, and can we supply any kind of revision supported by the git back end? If so, we should use that term, so it's more accurate and git veterans will know what's going on.
I agree that "anything git-show can resolve to a single commit" is what we should (do actually?) support. Unfortunately I don't think "revision" means that either: a revision might resolve to a tree or a blob rather than a commit.
For now we have a compromise: "git commit tag, branch or hash" is git-correct terminology (right?) and doesn't include anything we don't want. But at least it isn't overly broad (like "revision" would be) and it makes it clear that we accept at least some symbolic refs ("commit" alone might not convey this).
To explicitly support revisions like "master^{/json_response}"
("youngest commit reachable from master whose comment contains the string json_response") we should probably do some testing and add a suitable paragraph. Due to the nature of git I think we will ultimately have to define "acceptable" as "a string for which git command XYZ outputs exactly one commit hash"...
- doc/api/methods/jobs.html.textile.liquid
- Suggestion: include a tag or branch in the example arguments to
exclude_script_versions
Added.
- The documentation and examples for the Job methods still refer to arguments that have been removed from the method documentation, e.g.
script_version
,parameters
,nondeterministic
.
Tweaked wording, added links to the Job resource page where these are defined. (Having special find_or_create logic customized for Job resources makes this inherently awkward...)
- grammar pedant: "more than one of candidate jobs"
Fixed. (That qualifies as pedantry these days?)
Also added a new test case for the behavior "If ‘minimum_script_version’ is not specified, only ‘script_version’ is added to the list."
- doc/api/methods/virtual_machines.html.textile.liquid
get_all_logins
andlogins
- Suggestion: document
logins
first, and then explain thatget_all_logins
performs the result of alogins
query for every VM known to the system.
Re-ordered, but left the explanations independent, in case any pedants say "but the result of a logins query is an arvados#HashList
, so do I get N arvados#HashList
resource lists in my response?
- As long as we're updating this, let's document the format of the return value for
logins
andget_all_logins
, even if it's just a JSON object with obvious field names.
Added.
- doc/install/install-api-server.html.textile.liquid
- Are we not recommending that users install RVM when building/installing the API server?
I guess I don't. I think the RVM option (and this entire section of the doc site, for that matter) would be better off in a wiki page at arvados.org...
Updated by Tim Pierce over 10 years ago
Tom Clegg wrote:
Tim Pierce wrote:
Review:
General note: when we say "git commit tag, branch or hash" are we really talking about a git revision, and can we supply any kind of revision supported by the git back end? If so, we should use that term, so it's more accurate and git veterans will know what's going on.
I agree that "anything git-show can resolve to a single commit" is what we should (do actually?) support. Unfortunately I don't think "revision" means that either: a revision might resolve to a tree or a blob rather than a commit.
For now we have a compromise: "git commit tag, branch or hash" is git-correct terminology (right?) and doesn't include anything we don't want. But at least it isn't overly broad (like "revision" would be) and it makes it clear that we accept at least some symbolic refs ("commit" alone might not convey this).
To explicitly support revisions like
"master^{/json_response}"
("youngest commit reachable from master whose comment contains the string json_response") we should probably do some testing and add a suitable paragraph. Due to the nature of git I think we will ultimately have to define "acceptable" as "a string for which git command XYZ outputs exactly one commit hash"...
I'd like the documentation to be precise about what is and isn't expected behavior. If we want people to stick to hashes, branches and tags, but we're not actually enforcing that yet, a footnote to that effect would be useful ("Arvados will accept any string that 'git show' can resolve to a single commit, but that behavior is not guaranteed for future releases" or some such).
- doc/api/methods/jobs.html.textile.liquid
- Suggestion: include a tag or branch in the example arguments to
exclude_script_versions
Added.
Is it acceptable in Liquid to add these on a separate line? (Yes, I'm being lazy and not building my own doc server to see how it gets rendered...)
- doc/api/methods/virtual_machines.html.textile.liquid
get_all_logins
andlogins
- Suggestion: document
logins
first, and then explain thatget_all_logins
performs the result of alogins
query for every VM known to the system.Re-ordered, but left the explanations independent, in case any pedants say "but the result of a logins query is an
arvados#HashList
, so do I get Narvados#HashList
resource lists in my response?
OK, fair. (What! Pedants? Where?)
Updated by Tom Clegg over 10 years ago
Tim Pierce wrote:
I'd like the documentation to be precise about what is and isn't expected behavior. If we want people to stick to hashes, branches and tags, but we're not actually enforcing that yet, a footnote to that effect would be useful ("Arvados will accept any string that 'git show' can resolve to a single commit, but that behavior is not guaranteed for future releases" or some such).
Edited to claim "anything that resolves to a single commit" with a link to the git-revisions man page and a disclaimer about some classes of names that shouldn't be expected to produce sensible results.
Is it acceptable in Liquid to add these on a separate line? (Yes, I'm being lazy and not building my own doc server to see how it gets rendered...)
Yes, it renders correctly.