986719 - Centralized documentation for UITelemetry

Status: RESOLVED FIXED

(Firefox for Android Graveyard :: General, defect)

Description

[Richard Newman [:rnewman]]

We should have in-tree generated docs for the data we're producing. Now we have Bug 939367, we can do it!

This bug tracks creating the stub.

Comment 1

[Nick Alexander :nalexander [he/him]]

This is easy and awesome:

http://mxr.mozilla.org/mozilla-central/source/tools/docs/index.rst#30

One thing that's not obvious, though, is how to have documentation for the desktop and Fennec implementations of UITelemetry close to each other.

Comment 2

[Gregory Szorc [:gps]]

The in-tree docs are considered not part of the build and they do crazy things like install 3rd party Python libraries from PyPI.

A brief search of the internets for "sphinx javadoc" reveals cool projects like http://bronto.github.io/javasphinx/ that allow you to incorporate javadoc output into Sphinx. I think adding javadocs to the output of |mach build-docs| would be a nifty feature!

Let me know if you'd like to pursue something more official for Java docs integration.

Comment 3

[Gregory Szorc [:gps]]

(In reply to Nick Alexander :nalexander from comment #1)
> This is easy and awesome:
> 
> http://mxr.mozilla.org/mozilla-central/source/tools/docs/index.rst#30
> 
> One thing that's not obvious, though, is how to have documentation for the
> desktop and Fennec implementations of UITelemetry close to each other.

See tools/docs.

We currently stage each "namespace" from SPHINX_TREES into a staging directory. We don't have a mechanism for combining files from multiple directories into the same destination. Should be possible with a small patch. Hardest part is looking for conflicts coming from multiple source directories. (We could probably use this feature for FHR as well.)

Comment 4

[Richard Newman [:rnewman]]

Step one: have *any* generated docs for Fennec. We can iterate later.

Comment 5

[Richard Newman [:rnewman]]

Attachment: Centralized documentation for UITelemetry. v1

No content yet other than links. Individual UITelemetry work can add here.

Comment 6

[Gregory Szorc [:gps]]

Comment on attachment 8395090 [details] [diff] [review]
Centralized documentation for UITelemetry. v1

Review of attachment 8395090 [details] [diff] [review]:
-----------------------------------------------------------------

This is all you need!

Comment 7

[Richard Newman [:rnewman]]

https://hg.mozilla.org/integration/fx-team/rev/e4b7ea863d20

Thanks for the quick turnaround, gps!

Comment 8

[Phil Ringnalda (:philor)]

https://hg.mozilla.org/mozilla-central/rev/e4b7ea863d20