Dvclive api reference

[daavoo]

You may disregard these recommendations if you used the Edit on GitHub button from dvc.org to improve a doc in place.

❗ Please read the guidelines in the Contributing to the Documentation list if you make any substantial changes to the documentation or JS engine.

🐛 Please make sure to mention Fix #issue (if applicable) in the description of the PR. This causes GitHub to close it automatically when the PR is merged.

Please choose to allow us to edit your branch when creating the PR.

Thank you for the contribution - we'll try to review it as soon as possible. 🙏

Closes iterative/dvclive#108

[dberenbaum]

Great work! This looks really nice as a first draft. I'd also like to get someone from the docs team to review before merging (cc @jorgeorpinel).

We should also open a discussion on whether to include this in docstrings. I know there was already some discussion on autogenerating docs, but I think even if we have to duplicate text, it's worth considering for dvclive. IMO docstrings are generally accepted practice for a lot of ML libraries and could encourage contributions.

[daavoo]

We should also open a discussion on whether to include this in docstrings. I know there was already some discussion on autogenerating docs, but I think even if we have to duplicate text, it's worth considering for dvclive. IMO docstrings are generally accepted practice for a lot of ML libraries and could encourage contributions.

I agree that it's worth to add the docstrings to dvclive even by copy-pasting content from here. I think I will wait for this P.R. to be merged and after that add the docstrings.

[dberenbaum]

@jorgeorpinel Should we assign a reviewer from the docs team?

[shcheklein]

future improvement: we should create a ticket or improve auto-linker, to keep text clean from these internal links like we do in DVC API reference

[jorgeorpinel]

iterative/dvclive#114

[shcheklein]

some minor comments:

• try to use more links, "abbr" tooltips, for people better understand certain concepts
• write and prioritize the work on the ticket that would allow us to get rid of the explicit MD links to api reference - that should be very easy, similar to DVC.

[shcheklein]

Btw, on docstrings, I do think we need to include them (way simpler version though).

Also, as a next step, do we want to write some examples for these APIs?

[jorgeorpinel]

Hi 👋 just noticed this. I have lots of comments. Nothing super major but a few relevant questions and suggestions, and lots of minor ones (e.g. copy edits). A couple cosmetic ones 💅 too

Thanks

[jorgeorpinel]

p.s. @daavoo I realize you may be focused on development so one option is to create a future docs improvement ticket linking to my #2632 (review) above. Maybe we can even work on it ourselves (docs team) — we can discuss in a planning meeting. Tanks

[jorgeorpinel]

UPDATE: I guess could be part of iterative/dvclive/issues/86 but that's already a pretty long one 😅 kind of an epic?

[daavoo]

p.s. @daavoo I realize you may be focused on development so one option is to create a future docs improvement ticket linking to my #2632 (review) above. Maybe we can even work on it ourselves (docs team) — we can discuss in a planning meeting. Tanks

I was already addressing your suggestions locally. My personal opinion is that, for dvclive, extending existing documentation would be more valuable at this point than development of new features and that is also what we have agreed at our planning.

[daavoo]

UPDATE: I guess could be part of iterative/dvclive/issues/86 but that's already a pretty long one sweat_smile kind of an epic?

Yep. I tried to use the Github tasks feature to create new issues from the task list. Will create a new one for this API Reference updates.

[shcheklein]

@jorgeorpinel to clarify, @daavoo 's scope of work includes writing docs/README and other product things, not only engineering. It's expected that he takes of the product holistically (similar to Casper's work on CML I think).

[jorgeorpinel]

Got it, thanks guys.