Page MenuHomeSoftware Heritage

doc: rename Getting Started as User Manual and update the content
ClosedPublic

Authored by douardda on Nov 6 2020, 11:00 AM.

Details

Summary
  • add an installation section (for swh deposit cli)
  • do not talk about the metadata-file-less deposit (it's a marginal use case that we do not encourage),
  • present the deposit workflow,
  • make it a step-by-step reproducible tutorial

Depends on D4429.
Related to T2751.

Diff Detail

Event Timeline

Build is green

Patch application report for D4430 (id=15686)

Could not rebase; Attempt merge onto 0f4ec31168...

Updating 0f4ec311..b54cd308
Fast-forward
 docs/endpoints/collection.rst       | 116 ++++-----
 docs/endpoints/content.rst          |  65 +++++-
 docs/endpoints/service-document.rst |  80 ++++---
 docs/endpoints/status.rst           |  63 ++---
 docs/endpoints/update-media.rst     |  16 +-
 docs/endpoints/update-metadata.rst  |  10 +-
 docs/getting-started.rst            | 285 ----------------------
 docs/index.rst                      |   7 +-
 docs/spec-api.rst                   |  29 +--
 docs/specs/blueprint.rst            | 192 +++++++--------
 docs/specs/{specs.rst => index.rst} |   0
 docs/specs/spec-loading.rst         | 119 +++++-----
 docs/user-manual.rst                | 454 ++++++++++++++++++++++++++++++++++++
 13 files changed, 843 insertions(+), 593 deletions(-)
 delete mode 100644 docs/getting-started.rst
 rename docs/specs/{specs.rst => index.rst} (100%)
 create mode 100644 docs/user-manual.rst
Changes applied before test
commit b54cd3081436526ecfa92ddd34dc3a16caeb1b9d
Author: David Douard <david.douard@sdfa3.org>
Date:   Mon Nov 2 14:52:15 2020 +0100

    doc: improve the user manual documentation
    
    - add an installation section (for swh deposit cli)
    - do not talk about the metadata-file-less deposit (it's a marginal use
      case that we do not encourage),
    - present the deposit workflow,
    - make it a step-by-step reproducible tutorial

commit cfb20df96b852b4a8e0c88d909f15ad6b6a8a653
Author: David Douard <david.douard@sdfa3.org>
Date:   Wed Oct 28 09:58:04 2020 +0100

    doc: rename Getting Starter as User Manual and update the content

commit 912be1d02839250950b2770c79d332ccf0ccd0ef
Author: David Douard <david.douard@sdfa3.org>
Date:   Fri Nov 6 09:39:24 2020 +0100

    doc: add an introduction paragraph in blueprint.rst
    
    and move the list of deposit statuses there instead of repeating it 3
    times.
    
    Also reference the API endpoints used in the deposit creation scenario.

commit 489f1ab76caa54b50e7523c058b4d5034e66d858
Author: David Douard <david.douard@sdfa3.org>
Date:   Fri Nov 6 09:36:29 2020 +0100

    doc: improve the spec-loading doc
    
    - update some deprecated statements (tar loader -> deposit loader)
    - explcit API calls for example JSON snippets
    - update JSON snippets for current API behavior

commit 61653ddfc7c38bd4130374a6b6472f55f358138a
Author: David Douard <david.douard@sdfa3.org>
Date:   Thu Nov 5 16:16:07 2020 +0100

    doc: improve the doc of API endpoints
    
    make usage of the sphinx-httpdomain extension according to its
    documenation.

commit 1736371f2c6da9713e4f815da99cd3cd624fdaad
Author: David Douard <david.douard@sdfa3.org>
Date:   Thu Nov 5 14:21:40 2020 +0100

    doc: rename docs/specs/specs.rst as docs/specs/index.rst
    
    for the sake of clarity.

See https://jenkins.softwareheritage.org/job/DDEP/job/tests-on-diff/284/ for more details.

First major question: do we prefer to have deposits with cli?
and do we need to have a preference, or should both mechanisms be equal

I think that the first sentence ending with "push a software deposit with the swh deposit commands." is clear enough that the cli is used in this user manual.
To cover both mechanisms to deposit in SWH, we need 2 tutorials
A quick look concludes that:

  • the requirements applies to both mechanisms
  • the installation section is only for the cli
  • prepare a deposit is for both (and might be a bit too detailed)
docs/user-manual.rst
17

didn't you want to change that to the deposit email?

21

does this mean that staging is now public?

docs/user-manual.rst
17

ah yes you're right

21

Not yet, but I expect it will be soon :-)

