1566932 - Add new docs directory in browser/components/urlbar and move AddressBar.rst there

Status: RESOLVED FIXED

(Firefox :: Address Bar, task, P1)

Description

[Drew Willcoxon :adw]

Omkar and I are going to add docs for the process of implementing and shipping urlbar extension experiments (starting with the top sites experiment and the contextual tips experiment). Mike suggested that we move urlbar docs from browser/docs into a new browser/components/urlbar/docs and add new docs there, linking to them from browser/docs/index.rst.

Comment 1

[Drew Willcoxon :adw]

We might also consider splitting up AddressBar.rst into multiple docs. We'd also want a top-level index/contents doc of course.

Comment 2

[Marco Bonardo [:mak] (Away Apr 25 - May 5)]

Just fyi, that means the urlbar docs won't be anymore under "Firefox", that was the main reason to keep it in browser/docs (though nobody seems to really care about having a well organized structure)

Comment 3

[Mark Banner (:standard8)]

(In reply to Marco Bonardo [::mak] from comment #2)

Just fyi, that means the urlbar docs won't be anymore under "Firefox", that was the main reason to keep it in browser/docs (though nobody seems to really care about having a well organized structure)

Some of us do (e.g. see Toolkit), unfortunately we're waiting for redirect support so that we can move the other pages around (without also breaking existing links).

You might be able to move the file to browser/components/urlbar/docs, if in browser/components/urlbar/moz.build you add:

SPHINX_TREES['/browser/browser/'] = 'docs'

I'm not quite sure if that'll work with existing docs in that directory or not.

Alternately you could do something like

SPHINX_TREES['/browser/browser/urlbar'] = 'docs'

and then change the reference in browser/docs/index.rst.

I think one of those two options should work. Just a warning that if you end up moving the page on the server, then the old page might stay there until you can find someone who can remove it.

Comment 4

[Mike de Boer [:mikedeboer]]

(In reply to Mark Banner (:standard8) from comment #3)

(In reply to Marco Bonardo [::mak] from comment #2)

Just fyi, that means the urlbar docs won't be anymore under "Firefox", that was the main reason to keep it in browser/docs (though nobody seems to really care about having a well organized structure)

Some of us do (e.g. see Toolkit), unfortunately we're waiting for redirect support so that we can move the other pages around (without also breaking existing links).

It should work, really, since I don't see any orphaned docs in Toolkit/ either.

Please don't worry about redirect support right now; the impact of a broken link would be small enough that it only hits a circle quite close to us. I don't see the use of these docs right now other than Mozilla frontend devs.

Comment 5

[Mark Banner (:standard8)]

(In reply to Mike de Boer [:mikedeboer] from comment #4)

It should work, really, since I don't see any orphaned docs in Toolkit/ either.

That was kinda a fluke as the top-level toolkit/ docs hadn't been created already, and we were able to get it in the right place without moving everything. Now I look at it again, we might actually be able to get the top-level of browser working correctly, if we don't mind moving just that top-level doc. I've filed bug 1567121 to take a look.

Comment 6

[Mike de Boer [:mikedeboer]]

Ooh, I stand corrected - thanks for checking that out! :)

Comment 7

[Drew Willcoxon :adw]

Yes, I was planning on linking to the ulbar docs from Firefox's index.rst or somewhere else. Thanks for the tips, Mark.

Bug 1547676 covers the experiment doc(s) specifically, so removing that from the summary.

Comment 8

[Drew Willcoxon :adw]

There's a top-level browser directory in the docs that already has a bunch of subdirectories, like for tabbrrowser, Firefox Home, WebPayments, form autofill, and installer. And then there's a browser/browser subdirectory with... a top-level Firefox index, AddressBar, and Browser Usage Telemetry? Why is this such a mess? Why isn't everything related to Firefox/browser listed under Firefox? Should urlbar be listed as a top-level doc, too?

I'd really like to clean all this up first by moving all Firefox docs under the Firefox index...

Comment 9

[Drew Willcoxon :adw]

(In reply to Mark Banner (:standard8) (afk 19th - 28th July) from comment #3)

Some of us do (e.g. see Toolkit), unfortunately we're waiting for redirect support so that we can move the other pages around (without also breaking existing links).

I guess that's what this comment refers to?

Comment 10

[Drew Willcoxon :adw]

Attachment: Bug 1566932 - Move quantumbar docs to browser/components/urlbar/docs.

• Move AddressBar.rst into a new browser/components/urlbar/docs directory
• Break it up into several files, which makes the patch look way bigger than it really is because I used hg cp to preserve blame
• Add Extensions and Experiments files/subsections, to be written later
• Rewrite the intro a little for wording and also to reflect the fact that quantumbar has shipped, and also tweak the wording of some subsection titles

Comment 11

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/integration/autoland/rev/856b77a3440f
Move quantumbar docs to browser/components/urlbar/docs. r=mak

Comment 12

[Cristian Brindusan [:cbrindusan]]

https://hg.mozilla.org/mozilla-central/rev/856b77a3440f