1349256 - Clean-up our /devtools/docs a bit

Status: RESOLVED FIXED

(DevTools :: General, enhancement, P3)

Description

[Patrick Brosset <:pbro>]

I think we could clean things up a bit in a number of ways:

- README.md contains some contribution information. We have this duplicated in so many places already that I feel like we should just remove the info from this file.

- All docs are flat under /devtools/docs, there is no structure. So if you look at SUMMARY.md then you get the structure, but if you just browse the disk, it would be nice if the files were organized in a way that matches SUMMARY.md

- We intended, at first at least, to generate HTML versions of our docs online using gitbook. I think it's still a good idea, but we haven't documented how to do that anywhere.

- We have 2 docs folders: /devtools/docs and /devtools/server/docs
I don't think this is useful. First of all it's confusing because the main folder also contains server-related docs. And the docs folder inside server is harder to find.
Let's just consolidate in one place.

Comment 1

[Patrick Brosset <:pbro>]

I'll push a few commits for this, and will ask what people think about it.

Comment 2

[Patrick Brosset <:pbro>]

Attachment: Bug 1349256 - Rephrase README.md a bit and remove dup information;

Review commit: https://reviewboard.mozilla.org/r/122380/diff/#index_header
See other reviews: https://reviewboard.mozilla.org/r/122380/

Comment 3

[Patrick Brosset <:pbro>]

Attachment: Bug 1349256 - Moved docs into folders so it's easier to browse;

Review commit: https://reviewboard.mozilla.org/r/122382/diff/#index_header
See other reviews: https://reviewboard.mozilla.org/r/122382/

Comment 4

[Patrick Brosset <:pbro>]

Attachment: Bug 1349256 - Added docs about how to generate the gitbook;

Review commit: https://reviewboard.mozilla.org/r/122384/diff/#index_header
See other reviews: https://reviewboard.mozilla.org/r/122384/

Comment 5

[Patrick Brosset <:pbro>]

Attachment: Bug 1349256 - Added a link to the debugger.html documentation;

Review commit: https://reviewboard.mozilla.org/r/122386/diff/#index_header
See other reviews: https://reviewboard.mozilla.org/r/122386/

Comment 6

[Patrick Brosset <:pbro>]

Attachment: Bug 1349256 - Merged server and general docs under just one directory;

Review commit: https://reviewboard.mozilla.org/r/122388/diff/#index_header
See other reviews: https://reviewboard.mozilla.org/r/122388/

Comment 7

[Soledad Penades [:sole] [:spenades]]

Comment on attachment 8849599 [details]
Bug 1349256 - Rephrase README.md a bit and remove dup information;

https://reviewboard.mozilla.org/r/122380/#review124868

Missing a couple of edits so no + yet :)

