Page MenuHomeSoftware Heritage

Add a 'user' documentation entry for the Crates lister. Add myself as contributor
AbandonedPublic

Authored by franckbret on Aug 5 2022, 12:17 PM.

Details

Reviewers
vlorentz
Group Reviewers
Reviewers
Maniphest Tasks
T4104: Ingest crates.io (Rust)
Summary

Related T4104

Diff Detail

Event Timeline

Build has FAILED

Patch application report for D8199 (id=29580)

Rebasing onto a83766debd...

Current branch diff-target is up to date.
Changes applied before test
commit 05f838aaa4864b418d6b66d6eec3fcd0744e061c
Author: Franck Bret <franck.bret@octobus.net>
Date:   Fri Aug 5 12:12:46 2022 +0200

    Add a 'user' documentation entry for the Crates lister.
    
    Related T4104

Link to build: https://jenkins.softwareheritage.org/job/DDOC/job/build-on-diff/202/
See console output for more information: https://jenkins.softwareheritage.org/job/DDOC/job/build-on-diff/202/console

Harbormaster returned this revision to the author for changes because remote builds failed.Aug 5 2022, 12:20 PM
Harbormaster failed remote builds in B30646: Diff 29580!

Nice, thanks.

A couple of typos to fix inline.

user/listers/crates.rst
19
20
30
42
43
48
user/listers/crates.rst
47

build failure is not happy about this one [1] [2]

[1]

12:19:57  /var/lib/jenkins/workspace/DDOC/build-on-diff/swh-docs/user/listers/crates.rst:48: ERROR: Unknown target name: "original-artifacts-json specification".

[2] https://jenkins.softwareheritage.org/job/DDOC/job/build-on-diff/202/console

Build has FAILED

Patch application report for D8199 (id=29580)

Rebasing onto a83766debd...

Current branch diff-target is up to date.
Changes applied before test
commit 05f838aaa4864b418d6b66d6eec3fcd0744e061c
Author: Franck Bret <franck.bret@octobus.net>
Date:   Fri Aug 5 12:12:46 2022 +0200

    Add a 'user' documentation entry for the Crates lister.
    
    Related T4104

Link to build: https://jenkins.softwareheritage.org/job/DDOC/job/build-on-diff/203/
See console output for more information: https://jenkins.softwareheritage.org/job/DDOC/job/build-on-diff/203/console

Build has failed

See this line which the build is not happy about [1]

[1] https://forge.softwareheritage.org/D8199#inline-58335

also, I cannot accept it yet (the build needs to pass first ;)

franckbret marked 7 inline comments as done.

Fix typos and an hyperlink

Build is green

Patch application report for D8199 (id=29595)

Rebasing onto a83766debd...

Current branch diff-target is up to date.
Changes applied before test
commit 880293b9754eb19e464624e54a4be5a63bc1266d
Author: Franck Bret <franck.bret@octobus.net>
Date:   Fri Aug 5 12:12:46 2022 +0200

    Add a 'user' documentation entry for the Crates lister.
    
    Related T4104

See https://jenkins.softwareheritage.org/job/DDOC/job/build-on-diff/204/ for more details.

vlorentz added inline comments.
user/listers/crates.rst
30

"envelope", actually; "envelop" is a verb.

But I don't understand what it is supposed to mean. Why not "schema" or "keys"?

46

This is an internal link

71
113

see above

franckbret marked 3 inline comments as done.

Some more typos, replace a link with an internal ref

Updating D8199: Add a 'user' documentation entry for the Crates lister.

Add myself as contributor

Build has FAILED

Patch application report for D8199 (id=29596)

Rebasing onto a83766debd...

Current branch diff-target is up to date.
Changes applied before test
commit 25f86a1e503e893f2c238749d3e52f5ffffa8d22
Author: Franck Bret <franck.bret@octobus.net>
Date:   Fri Aug 5 12:12:46 2022 +0200

    Add a 'user' documentation entry for the Crates lister.
    
    Related T4104

Link to build: https://jenkins.softwareheritage.org/job/DDOC/job/build-on-diff/205/
See console output for more information: https://jenkins.softwareheritage.org/job/DDOC/job/build-on-diff/205/console