Rebase, updates and fix according to moranegg's comments

douardda retitled this revision from [WIP] doc: rename Getting Starter as User Manual and update the content to doc: rename Getting Starter as User Manual and update the content.Nov 9 2020, 4:09 PM
douardda edited the summary of this revision. (Show Details)

Build is green

Patch application report for D4430 (id=15750)

Rebasing onto 7148a257b2...

Current branch diff-target is up to date.
Changes applied before test
commit 4af028e76d5bc67aa937579cfa1cc31ab41d0354
Author: David Douard <david.douard@sdfa3.org>
Date:   Mon Nov 2 14:52:15 2020 +0100

    doc: improve the user manual documentation
    
    - add an installation section (for swh deposit cli)
    - do not talk about the metadata-file-less deposit (it's a marginal use
      case that we do not encourage),
    - present the deposit workflow,
    - make it a step-by-step reproducible tutorial

commit a98bbbfad4cc5eb292bed0bc66058cfbd8232ad8
Author: David Douard <david.douard@sdfa3.org>
Date:   Wed Oct 28 09:58:04 2020 +0100

    doc: rename Getting Starter as User Manual and update the content

See https://jenkins.softwareheritage.org/job/DDEP/job/tests-on-diff/304/ for more details.

vlorentz added inline comments.
docs/user-manual.rst
194–202

déjà-vu

433–439

duplicate, do you want to keep it?

douardda edited the summary of this revision. (Show Details)

adapt according to vlorentz' comment

Build is green

Patch application report for D4430 (id=15759)

Rebasing onto 7148a257b2...

Current branch diff-target is up to date.
Changes applied before test
commit 08cb9a869142e81507e9f0efd34a5b4f8a1da4f3
Author: David Douard <david.douard@sdfa3.org>
Date:   Mon Nov 2 14:52:15 2020 +0100

    doc: improve the user manual documentation
    
    - add an installation section (for swh deposit cli)
    - do not talk about the metadata-file-less deposit (it's a marginal use
      case that we do not encourage),
    - present the deposit workflow,
    - make it a step-by-step reproducible tutorial

commit a98bbbfad4cc5eb292bed0bc66058cfbd8232ad8
Author: David Douard <david.douard@sdfa3.org>
Date:   Wed Oct 28 09:58:04 2020 +0100

    doc: rename Getting Starter as User Manual and update the content

See https://jenkins.softwareheritage.org/job/DDEP/job/tests-on-diff/307/ for more details.

ardumont retitled this revision from doc: rename Getting Starter as User Manual and update the content to doc: rename Getting Started as User Manual and update the content.Nov 10 2020, 9:35 AM

Added some typos and indentation to fix.
Add some questions or remarks inline but otherwise, looks good to me.

Thanks

docs/user-manual.rst
21

yes, it will come soon [1]

[1] T2747

54

Given the orientation the documentation is taking, using swh deposit cli output with jq.

We should consider making the swh deposit cli output format default to json, i don't think it's the case today.

59

Fo`r`

90

Why do we need to expose that much information on the jq install step?

194–202

I think that means "Can you please reuse the include step you did in another documentation refactoring about those statuses?"

;)

247

indentation is off

and for --format json, that's why i proposed to default to json as the cli output earlier ;)

