Clean-up our /devtools/docs a bit

RESOLVED FIXED in Firefox 55

Status

enhancement
P3
normal
RESOLVED FIXED
2 years ago
Last year

People

(Reporter: pbro, Assigned: pbro)

Tracking

unspecified
Firefox 55

Firefox Tracking Flags

(firefox55 fixed)

Details

Attachments

(5 attachments)

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.
Assignee: nobody → pbrosset
I'll push a few commits for this, and will ask what people think about it.
Status: NEW → ASSIGNED
Priority: -- → P3
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 on attachment 8849600 [details]
Bug 1349256 - Moved docs into folders so it's easier to browse;

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

Excellent!
Attachment #8849600 - Flags: review?(sole) → review+
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?
Attachment #8849601 - Flags: review?(sole) → review+
Comment on attachment 8849602 [details]
Bug 1349256 - Added a link to the debugger.html documentation;

https://reviewboard.mozilla.org/r/122386/#review124874
Attachment #8849602 - Flags: review?(sole) → review+
Comment on attachment 8849603 [details]
Bug 1349256 - Merged server and general docs under just one directory;

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

Nice!
Attachment #8849603 - Flags: review?(sole) → review+
(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 on attachment 8849599 [details]
Bug 1349256 - Rephrase README.md a bit and remove dup information;

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

Much better! :-)
Attachment #8849599 - Flags: review?(sole) → review+
Pushed by pbrosset@mozilla.com:
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
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.
Flags: needinfo?(pbrosset)
Pushed by pbrosset@mozilla.com:
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
Clearing needinfo. I fixed the problem and landed again. Thanks for the backout!
Flags: needinfo?(pbrosset)
Product: Firefox → DevTools
You need to log in before you can comment on or make changes to this bug.