Closed Bug 1576912 Opened 11 months ago Closed 19 days ago

Improve docs for writing docs

Categories

(Firefox Build System :: Generated Documentation, task, P3)

task

Tracking

(firefox73 wontfix, firefox74 fixed)

RESOLVED FIXED
mozilla74
Tracking Status
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.

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

(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.

(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.

(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 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.

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:

  1. Check that JSDoc generates the output you expect (you may need to
    use a @class annotation on "object initializer"-style class definitions for
    instance)
  2. 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
  3. 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
  4. 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!

Flags: needinfo?(shivams2799)

Hi Robert, I will add it in my patch :)

Flags: needinfo?(shivams2799)

Any idea when you might manage to do that, Shivam?

Flags: needinfo?(shivams2799)
Assignee: nobody → shivams2799
Attachment #9089158 - Attachment is obsolete: true
Status: NEW → ASSIGNED
Flags: needinfo?(shivams2799)
Attachment #9118274 - Attachment description: Bug 1576912 - Improve docs for writing docs.r=sylvestre,ahal → Bug 1576912 - Improve docs for writing docs.r=sylvestre
Pushed by sledru@mozilla.com:
https://hg.mozilla.org/integration/autoland/rev/77b3c9083a9d
Improve docs for writing docs.r=sylvestre
Status: ASSIGNED → RESOLVED
Closed: 7 months ago
Resolution: --- → FIXED
Target Milestone: --- → mozilla73

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.)

Flags: needinfo?(sledru)

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 ;).

Flags: needinfo?(sledru)
Status: RESOLVED → REOPENED
Keywords: leave-open
Resolution: FIXED → ---

(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!

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
Target Milestone: mozilla73 → mozilla74

Can this be closed now?

Flags: needinfo?(shivams2799)

Hey,

Naah, docs for supporting markdown and few other things left , will submit the patch for them soon then we can close this bug ;)

Flags: needinfo?(shivams2799)

The leave-open keyword is there and there is no activity for 6 months.
:rstewart, maybe it's time to close this bug?

Flags: needinfo?(rstewart)

I think we can close this and file bugs on forward for the docs missing later on
WDYT Sylvestre?

Flags: needinfo?(rstewart) → needinfo?(sledru)

indeed, thanks

Status: REOPENED → RESOLVED
Closed: 7 months ago19 days ago
Flags: needinfo?(sledru)
Resolution: --- → FIXED
You need to log in before you can comment on or make changes to this bug.