Improve docs for writing docs
Categories
(Developer Infrastructure :: Source Documentation, task, P3)
Tracking
(firefox73 wontfix, firefox74 fixed)
People
(Reporter: ahal, Assigned: championshuttler)
References
(Blocks 1 open bug)
Details
Attachments
(2 files, 1 obsolete file)
We have a (very sparse) section on how to add docs to the firefox-source-docs
here:
https://firefox-source-docs.mozilla.org/tools/moztreedocs/
But this is A) difficult to find as you need to scroll down past dozens of links to see it, and B) leaves out many important details and features of the system. We should move this to its own page that is linked to from the index and expand it to cover all the details necessary to use this system.
Reporter | ||
Comment 1•5 years ago
•
|
||
Some things we should be sure to cover:
- server upload/synchronization
- more details on building docs
- more details on moz.build registration
- redirects
- nested doc trees
- mermaid integration
- rst linter (just a quick link to the linter page)
- markdown support
- jsdoc support
Comment 2•5 years ago
•
|
||
(In reply to Andrew Halberstadt [:ahal] from comment #1)
Some things we should be sure to cover:
- server upload/synchronization
- more details on building docs
- more details on moz.build registration
- redirects
- nested doc trees
- mermaid integration
- rst linter (just a quick link to the linter page)
- markdown support
Bug 1389341 added support for building API docs from jsdoc, but I don't think we added any documentation on how to actually use this. It would be really nice to do so if you think it's in-scope.
Reporter | ||
Comment 3•5 years ago
|
||
(In reply to Robert Helmer [:rhelmer] from comment #2)
Bug 1389341 added support for building API docs from jsdoc, but I don't think we added any documentation on how to actually use this. It would be really nice to do so if you think it's in-scope.
+1. We can leave-open
this bug and get these sections added one at a time. E.g, I don't know how to use jsdoc
so would be good if you or someone else with more experience documented it.
Shivam is going to look into creating a standalone doc tree to house all this stuff.
Assignee | ||
Comment 4•5 years ago
|
||
Comment 5•5 years ago
|
||
(In reply to Andrew Halberstadt [:ahal] from comment #3)
(In reply to Robert Helmer [:rhelmer] from comment #2)
Bug 1389341 added support for building API docs from jsdoc, but I don't think we added any documentation on how to actually use this. It would be really nice to do so if you think it's in-scope.
+1. We can
leave-open
this bug and get these sections added one at a time. E.g, I don't know how to usejsdoc
so would be good if you or someone else with more experience documented it.Shivam is going to look into creating a standalone doc tree to house all this stuff.
OK cool. Here is an introductory bit I sent to the firefox-dev list, in retrospect I should have just added it to firefox-source-docs :)
===
Here is a quick example, for the public AddonManager API:
https://firefox-source-docs.mozilla.org/toolkit/mozapps/extensions/addon-manager/AddonManager.html
To use it for your own code:
- Check that JSDoc generates the output you expect (you may need to
use a @class annotation on "object initializer"-style class definitions for
instance) - Create an .rst file, which may contain explanatory text as well as
the API docs. The minimum will look something like
https://firefox-source-docs.mozilla.org/_sources/toolkit/mozapps/extensions/addon-manager/AddonManager.rst.txt - Ensure your component is on the js_source_path here in the sphinx
config: https://hg.mozilla.org/mozilla-central/file/72ee4800d415/tools/docs/conf.py#l46 - Run
mach doc
locally to generate the output and confirm that it
looks correct
===
Shivam, do you want to work this into the doc you are doing, or would you rather I put this elsewhere (maybe linked from yours?)
Thanks!
Assignee | ||
Comment 6•5 years ago
|
||
Hi Robert, I will add it in my patch :)
Comment 7•5 years ago
|
||
Any idea when you might manage to do that, Shivam?
Updated•4 years ago
|
Assignee | ||
Comment 8•4 years ago
|
||
Assignee | ||
Updated•4 years ago
|
Updated•4 years ago
|
Pushed by sledru@mozilla.com: https://hg.mozilla.org/integration/autoland/rev/77b3c9083a9d Improve docs for writing docs.r=sylvestre
Comment 10•4 years ago
|
||
bugherder |
Comment 11•4 years ago
|
||
Thanks for improving things here, Shivam!
Sylvestre, per your comment in the phab rev, I have work in progress for Layout docs that uses the Mermaid integration. Please don't remove it. :) (needinfo just to make sure you see this.)
Assignee | ||
Comment 12•4 years ago
|
||
Hi,
Sorry for taking so long.
Sure thing we will not remove it now, even improving the docs with the example now https://phabricator.services.mozilla.com/D58684. Feel free to update the docs if you find something missing. Clearing ni for him ;).
Assignee | ||
Updated•4 years ago
|
Updated•4 years ago
|
Assignee | ||
Comment 13•4 years ago
|
||
Comment 14•4 years ago
|
||
(In reply to Shivam Singhal [ :championshuttler ] from comment #12)
Sorry for taking so long.
No worries. Life happens. :)
Sure thing we will not remove it now, even improving the docs with the example now https://phabricator.services.mozilla.com/D58684. Feel free to update the docs if you find something missing. Clearing ni for him ;).
Awesome. Thank you!
Comment 15•4 years ago
|
||
Pushed by sledru@mozilla.com: https://hg.mozilla.org/integration/autoland/rev/91f9a82f172c Fix the sphinx UI Issue and update the redirects link.r=sylvestre
Updated•4 years ago
|
Comment 16•4 years ago
|
||
bugherder |
Updated•4 years ago
|
Updated•4 years ago
|
Updated•4 years ago
|
Updated•4 years ago
|
Assignee | ||
Comment 18•4 years ago
|
||
Hey,
Naah, docs for supporting markdown and few other things left , will submit the patch for them soon then we can close this bug ;)
Comment 19•4 years ago
|
||
The leave-open keyword is there and there is no activity for 6 months.
:rstewart, maybe it's time to close this bug?
Assignee | ||
Comment 20•4 years ago
|
||
I think we can close this and file bugs on forward for the docs missing later on
WDYT Sylvestre?
Comment 21•4 years ago
|
||
indeed, thanks
Updated•4 years ago
|
Updated•2 years ago
|
Description
•