api: better code documentation

[jorgeorpinel]

Close #3092

[Suor]

I don't like backticks, we don't use them anywhere else. Python stdlib doesn't use them either.

[shcheklein]

any suggestions? is there a standard way of doing markup that is understood by the tools that generate a view for this (like F1 in PyCharm, quick help in VS Code, docs generators, etc)

btw, we do use them as far as I can tell internally, also, Markdown markup or some markup is being used in other libraries for external APIs

Python stdlib:

Return whether an object is an instance of a class or of a subclass thereof.
    
    A tuple, as in ``isinstance(x, (A, B, ...))``, may be given as the target to
    check against. This is equivalent to ``isinstance(x, A) or isinstance(x, B)
    or ...`` etc.

double backtics to highlight the code (and probably make it linkable).

Am I missing something here?

[ghost]

@shcheklein , there are plenty docstring formats: https://stackoverflow.com/questions/3898572/what-is-the-standard-python-docstring-format

From PEP 287:

Text enclosed in single backquotes is recognized as "interpreted text", whose interpretation is application-dependent. In the context of a Python docstring, the default interpretation of interpreted text is as Python identifiers. The text will be marked up with a hyperlink connected to the documentation for the identifier given

Not sure if any particular IDE takes advantages of such feature.

we don't use them anywhere else

@Suor, we actually do 😅 but it is quite inconsistent:

grep -R '`.*`' dvc

---

I'd say that there's no need to block a PR for this. I created a separate issue to discuss the formatting across the code base: #3176

[shcheklein]

Not sure if any particular IDE takes advantages of such feature.

yep, all of those I've used at least.

[jorgeorpinel]

Text enclosed in single backquotes is recognized as "interpreted text"... In the context of a Python docstring, the default interpretation of interpreted text is as Python identifiers. The text will be marked up with a hyperlink connected to the documentation for the identifier given

This is what I was going for here. So keep it for now guys? I don't initially have a strong opinion.

there a standard way of doing markup that is understood by the tools that generate a view for this (like F1 in PyCharm, quick help in VS Code, docs generators, etc)

Yeah great question @shcheklein! I'll look it up.

[jorgeorpinel]

Extracted docstring format discussion fully to #3176 (comment)

[jorgeorpinel]

So to resolve this one @Suor, as most available formats use backquotes except Google's, are you able to approve this for the time being? We will revisit this once #3176 is resolved anyway.

[pared]

One comment

[Suor]

I don't like backticks, we don't use them anywhere else. Python stdlib doesn't use them either.

[ghost]

Why not "local repositories"? Not sure I understand what's a local DVC project.

[jorgeorpinel]

A DVC project isn't always a repo. It can be initialized with --no-scm and you can provide the local path to that project in the file system to the repo argument (misleading name BTW) of API functions.

[ghost]

I'm going to say yes. 😅
Thanks, @jorgeorpinel

[efiop]

Thanks @jorgeorpinel !