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
- Branch
- doc
- Lint
Lint Skipped - Unit
Unit Tests Skipped - Build Status
Buildable 16987 Build 26212: Phabricator diff pipeline on jenkins Jenkins console · Jenkins Build 26211: arc lint + arc unit
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? |
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.
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.
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 content
See 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 content
See 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 content
See https://jenkins.softwareheritage.org/job/DDEP/job/tests-on-diff/316/ for more details.