Interactive synopsis Fix #2024

[yathomasi]

Feature mentioned on #2024 .

Needs:

• Special place/way to specify command arguments in pages of https://dvc.org/doc/command-reference
• link to them from the synopsis? (as well as to -- options)
• Have anchors for each argument and option

We may not actually need the different/special way to specify command arguments because current enclosing with enclosing brackets should be fine. But, we need to define some set of rules/guidelines so that we are consistent throughout the documentation and also it's would be great to define the parser.

• define some guidelines for arguments and options(no need as it's defined by argsparse on similar pattern)
• parse synopsis code block and add anchor # tags to the arguments
• make sure change in Code component doesn't affect existing syntax highlighting
• parse options and add respective id for anchor tags

@iterative/websites @shcheklein @iterative/docs

---

After merge:

• Change isolated option mentions throughout important docs so they auto-link e.g. from "...use the --out option of dvc import," to just "use dvc import --out."

[julieg18]

Great work so far!

[julieg18]

But, we need to define some set of rules/guidelines so that we are consistent throughout the documentation and also it's would be great to define the parser.

One idea that comes to mind is having our /command-reference/RANDOM_COMMAND#options section setup like our glossary page, with each item in the list having a link attached to it. The links in the Synopsis section would take you the desired list item in the options section.

[yathomasi]

One idea that comes to mind is having our /command-reference/RANDOM_COMMAND#options section setup like our glossary page, with each item in the list having a link attached to it. The links in the Synopsis section would take you the desired list item in the options section.

Yeah, that's the idea. But, I am having a little bit issue with adding the HTML id attribute to the markdown AST.

[julieg18]

Yeah, that's the idea. But, I am having a little bit issue with adding the HTML id attribute to the markdown AST.

Feel free to message me in Slack if you want to discuss possible solutions!

[yathomasi]

@iterative/docs
Some assumptions here are:

1. arguments are always enclosed in square brackets eg: [-h]
2. arguments that need to be linked start with - or --. eg: [-h] [--version]
3. Option definition on the list starts with the respective inline code block which also starts with - or --
   Eg:

• -h

These are the assumptions taken and these need to be converted into guidelines/rules.
For my quick overview look, I could not see edge cases for now. Please, mention them if there could be some.

[casperdcl]

These are the assumptions taken and these need to be converted into guidelines/rules.

It's just the output from dvc ... --help as generated by argparse so I don't think any manual rules are needed.

[casperdcl]

looking good

[julieg18]

Looks good! I did notice some minor things, but I think we could still merge this and fix them on a later iteration.

[julieg18]

Looks awesome! Reading through all of the comments, there is still a couple things to do but we could create a issue listing the rest of the tasks to do later. If everyone else agrees, I think we could merge this!

[rogermparent]

Definitely looks good enough to me to be merged as a first iteration!

[shcheklein]

Looks good to me! Good stuff with the prism hook - less code == better sleep :)

Two small things. First, could we please move icon a bit down to align it better with the bullets?

And please still review and resolve the existing comments (it's totally fine if you think that it's not the right time to address, or you want to keep certain things the way it is, but it's a good practice to react and say that we are moving forward).

[yathomasi]

We had headings icons aligned similarly, so I had left it as it was.
I have just made the change and this looks nice with bullet points.

If we want more aesthetic changes, we can continue on another iteration.

Similarly, looks like I had missed another conversation. I have gone through and updated them with the necessary changes.

Here is the listing we would need discussion or move to another iteration:

• plain mentions of options inside a cmd ref. could be auto-linked to that anchor e.g. mention of --no-commit, which would be linked to #--no-commit
• making args-linker more strict to the Options section
• making aesthetic/UI changes for the anchor tags on synopsis or anchor icon on list options.

I think these are all, please mention if I have missed any.

[shcheklein]

Thanks @yathomasi !