1150232 - Allow integrating Doxygen code comments into Sphinx documentation

Status: RESOLVED WONTFIX

(Firefox Build System :: General, defect)

Description

[Botond Ballo [:botond]]

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/

Comment 1

[Joshua Cranmer [:jcranmer]]

See bug 1115452, which includes a link to a blog post with more interesting comment discussion.

Comment 2

[Benoit Girard (:BenWa)]

Attachment: Part -1: Stop gap until we support .md files

I couldn't test it yet, waiting on bug 1175954.

Comment 3

[Gregory Szorc [:gps]]

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?

Comment 4

[Benoit Girard (:BenWa)]

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.

Comment 5

[Benoit Girard (:BenWa)]

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.

Comment 6

[Benoit Girard (:BenWa)]

Attachment: Part -1: Stop gap until we support .md files v2

I left the wording open ended since we still haven't fully converged to a solution yet. How about this Botond?

Comment 7

[Botond Ballo [:botond]]

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

Comment 8

[Pulsebot]

https://hg.mozilla.org/integration/mozilla-inbound/rev/a92d4fcd8afa

Comment 9

[Wes Kocher (:KWierso) (Not reading bugmail; email directly if needed)]

https://hg.mozilla.org/integration/mozilla-inbound/rev/a92d4fcd8afa

Comment 10

[Carsten Book [:Tomcat]]

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

Comment 11

[Benoit Girard (:BenWa)]

I just wanted to land the above patch.

Someone else should feel free to fix the patch above.

Comment 12

[Nick Alexander :nalexander [he/him]]

Closing in favour of Bug 1435424, which tracks removing Doxygen from the build system entirely.

Comment 13

[Firefox Bug Husbandry Bot]

Removing leave-open keyword from resolved bugs, per :sylvestre.