Page MenuHomeSoftware Heritage

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

Authored by anlambert on Feb 12 2020, 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

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?

227–240

what is this about?

This revision now requires changes to proceed.Feb 14 2020, 10:27 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.

227–240

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.

swh/web/api/apidoc.py
227–240

I think I found a better solution, diff update incoming

Update:

  • rebase
  • address vlorentz comments
swh/web/api/apidoc.py
86–92

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

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.

Improve HTML string litterals formatting in test_apidoc.py

This revision is now accepted and ready to land.Feb 18 2020, 11:28 AM
swh/web/api/apidoc.py
86–92

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