Allow integrating Doxygen code comments into Sphinx documentation

RESOLVED WONTFIX

Status

RESOLVED WONTFIX
4 years ago
10 months ago

People

(Reporter: botond, Unassigned)

Tracking

(Blocks: 1 bug)

Trunk

Firefox Tracking Flags

(firefox40 affected)

Details

Attachments

(1 attachment, 1 obsolete attachment)

(Reporter)

Description

4 years ago
We have a system for generating HTML documentation from in-tree .rst documentation files via Sphinx [1].

In some parts of the code, such as Graphics, we also have code comments in Doxygen format, from which we generate HTML documentation.

It would be nice to integrate these two, and have all the documentation in one place. One way to do this would be to integrate the Doxygen documentation into the Sphinx documentation via Breathe [2].

Thoughts? How involved would this be to support in the build system?

[1] https://ci.mozilla.org/job/mozilla-central-docs/Tree_Documentation/index.html
[2] https://breathe.readthedocs.org/en/latest/
See bug 1115452, which includes a link to a blog post with more interesting comment discussion.
(Reporter)

Updated

4 years ago
See Also: → bug 1115452
I couldn't test it yet, waiting on bug 1175954.
Assignee: nobody → bgirard
Attachment #8624293 - Flags: review?(mstange)
Attachment #8624293 - Flags: review?(mstange) → review+
Comment on attachment 8624293 [details] [diff] [review]
Part -1: Stop gap until we support .md files

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

Don't hold your breath on integrating Markdown into Sphinx.

::: gfx/moz.build
@@ +33,5 @@
>      DIRS += ['tests/gtest']
>  
>  TEST_DIRS += ['tests']
>  
> +#SPHINX_TREES['gfx'] = 'docs'

Why is this commented?
I told mstange in person that I would fix it. I was actually seeing if this was the cause of bug 1150058.

Once we resolve bug 1150058 I'll test this patch.
Sorry I meant bug 1175954 above.

(In reply to Gregory Szorc [:gps] from comment #3)
> Don't hold your breath on integrating Markdown into Sphinx.
> 

I'll change the comment in the documentation.

Botond points out that we're actually wanting to integrate Doxygen into Sphinx. BTW We're not even particularly set on Doxygen, at least I'm not, but it feels like javadocs style is the way forward for in-code documentation.

I think ultimately I just want to make the current graphics documentation discoverable until we can pick an official in code system for platform c++ code.
I left the wording open ended since we still haven't fully converged to a solution yet. How about this Botond?
Attachment #8624293 - Attachment is obsolete: true
Attachment #8624848 - Flags: feedback?(botond)
(Reporter)

Comment 7

4 years ago
Comment on attachment 8624848 [details] [diff] [review]
Part -1: Stop gap until we support .md files v2

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

LGTM
Attachment #8624848 - Flags: feedback?(botond) → feedback+
Keywords: checkin-needed, leave-open
I just wanted to land the above patch.

Someone else should feel free to fix the patch above.
Assignee: bgirard → nobody
Closing in favour of Bug 1435424, which tracks removing Doxygen from the build system entirely.
Status: NEW → RESOLVED
Last Resolved: a year ago
Resolution: --- → WONTFIX
Removing leave-open keyword from resolved bugs, per :sylvestre.
Keywords: leave-open

Updated

a year ago
Product: Core → Firefox Build System
You need to log in before you can comment on or make changes to this bug.