remote: create separate sections for remote types

[ghost]

Instead of having expandable boxes on each remote sub-command, let's create separate sections for each remote, adding more information when needed.

For example, with SSH, you can increment the MaxSessions in your sshd configuration to increase the push/pull operations, also, would be great to add some information (or links) about using key files instead of passwords. With S3 you can configure the remote in different ways, even using environment variables.

Each remote has its own configuration details, it would be great to have them separately.

[jorgeorpinel]

Good idea, no need to expand examples, just use:

## Examples: Local
...
## Examples: SSH
...

So are you working on this @MrOutis? If so perhaps assign yourself 🙂

[shcheklein]

I would say the title Examples looks strange for section that contains available options per remote type. Especially in the dvc remote modify. Those should be part of the options, or descriptions. Or have a different name at least. Otherwise I would prefer actually to see the full list of supported protocols and one click to see the specifics. Instead of huge text file that includes everything. In my experience it's easier to navigate long texts when there is some structure and less scary :)

[ryokugyu]

@shcheklein @jorgeorpinel @MrOutis I will suggest that under dvc remote let's have separate pages for each type of remote. maybe sort of tutorials. where we will describe:

1. configure a dvc remote from scratch
2. modify options
3. if multiple instances of a remote can exist together, then, how to use it.

[ghost]

@jorgeorpinel, I was thinking about using a page per remote because I'm assuming the user only wants to configure one remote, take for example SSH or S3, they would need to navigate through each remote sub-command finding their sections.

yep, @ryokugyu, that's the idea 👍

[jorgeorpinel]

Are you saying you want to split one command reference into several pages @MrOutis? How would that look on the navigation side bar? remote is already a menu with 5 sub-entries:

Or are we talking about a different existing page?

[ghost]

@jorgeorpinel , that remote section would stay like that, I'm planning to create a new one:

static/docs/remotes
├── azure.md
├── gs.md
├── hdfs.md
├── http.md
├── local.md
├── oss.md
├── s3.md
└── ssh.md

and move the "expandable" sections to each respective remote

[shcheklein]

I would say that's too much to have a separate top level section just for remotes. May be a section in the User Guide - something like "Configuring Remote Storages"?

[jorgeorpinel]

And do we remove the expanding sections from https://dvc.org/doc/commands-reference/remote-add and https://dvc.org/doc/commands-reference/remote-modify ?

[ghost]

@jorgeorpinel , the idea was to remove the expanding sections and replace them with a "top level section" for each remote; looks like it wasn't that good after all 😅 I'll close this

[jorgeorpinel]

Thanks anyway. Always good to explore improvement ideas 🙂

[dashohoxha]

I find this a good idea. I have been thinking the same but did not have a clear idea. These pages fit on User Guide.

[jorgeorpinel]

The command reference lists commands, not other kinds of things (e.g. remote types), so both refs for remote add and for remote modify have expandable examples for all the remote types. Would have to have a 3rd level in each of those with repetitive docs per remote type (which again, wouldn't be commands so not belonging to the cmd ref.) Refer to #703 for other ideas.