This revision is now accepted and ready to land.Aug 5 2022, 3:39 PM

Try to fix internal ref link

Build has FAILED

Patch application report for D8199 (id=29597)

Rebasing onto a83766debd...

Current branch diff-target is up to date.
Changes applied before test
commit b8c8e177fd4a622772843763887b90b537478b62
Author: Franck Bret <franck.bret@octobus.net>
Date:   Fri Aug 5 12:12:46 2022 +0200

    Add a 'user' documentation entry for the Crates lister.
    
    Related T4104

Link to build: https://jenkins.softwareheritage.org/job/DDOC/job/build-on-diff/206/
See console output for more information: https://jenkins.softwareheritage.org/job/DDOC/job/build-on-diff/206/console

Try again to fix the internal hyperlink to a section, this time replace \# with \:

Updating D8199: Add a 'user' documentation entry for the Crates lister.

Add myself as contributor

Build has FAILED

Patch application report for D8199 (id=29598)

Rebasing onto a83766debd...

Current branch diff-target is up to date.
Changes applied before test
commit 92c8629bd8fdd3eeef0a5216074639456bffe3ce
Author: Franck Bret <franck.bret@octobus.net>
Date:   Fri Aug 5 12:12:46 2022 +0200

    Add a 'user' documentation entry for the Crates lister.
    
    Related T4104

Link to build: https://jenkins.softwareheritage.org/job/DDOC/job/build-on-diff/207/
See console output for more information: https://jenkins.softwareheritage.org/job/DDOC/job/build-on-diff/207/console

user/listers/crates.rst
46

What should be the correct syntax to reference a section in another document?

I tried those but it still fails building.

<extrinsic-metadata-specification#original-artifacts-json>
<extrinsic-metadata-specification:original-artifacts-json>

user/listers/crates.rst
46

just <original-artifacts-json>

Fix hyperlink, only the reference to named anchor is needed

Build has FAILED

Patch application report for D8199 (id=29600)

Rebasing onto a83766debd...

Current branch diff-target is up to date.
Changes applied before test
commit 464f848b9e82c71bff510baea3422055b055db72
Author: Franck Bret <franck.bret@octobus.net>
Date:   Fri Aug 5 12:12:46 2022 +0200

    Add a 'user' documentation entry for the Crates lister.
    
    Related T4104

Link to build: https://jenkins.softwareheritage.org/job/DDOC/job/build-on-diff/208/
See console output for more information: https://jenkins.softwareheritage.org/job/DDOC/job/build-on-diff/208/console

franckbret added inline comments.
user/listers/crates.rst
46

It still fail.

/var/lib/jenkins/workspace/DDOC/build-on-diff/swh-docs/user/listers/crates.rst:47: WARNING: undefined label: original-artifacts-json

By the way what is the quick way to check for errors within my venv?

I've tried with make docs but it fails, make all too. Looks like it complains about svg files and dia. Do I need to install dia or is it unexpected?

user/listers/crates.rst
46
/var/lib/jenkins/workspace/DDOC/build-on-diff/swh-docs/user/listers/crates.rst:47: WARNING: undefined label: original-artifacts-json

original-artifacts-json is defined in a different git repo, but this shouldn't be an issue. Hmm.....

By the way what is the quick way to check for errors within my venv?

Jenkins runs tox -e sphinx-dev

user/listers/crates.rst
46

OH, I got it. it's because you added this to the user documentation. We could add an inter-sphinx link, but I'd rather you move this to developer documentation instead; this page only contains technical details that aren't useful to end users.

franckbret added inline comments.
user/listers/crates.rst
46

Ah, ok.
What should be the path of that file?

user/listers/crates.rst
46

Make it a module docstring in swh/listers/crates/__init__.py so it shows up on https://docs.softwareheritage.org/devel/apidoc/swh.lister.crates.html which is linked from https://docs.softwareheritage.org/user/listers/index.html

franckbret added inline comments.
user/listers/crates.rst
46

Ok, I moved it to module level, see D8206

franckbret marked an inline comment as done.

Abandonning this one as the same content has been moved to crates lister module docstring ( see D8206 )