Turn our GFX docs into Sphinx docs




3 years ago
a year ago


(Reporter: mstange, Unassigned)


(Depends on: 1 bug)


Firefox Tracking Flags

(firefox40 affected)


(Whiteboard: gfx-noted)



3 years ago
There is a "mach build-docs" command to build in-tree documentation.
These docs are automatically published at https://ci.mozilla.org/job/mozilla-central-docs/Tree_Documentation/index.html

There's probably no good reason to have the gfx docs in a separate place (one which is currently broken, at that (http://people.mozilla.org/~bgirard/doxygen/gfx/index.html is empty)), so let's convert our gfx docs to Sphinx docs. This will involve changing their format from Markdown to reStructured Text.
Sphinx also extracts documentation from source code using doxygen like tags?

Comment 2

3 years ago
Oh, no, I don't think so. I should have been more specific: I'm only referring to the text documents that we manually write and place in the gfx/doc/ folder. Automatic source code documentation will still need to be generated by doxygen.

But we should at least link to those generated docs from the Sphinx docs, once they're available again.
Currently doxygen auto-generated-from-source also picks up the stuff from gfx/doc folder.  When it works, it all shows up in one place - what does the workflow and the result look like with sphinx?
I believe that by itself, Sphinx just takes .rst files from specified locations and generates HTML from them.

However, it looks like it's possible to Sphinx to process Doxygen-generated XML and integrate it into its output, using Breathe [1].

[1] https://breathe.readthedocs.org/en/latest/

Comment 5

3 years ago
Currently gfx/doc stuff shows up in one place with the gfx source code documentation, but it's in a different place than the rest of the tree documentation.

I guess what I'm really saying is: I'd prefer the gfx/doc stuff to be in the same place as the other tree docs, even if that means separating it from the gfx doxyigen source code docs.

If you disagree, we could alternatively just create a gfx sphinx stub and make it link to the gfx doxygen docs.

Comment 6

3 years ago
(I wrote comment 5 before I had seen comment 4.)
Valid points.

gfx/doc documentation is meant to be extracted-from-code type documentation that doesn't really fit being in any particular file.  Really the only reason we created that directory.  It belongs with the rest of the source code documentation, doesn't really stand on its own, and the in-code extracted docs are poorer without the stuff from gfx/doc.
It'd be nice if it was all somehow available somewhere together, agreed.  But I really don't want to separate the extracted-from-source from gfx/doc, they're meant to be together.

Comment 8

3 years ago
All right, that totally makes sense.


3 years ago
Depends on: 1150232
Sounds like, if we're going to do this at all, we'll only want to do it after we have a way of getting Doxygen doc-comments into the Sphinx documentation as well. I filed bug 1150232 for that.
Whiteboard: gfx-noted
See Also: → bug 1313120
You need to log in before you can comment on or make changes to this bug.