Feature #2505

Recurring: Update doc site to ensure it is internally consistent and accurately reflects the current behavior of the software.

Added by Tom Clegg almost 6 years ago. Updated almost 6 years ago.

Status:
Resolved
Priority:
Normal
Assigned To:
Category:
-
Start date:
12/02/2013
Due date:
% Done:

100%

Estimated time:
(Total: 5.00 h)
Story points:
1.0

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

Subtasks

Task #2635: Update docs. See #2505ResolvedTom Clegg

Task #2672: Review 2505-update-docs branchResolvedTom Clegg


Related issues

Related to Arvados - Bug #2380: Fix bugs in Windows SSH instructions, and split off to a separate page (use template includes to show identical workbench-side content on both).Resolved06/30/2014

Associated revisions

Revision 6d2128ae
Added by Tom Clegg almost 6 years ago

Merge branch '2505-update-docs'

refs #2505

Conflicts:
doc/api/methods/groups.html.textile.liquid
doc/api/methods/users.html.textile.liquid
doc/api/schema/Group.html.textile.liquid

History

#1 Updated by Tom Clegg almost 6 years ago

  • Description updated (diff)

#2 Updated by Brett Smith almost 6 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"?

#3 Updated by Tom Clegg almost 6 years ago

  • Description updated (diff)

#4 Updated by Tom Clegg almost 6 years ago

  • Description updated (diff)

#5 Updated by Tom Clegg almost 6 years ago

  • Description updated (diff)

#6 Updated by Tom Clegg almost 6 years ago

  • Description updated (diff)
Workbench install:
  • Instructions for making tests run should move from README to doc? public wiki
API server install:
  • 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 before bundle install

#7 Updated by Tom Clegg almost 6 years ago

  • Description updated (diff)

#8 Updated by Tom Clegg almost 6 years ago

In API reference, there's a "Methods" boilerplate on each "schema" page which should move to the appropriate "methods" page.

#9 Updated by Tom Clegg almost 6 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?

#10 Updated by Tom Clegg almost 6 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`

#11 Updated by Tom Clegg almost 6 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

#12 Updated by Tom Clegg almost 6 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" 

#13 Updated by Tom Clegg almost 6 years ago

Description of the Job record is duplicated in the API methods section.
  • 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.

#14 Updated by Tom Clegg almost 6 years ago

  • Assigned To set to Tom Clegg

#15 Updated by Tom Clegg almost 6 years ago

Remove use of where parameter in tutorials and examples.

#16 Updated by Tom Clegg almost 6 years ago

  • Description updated (diff)

#17 Updated by Tom Clegg almost 6 years ago

Notes on 2505-update-docs branch
  • 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

#18 Updated by Tim Pierce almost 6 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"
  • doc/api/methods/virtual_machines.html.textile.liquid
    • get_all_logins and logins
      • Suggestion: document logins first, and then explain that get_all_logins performs the result of a logins 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 and get_all_logins, even if it's just a JSON object with obvious field names.
  • doc/install/install-api-server.html.textile.liquid
    • Are we not recommending that users install RVM when building/installing the API server?

#19 Updated by Tom Clegg almost 6 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 and logins
      • Suggestion: document logins first, and then explain that get_all_logins performs the result of a logins 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 and get_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...

475c550e2ee1377b2f7b2ad9fcfdf392ecbd983b

#20 Updated by Tim Pierce almost 6 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 and logins
      • Suggestion: document logins first, and then explain that get_all_logins performs the result of a logins 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?

OK, fair. (What! Pedants? Where?)

#21 Updated by Tom Clegg almost 6 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.

#22 Updated by Tim Pierce almost 6 years ago

LGTM

#23 Updated by Tom Clegg almost 6 years ago

  • Status changed from New to Resolved

Also available in: Atom PDF