::: devtools/docs/README.md:10
(Diff revision 1)
> -If you are looking to **start hacking** on the developer tools, all of
> +If you are looking for a getting started guide on the developer tools, all of this information is documented on the [Hacking](https://wiki.mozilla.org/DevTools/Hacking) wiki page.
> -this information is documented on the
> -[Hacking](https://wiki.mozilla.org/DevTools/Hacking) wiki page.
>  
> -A very quick version:
> +These docs explain how the developer tools work at high-level, as well as provide links to reference documentation.
> +This is a good starting point if you are a new contributor, or want to learn how our protocol, a specific tool, or something else works.

I think this paragraph is more or less rephrasing what the first one says, so you'd better move it above and delete half of it :)

::: devtools/docs/README.md:12
(Diff revision 1)
> -[Hacking](https://wiki.mozilla.org/DevTools/Hacking) wiki page.
>  
> -A very quick version:
> +These docs explain how the developer tools work at high-level, as well as provide links to reference documentation.
> +This is a good starting point if you are a new contributor, or want to learn how our protocol, a specific tool, or something else works.
>  
> -```
> +Head over to the [table of content](SUMMARY.md) to browse the documentation.

table of contentS

Comment 8

[Soledad Penades [:sole] [:spenades]]

Comment on attachment 8849600 [details]
Bug 1349256 - Moved docs into folders so it's easier to browse;

https://reviewboard.mozilla.org/r/122382/#review124870

Excellent!

Comment 9

[Soledad Penades [:sole] [:spenades]]

Comment on attachment 8849601 [details]
Bug 1349256 - Added docs about how to generate the gitbook;

https://reviewboard.mozilla.org/r/122384/#review124872

It's good to know how to generate the HTML version, but makes me wonder whether we are publishing it anywhere?

Comment 10

[Soledad Penades [:sole] [:spenades]]

Comment on attachment 8849602 [details]
Bug 1349256 - Added a link to the debugger.html documentation;

https://reviewboard.mozilla.org/r/122386/#review124874

Comment 11

[Soledad Penades [:sole] [:spenades]]

Comment on attachment 8849603 [details]
Bug 1349256 - Merged server and general docs under just one directory;

https://reviewboard.mozilla.org/r/122388/#review124876

Nice!

Comment 12

[Patrick Brosset <:pbro>]

(In reply to Soledad Penades [:sole] [:spenades] from comment #9)
> Comment on attachment 8849601 [details]
> Bug 1349256 - Added docs about how to generate the gitbook;
> 
> https://reviewboard.mozilla.org/r/122384/#review124872
> 
> It's good to know how to generate the HTML version, but makes me wonder
> whether we are publishing it anywhere?
Unfortunately not. James Long originally created these docs, and I think he hosted the gitbook somewhere on his server. But this has not been continued.

Thanks for the quick reviews sole!

Comment 13

[Patrick Brosset <:pbro>]

Comment on attachment 8849599 [details]
Bug 1349256 - Rephrase README.md a bit and remove dup information;

Review request updated; see interdiff: https://reviewboard.mozilla.org/r/122380/diff/1-2/

Comment 14

[Patrick Brosset <:pbro>]

Comment on attachment 8849600 [details]
Bug 1349256 - Moved docs into folders so it's easier to browse;

Review request updated; see interdiff: https://reviewboard.mozilla.org/r/122382/diff/1-2/

Comment 15

[Patrick Brosset <:pbro>]

Comment on attachment 8849601 [details]
Bug 1349256 - Added docs about how to generate the gitbook;

Review request updated; see interdiff: https://reviewboard.mozilla.org/r/122384/diff/1-2/

Comment 16

[Patrick Brosset <:pbro>]

Comment on attachment 8849602 [details]
Bug 1349256 - Added a link to the debugger.html documentation;

Review request updated; see interdiff: https://reviewboard.mozilla.org/r/122386/diff/1-2/

Comment 17

[Patrick Brosset <:pbro>]

Comment on attachment 8849603 [details]
Bug 1349256 - Merged server and general docs under just one directory;

Review request updated; see interdiff: https://reviewboard.mozilla.org/r/122388/diff/1-2/

Comment 18

[Soledad Penades [:sole] [:spenades]]

Comment on attachment 8849599 [details]
Bug 1349256 - Rephrase README.md a bit and remove dup information;

https://reviewboard.mozilla.org/r/122380/#review124898

Much better! :-)

Comment 19

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/integration/autoland/rev/7f8066747d03
Rephrase README.md a bit and remove dup information; r=sole
https://hg.mozilla.org/integration/autoland/rev/fd138b13a8f2
Moved docs into folders so it's easier to browse; r=sole
https://hg.mozilla.org/integration/autoland/rev/c70687e1b94f
Added docs about how to generate the gitbook; r=sole
https://hg.mozilla.org/integration/autoland/rev/098a2b99cc1b
Added a link to the debugger.html documentation; r=sole
https://hg.mozilla.org/integration/autoland/rev/354618874505
Merged server and general docs under just one directory; r=sole

Comment 20

[Sebastian Hengst [:aryx] (needinfo me if it's about an intermittent or backout)]

Backed out for build bustage: test_mozbuild_reading.py docs/memory-panel.md corresponds to no files:

https://hg.mozilla.org/integration/autoland/rev/a36b644a8bb5eec461fa92944ad366517781026b
https://hg.mozilla.org/integration/autoland/rev/6aca84425874fe9dc9b48acf8f13a0b1a69ff7e5
https://hg.mozilla.org/integration/autoland/rev/99aec35c1a14c93f05c8a1faffd01a2c72e5b317
https://hg.mozilla.org/integration/autoland/rev/2d332e1a7dc99b2518ca46fc9868d3e901fa4c29
https://hg.mozilla.org/integration/autoland/rev/422edf8678ad27d3ea687144467f68cb5f626c92

Push with failures: https://treeherder.mozilla.org/#/jobs?repo=autoland&revision=354618874505afa337ee7525d93ef701f28f5bd5&filter-resultStatus=testfailed&filter-resultStatus=busted&filter-resultStatus=exception&filter-resultStatus=retry&filter-resultStatus=usercancel&filter-resultStatus=runnable
Failure log: https://treeherder.mozilla.org/logviewer.html#?job_id=85631658&repo=autoland

[task 2017-03-22T14:24:16.853226Z] 14:24:16  WARNING - TEST-UNEXPECTED-FAIL | /home/worker/workspace/build/src/config/tests/test_mozbuild_reading.py | TestMozbuildReading.test_orphan_file_patterns, line 105: The pattern 'docs/memory-panel.md' in a Files() entry in '/home/worker/workspace/build/src/devtools/moz.build' corresponds to no files in the tree.
[task 2017-03-22T14:24:16.853402Z] 14:24:16     INFO - FAIL: test_orphan_file_patterns (__main__.TestMozbuildReading)
[task 2017-03-22T14:24:16.853573Z] 14:24:16     INFO - Traceback (most recent call last):
[task 2017-03-22T14:24:16.853791Z] 14:24:16     INFO -   File "/home/worker/workspace/build/src/config/tests/test_mozbuild_reading.py", line 105, in test_orphan_file_patterns
[task 2017-03-22T14:24:16.853950Z] 14:24:16     INFO -     (ctx.pattern, ctx.main_path))
[task 2017-03-22T14:24:16.854191Z] 14:24:16     INFO - AssertionError: The pattern 'docs/memory-panel.md' in a Files() entry in '/home/worker/workspace/build/src/devtools/moz.build' corresponds to no files in the tree.

Comment 21

[Patrick Brosset <:pbro>]

Comment on attachment 8849600 [details]
Bug 1349256 - Moved docs into folders so it's easier to browse;

Review request updated; see interdiff: https://reviewboard.mozilla.org/r/122382/diff/2-3/

Comment 22

[Patrick Brosset <:pbro>]

Comment on attachment 8849601 [details]
Bug 1349256 - Added docs about how to generate the gitbook;

Review request updated; see interdiff: https://reviewboard.mozilla.org/r/122384/diff/2-3/

Comment 23

[Patrick Brosset <:pbro>]

Comment on attachment 8849602 [details]
Bug 1349256 - Added a link to the debugger.html documentation;

Review request updated; see interdiff: https://reviewboard.mozilla.org/r/122386/diff/2-3/

Comment 24

[Patrick Brosset <:pbro>]

Comment on attachment 8849603 [details]
Bug 1349256 - Merged server and general docs under just one directory;

Review request updated; see interdiff: https://reviewboard.mozilla.org/r/122388/diff/2-3/

Comment 25

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/integration/autoland/rev/8413413d3399
Rephrase README.md a bit and remove dup information; r=sole
https://hg.mozilla.org/integration/autoland/rev/158ca18db474
Moved docs into folders so it's easier to browse; r=sole
https://hg.mozilla.org/integration/autoland/rev/39f0b1403283
Added docs about how to generate the gitbook; r=sole
https://hg.mozilla.org/integration/autoland/rev/68f93b517ec8
Added a link to the debugger.html documentation; r=sole
https://hg.mozilla.org/integration/autoland/rev/29877490028f
Merged server and general docs under just one directory; r=sole

Comment 26

[Patrick Brosset <:pbro>]

Clearing needinfo. I fixed the problem and landed again. Thanks for the backout!

Comment 27

[Wes Kocher (:KWierso) (Not reading bugmail; email directly if needed)]

https://hg.mozilla.org/mozilla-central/rev/8413413d3399
https://hg.mozilla.org/mozilla-central/rev/158ca18db474
https://hg.mozilla.org/mozilla-central/rev/39f0b1403283
https://hg.mozilla.org/mozilla-central/rev/68f93b517ec8
https://hg.mozilla.org/mozilla-central/rev/29877490028f