Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: replace dvc code block lang. for cli #1369

Closed
jorgeorpinel opened this issue May 28, 2020 · 10 comments
Closed

doc: replace dvc code block lang. for cli #1369

jorgeorpinel opened this issue May 28, 2020 · 10 comments
Labels
A: docs Area: user documentation (gatsby-theme-iterative) good first issue Good for newcomers help wanted Contributors especially welcome p2-nice-to-have Less of a priority at the moment. We don't usually deal with this immediately. type: enhancement Something is not clear, small updates, improvement suggestions

Comments

@jorgeorpinel
Copy link
Contributor

jorgeorpinel commented May 28, 2020

We use ```dvc for all kinds of console session examples throughout blocks, not just DVC commands (sometimes there's no DVC command in the block). Maybe we should change to ```cli? or ```console (standard)

This applies to Markdown file processing.

UPDATE: See #1369 (comment) below.

@jorgeorpinel jorgeorpinel added type: enhancement Something is not clear, small updates, improvement suggestions website: eng-doc DEPRECATED JS engine for /doc good first issue Good for newcomers labels May 28, 2020
@jorgeorpinel jorgeorpinel changed the title doc: change dvc code bllock highlight for cli doc: change dvc code block highlight for cli May 28, 2020
@jorgeorpinel jorgeorpinel added the A: docs Area: user documentation (gatsby-theme-iterative) label May 28, 2020
@shcheklein
Copy link
Member

My 2cs. It's too specific too dvc I would say - it's literally bash + dvc syntax. cli or console are too generic? and can overlap with existing highlighters?

@jorgeorpinel jorgeorpinel added the type: discussion Requires active participation to reach a conclusion. label May 28, 2020
@jorgeorpinel
Copy link
Contributor Author

Yes maybe you're right.

can overlap with existing highlighters?

There are other built-in highlighters? I thought we only had dvc, usage, py, json, and yaml

@shcheklein
Copy link
Member

yep, there are some taken already https://prismjs.com/#supported-languages

@shcheklein shcheklein added the A: website Area: website label May 28, 2020
@jorgeorpinel
Copy link
Contributor Author

Nice. So neither cli nor console are taken (the latter I know Github has but it's custom to them). Only bash and shell are taken.

@jorgeorpinel
Copy link
Contributor Author

It's too specific too dvc I would say - it's literally bash + dvc syntax

Yes but what if in the future we want to support special highlighting in the YAML file since there are some DVC schema specific fields in .dvc files and dvc.yaml? We would just extend the yaml highlight right? Same for bash in that case, we should just use the existing one and extend it. Except we have users in all sorts of shells, not just Bash, thus I vote for console (copying GH) or just cli which can be based of bash.

But anyway this is a minor detail over all. No strong opinion or any urgency

@shcheklein
Copy link
Member

Good point, @jorgeorpinel ! I think console is good then. I wonder how will GH highlight it.

@MerlynMShelley
Copy link

We use ```dvc for all kinds of console session examples throughout blocks, not just DVC commands (sometimes there's no DVC command in the block). Maybe we should change to ```cli? or ```console (standard)

This applies to Markdown file processing.

Yep, in workflows it's quite easy to understand the standard console to describe a console session.

@MayankGoel28
Copy link

@jorgeorpinel is this a generic substitution of all ```dvc to ```console? Wanted to confirm as there's some discussion on this. If so, I can apply a regex script to do so.

@jorgeorpinel jorgeorpinel removed the good first issue Good for newcomers label Jun 11, 2020
@jorgeorpinel
Copy link
Contributor Author

Hi @MayankGoel28 and sorry for the delay (we're really busy recently releasing DVC 1.0). No, this would require customization of the JS engine code first, and then also changing the md content, yes.

@jorgeorpinel jorgeorpinel changed the title doc: change dvc code block highlight for cli doc: change dvc code block highlight for cli Jun 2, 2022
@jorgeorpinel jorgeorpinel changed the title doc: change dvc code block highlight for cli doc: change dvc code block lang. for cli Jun 2, 2022
@jorgeorpinel jorgeorpinel removed website: eng-doc DEPRECATED JS engine for /doc type: discussion Requires active participation to reach a conclusion. A: website Area: website labels Jun 2, 2022
@jorgeorpinel jorgeorpinel changed the title doc: change dvc code block lang. for cli doc: replace dvc code block lang. for cli Jun 2, 2022
@jorgeorpinel
Copy link
Contributor Author

This will be resolved by #3396 but we can keep this open to update the contents (mass-replace ```dvc for ```cli.

@jorgeorpinel jorgeorpinel added help wanted Contributors especially welcome good first issue Good for newcomers p2-nice-to-have Less of a priority at the moment. We don't usually deal with this immediately. labels Jun 2, 2022
@dberenbaum dberenbaum closed this as not planned Won't fix, can't repro, duplicate, stale Oct 17, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A: docs Area: user documentation (gatsby-theme-iterative) good first issue Good for newcomers help wanted Contributors especially welcome p2-nice-to-have Less of a priority at the moment. We don't usually deal with this immediately. type: enhancement Something is not clear, small updates, improvement suggestions
Projects
None yet
Development

No branches or pull requests

5 participants