Site-www: Improve/update pub pages

[kwalrath]

I found some non-urgent issues when doing a survey of all the pages under https://www.dartlang.org/tools/pub/cmd. (I was comparing them to the output of pub help <cmd>, for pub version 2.1.0). Here are my notes, in case anyone has a yen to improve these pages:

• pub help and pub version don't have pages. (I don't think this is a problem, since they're kind of obvious.)
• I filed dart-lang/pub#2001 about small issues with the pub command's references to doc pages.
• No pages talk about the no- modifier to -- options. (I don't think this is a problem, since it's in the help.)
• Options section contents and formatting aren't consistent.
• pub deps page is missing --dev and --executables.
• pub downgrade page is missing -n, --dry-run. (Why doesn't pub downgrade have --precompile?)
• pub get and pub upgrade pages are missing --precompile and -n, --dry-run.

There was a more important issue in pub run, which I'm fixing in #1255.

[kwalrath]

Also see #1342, which mentions that all the pub pages could probably use a look-through.

[sil3nthill]

hello i would like to work for this and make a PR , what should i exactly do ?

[kwalrath]

@sil3nthill thank you for the offer! We're in the middle of a bunch of site changes, so we're avoiding content changes until after I/O (early May).

Would you be willing to look at this in May?

[gryclmn]

I would like to help with this issue as well for a first time PR. How can I help?

[Purukitto]

@kwalrath Is this issue fixed to satisfaction or can I contribute to it?

[kwalrath]

Sorry, @sil3nthill, @gryclmn, and @Purukitto for not getting back to you sooner!

We're ready to accept changes on these pages now. What I'd love is for each of you to claim one page (here in a comment) and create a PR for that page fixing whatever issues I noted above for the page. I'm open to any other fixes you deem necessary, as well.

Once we have a single-page PR from you, then we can figure out how to organize the rest of the work.

Does that sound OK?

[Purukitto]

@kwalrath

Does that sound OK?

Sure does

pub help and pub version don't have pages. (I don't think this is a problem, since they're kind of obvious.)

They are indeed obvious but adding these must not break anyone and I feel they should be listed as they are cmds anyways

Options section contents and formatting aren't consistent.

I'm not sure but it does look fine to me, maybe it was fixed?

What I'd love is for each of you to claim one page (here in a comment) and create a PR for that page fixing whatever issues I noted above for the page.

If you agree on adding help and version pages I can get started on them, otherwise I'm open to take up any other page

[kwalrath]

I would not mind at all if you added help and version pages. The only thing about adding new pages is that it would be a more involved change — you'd need to have the whole build working.

If you just make a change within an existing page, then you wouldn't necessarily need to build the whole site.

[Purukitto]

@kwalrath

I would not mind at all if you added help and version pages. The only thing about adding new pages is that it would be a more involved change — you'd need to have the whole build working.

If you just make a change within an existing page, then you wouldn't necessarily need to build the whole site.

Since I have no idea what that means exactly I don't think I should start on something that big as of now.
I'll check the other points and see what stuff I can come up with for them since no one else seemed to be claiming those

[jtxmp]

Hi @kwalrath,

Can I have a go at these issues?

Options section contents and formatting aren't consistent.
pub deps page is missing --dev and --executables.
pub downgrade page is missing -n, --dry-run.
pub get and pub upgrade pages are missing --precompile and -n, --dry-run.

Proposing to align the options section contents and formatting with the 'Global Options' section found in https://dart.dev/tools/pub/cmd.

I can do a single-page PR on pub deps page first, do let me know.

[kwalrath]

Doing a single-page PR for pub deps would be a great way to start. It's yours, @jtxmp!

[jtxmp]

Thanks, @kwalrath!

I'll move on to pub downgrade now, in the same style as pub deps.

The default and negatable options stumped me too in #2099. Will study how others have done it for a future PR.