Details

Reviewers

Group Reviewers

Maniphest Tasks

Restricted Maniphest Task

Commits

rDDOC17951eafe724: Merge branch 'master' of https://forge.softwareheritage.org/source/swh-docs
rDDOC6afe58358b84: T3339 Getting started with the SWH API.

Summary

Introduce the "getting started with the SWH API" document, as showed on [1]. This is basically a rst export of the document, with minor fixes to remove name/castalia header.

[1] https://deepnote.com/project/Software-Heritage-aHgvv66LTAC1jgEYfe9elw/%2Fgetting_started_with_the_swh_api.ipynb

Test Plan

No test

Diff Detail

Repository

rDDOC Development documentation

Branch

T3339_getting_started_api

Lint

No Linters Available

Unit

No Unit Test Coverage

Build Status

Buildable 21645
Build 33640: arc lint + arc unit

Event Timeline

borisbaldassari created this revision.May 26 2021, 11:54 AM

Herald added a reviewer: Reviewers. · View Herald TranscriptMay 26 2021, 11:54 AM

borisbaldassari requested review of this revision.May 26 2021, 11:54 AM

Harbormaster completed remote builds in B21645: Diff 20681.May 26 2021, 11:54 AM

Thanks.

I did not read everything yet, i'm posting my few comments (right now so i don't forget later) which are mostly nitpicks or typos.

docs/getting-started/getting_started_with_the_swh_api.rst
18
46
48
49
55
112
118
209–213	nitpicks, we tend to: use black to format our base code, might as well show it the same way in samples. (for some time now) use the f-string syntax since it's allowed by the python version we develop with (3.7 onwards).

@moranegg might want to have a look ;)

Looks good to me. I have a bunch of pedantic comments (terminology and ReST syntax) though, see below.

IMO the filename should be: docs/getting-started/api.rst to avoid redundancy

And please follow https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections for the title hierarchy (start with ======)

docs/getting-started/getting_started_with_the_swh_api.rst
21–24	Use references instead of external links: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#ref-role You'll need to edit swh-dataset's documentation to add an anchor there first
38–58	Isn't this description redundant with the data model? https://docs.softwareheritage.org/devel/swh-model/data-model.html
72–82	This assumes a virtualenv to work. Could you either mention virtualenvs in the documentation, or update it to work also without a virtualenv (you just need to rename `python` to `python3` and `pip` to `pip3`)?
126–136	what is `\*`? Shouldn't it be a list?
330–333	Only to branches and releases. Revisions and content are only linked indirectly
364
427–428
475	"associated" implies a mutual relationship
484–485	they are not the contents themselves, as "name" and "perms" are part of the directory manifest, not the content
505	ditto
519–520
529	Uncomment / remove?
556	Use a reference here too (you'll need to add an anchor in swh-vault's documentation)
564–566
579–580	ditto

This revision now requires changes to proceed.May 28 2021, 4:24 PM

Merge branch 'master' into T3339_getting_started_api
Fix url to https in sphinx.rst.
Fix api getting started + rename file.
More fixes to api getting started.

Harbormaster completed remote builds in B22608: Diff 21636.Jul 14 2021, 10:31 PM

Fix sections.

Harbormaster completed remote builds in B22609: Diff 21637.Jul 14 2021, 10:37 PM

Thanks!

One last thing:

docs/getting-started/index.rst
13	should should be just `api`, as the file was renamed

This revision is now accepted and ready to land.Jul 19 2021, 3:59 PM

Merge branch 'master' into T3339_getting_started_api
Fix wrong index after api rename.

Harbormaster completed remote builds in B22665: Diff 21696.Jul 20 2021, 11:46 AM

@vlorentz Thanks for the review! Updated diff with your last comment (api in index.rst). I squashed commits and am ready to push to master, as soon as you tell me to.

docs/getting-started/getting_started_with_the_swh_api.rst
38–58	Well, it's a subset of concepts needed to quickly understand the document, instead of the big, comprehensive but complex, data model. When I'm reading a getting started, I don't want to have to swallow the full mindblowing range of great concepts, I just want to get started, so.. If I may stand up for that, I will, otherwise I'll cut the description short as proposed (and that would be ok ;-).
72–82	I'd say that "no assumption" is the way to go, so applied what you proposed (no virtualenv).
126–136	It should indeed!
209–213	Fixed for the f-string syntax, but I'm not sure about the fix for the black formatting. All code blocks have been switched from ipython3 to python, hope it will fix it.