306

there is no need...

And i'd be explicit about the unneeded flags:

for giving the extra options `--name` and `--title`.
454

available to external

docs/user-manual.rst
194–202

I didn't know sphinx had includes! :o

docs/user-manual.rst
54

We should consider making the swh deposit cli output format default to json, i don't think it's the case today.

indeed, the "logging" format does not makes much sense IMHO

90

I agree this is uncecessary

306

And i'd be explicit about the unneeded flags:

for giving the extra options --name and --title.

Actually I think this should not be mentioned at all, since we removed the "simplified deposit" completely from this doc.

typos and some fixes according to comments

Build is green

Patch application report for D4430 (id=15776)

Rebasing onto 018500c195...

First, rewinding head to replay your work on top of it...
Applying: doc: rename Getting Starter as User Manual and update the content
Applying: doc: improve the user manual documentation
Changes applied before test
commit b8234f20a659e48beeaefea32c0b3a635961fe1d
Author: David Douard <david.douard@sdfa3.org>
Date:   Mon Nov 2 14:52:15 2020 +0100

    doc: improve the user manual documentation
    
    - add an installation section (for swh deposit cli)
    - do not talk about the metadata-file-less deposit (it's a marginal use
      case that we do not encourage),
    - present the deposit workflow,
    - make it a step-by-step reproducible tutorial

commit 917424c65d77e82e304282b86d9ba5f4978c1ac8
Author: David Douard <david.douard@sdfa3.org>
Date:   Wed Oct 28 09:58:04 2020 +0100

    doc: rename Getting Starter as User Manual and update the content

See https://jenkins.softwareheritage.org/job/DDEP/job/tests-on-diff/310/ for more details.

remove remaining mentions of the "simplified metadata deposit"

Build is green

Patch application report for D4430 (id=15778)

Rebasing onto 018500c195...

First, rewinding head to replay your work on top of it...
Applying: doc: rename Getting Starter as User Manual and update the content
Applying: doc: improve the user manual documentation
Changes applied before test
commit 7ac67cf6be2cc556c49e7ee33cd0529e8420298d
Author: David Douard <david.douard@sdfa3.org>
Date:   Mon Nov 2 14:52:15 2020 +0100

    doc: improve the user manual documentation
    
    - add an installation section (for swh deposit cli)
    - do not talk about the metadata-file-less deposit (it's a marginal use
      case that we do not encourage),
    - present the deposit workflow,
    - make it a step-by-step reproducible tutorial

commit 0a4a9e3ae8cacf7e78d6a4d75f16179e6c2b8206
Author: David Douard <david.douard@sdfa3.org>
Date:   Wed Oct 28 09:58:04 2020 +0100

    doc: rename Getting Starter as User Manual and update the content

See https://jenkins.softwareheritage.org/job/DDEP/job/tests-on-diff/311/ for more details.

This revision is now accepted and ready to land.Nov 10 2020, 2:58 PM

Build is green

Patch application report for D4430 (id=15783)

Rebasing onto 018500c195...

Current branch diff-target is up to date.
Changes applied before test
commit a252e005acb19c3b3c2c77d7455cd8bed2a8f4bb
Author: David Douard <david.douard@sdfa3.org>
Date:   Mon Nov 2 14:52:15 2020 +0100

    doc: improve the user manual documentation
    
    - add an installation section (for swh deposit cli)
    - do not talk about the metadata-file-less deposit (it's a marginal use
      case that we do not encourage),
    - present the deposit workflow,
    - make it a step-by-step reproducible tutorial

commit 91f92a12d4555f895e47f5e717c667842ac97bc5
Author: David Douard <david.douard@sdfa3.org>
Date:   Wed Oct 28 09:58:04 2020 +0100

    doc: rename Getting Starter as User Manual and update the content

See https://jenkins.softwareheritage.org/job/DDEP/job/tests-on-diff/316/ for more details.