Details
- Reviewers
ardumont - Group Reviewers
Reviewers - Maniphest Tasks
- T2751: Clarify in documentation the specs status
- Commits
- rDDEPa252e005acb1: doc: improve the user manual documentation
rDDEP91f92a12d455: doc: rename Getting Starter as User Manual and update the content
Diff Detail
- Repository
- rDDEP Push deposit
- Lint
Automatic diff as part of commit; lint not applicable. - Unit
Automatic diff as part of commit; unit tests not applicable.
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.rstChanges 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? | |
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 contentSee https://jenkins.softwareheritage.org/job/DDEP/job/tests-on-diff/304/ for more details.
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 contentSee https://jenkins.softwareheritage.org/job/DDEP/job/tests-on-diff/307/ for more details.
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 |
indeed, the "logging" format does not makes much sense IMHO | |
| 90 | I agree this is uncecessary | |
| 306 |
Actually I think this should not be mentioned at all, since we removed the "simplified deposit" completely from this doc. | |
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 contentSee https://jenkins.softwareheritage.org/job/DDEP/job/tests-on-diff/310/ for more details.
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 contentSee https://jenkins.softwareheritage.org/job/DDEP/job/tests-on-diff/311/ for more details.
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 contentSee https://jenkins.softwareheritage.org/job/DDEP/job/tests-on-diff/316/ for more details.