Open Bug 1150058 Opened 9 years ago Updated 2 years ago

Turn our GFX docs into Sphinx docs

Categories

(Core :: Graphics, defect)

Product:
Core
Component:
Graphics
Type:
defect

Tracking

()

Tracking Flags:
Tracking Status
firefox40 --- affected

People

(Reporter: mstange, Unassigned)

References

Details

(Whiteboard: gfx-noted) 

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?
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/
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.
(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.
All right, that totally makes sense.
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
Severity: normal → S3
You need to log in before you can comment on or make changes to this bug.