Page MenuHomeSoftware Heritage

apidoc: Add bullet list support in input/output data documentation
ClosedPublic

Authored by anlambert on Wed, Feb 12, 6:00 PM.

Details

Summary

It enables to document nested objects for request and response data.

Depends on D2666

Diff Detail

Repository
rDWAPPS Web applications
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.

Event Timeline

anlambert created this revision.Wed, Feb 12, 6:00 PM
vlorentz requested changes to this revision.Fri, Feb 14, 10:27 AM
vlorentz added a subscriber: vlorentz.
vlorentz added inline comments.
swh/web/api/apidoc.py
86–92

Use subn instead of search+sub:

replacements_made = 1
while replacements_made:
    (par, replacements_made) = re.subn(r'(:http:.*)(\(\w+\))', r'\1', par)

And why do URLs need to be replaced multiple times now?

228–241

what is this about?

This revision now requires changes to proceed.Fri, Feb 14, 10:27 AM
anlambert added inline comments.Fri, Feb 14, 11:26 AM
swh/web/api/apidoc.py
86–92

Use subn instead of search+sub:

Ack, thanks.

And why do URLs need to be replaced multiple times now?

Because previously I was replacing every words between parenthesis but some can be part of the documentation without being url arguments.
For instance when documenting nested JSON objects like this:

:>json object <swh_pid>: an object whose keys are input persistent
    identifiers and values objects with the following keys:

        * **known (bool)**: whether the object was found

The (bool) string was replaced by an empty one previously.

228–241

I am not proud of that s**t but I could not find any other way to do it.

Basically, I just want to concatenate a bullet list to the input data / response data documentation.
self.current_text stores a reference to the latest parsed doc for input data / response data member
but I can not concatenate any string to it without creating a new string reference, so that piece of crap
code.

anlambert added inline comments.Fri, Feb 14, 1:27 PM
swh/web/api/apidoc.py
228–241

I think I found a better solution, diff update incoming

anlambert updated this revision to Diff 9536.Fri, Feb 14, 2:40 PM

Update:

  • rebase
  • address vlorentz comments
vlorentz added inline comments.Sat, Feb 15, 11:07 AM
swh/web/api/apidoc.py
86–92

That explains the change in regexp, but why the while loop?

anlambert added inline comments.Mon, Feb 17, 11:59 AM
swh/web/api/apidoc.py
86–92

Because some url description can have multiple parameters between parenthesis or brackets .

For instance /api/1/content/[(hash_type):](hash)/filetype/ and we want to obtain /api/1/content/filetype/ to reference the endpoint.

Previously, a global replacement was made but now we restrict the replacement to strings starting with :http: and use group capture. So we need to do replacements while a group is captured in the input string.

anlambert updated this revision to Diff 9573.Mon, Feb 17, 4:13 PM

Improve HTML string litterals formatting in test_apidoc.py

vlorentz accepted this revision.Tue, Feb 18, 11:28 AM
This revision is now accepted and ready to land.Tue, Feb 18, 11:28 AM
vlorentz added inline comments.Tue, Feb 18, 11:29 AM
swh/web/api/apidoc.py
86–92

This would probably deserve a comment explaining that, eg. with that example