Another thing that occurred to me is that we have inline docs in JavaScript as well, not just C++ (e.g., ccall in src/preamble.js). I suppose these tools might work on that as well? Could make things a little more complex though. Overall it might just be simpler to move the docs out of source files and into dedicated docs files.
I don't feel strongly either way between Sphinx and Jekyll, I guess. Overall I slightly prefer the simpler option (Jekyll) as the benefits of the more complex one are not huge. But if you and others here prefer Sphinx that would be fine too. - Alon On Mon, Jun 30, 2014 at 10:49 PM, Hamish Willee <[email protected]> wrote: > Hi Alon, Bruce, et al. > > Sphinx does not provide support "out of the box" for extracting C++ > comments, but it does allow you to create a "domain > <http://sphinx-doc.org/domains.html#id2>" for C++ that allows you to > declare C++ entities and link to them (as shown on my test project here > <https://dl.dropboxusercontent.com/u/3067678/test/build/html/docs/test4.html> > ). > > However it is possible to use the tool Breathe ( > http://breathe.readthedocs.org/en/latest/index.html) to convert Doxygen > generated XML into the format used by Sphinx and import these. I tested > this HERE > <https://dl.dropboxusercontent.com/u/3067678/test/build/html/docs/test6.html#the-imported-code> > on > emscriptem.h. I had to make a number of very minor changes to the header to > get this to generate (mostly just addition of an extra asterisk on the > comment blocks). Unfortunately I can't yet get the linking to work, so I am > following up with the author of Breathe. > > I'm still not loving restructured text, but I am leaning further into the > Sphinx camp because while the toolchain is becoming more complicated, it is > all "standard stuff" > > Regards > H > > On Tuesday, 1 July 2014 05:40:48 UTC+10, Alon Zakai wrote: >> >> I am also pretty open to either Sphinx or Jekyll. It seems both have easy >> markup syntaxes, can export static sites, are popular, and basically >> support what we want. >> >> I couldn't find mention of the ability to extract docs from C++ header >> files among the Sphinx feature list, or docs. Maybe I didn't look in the >> right place? That does sound like a useful feature, I'd be curious to hear >> more about how it works. If it works well that might be a good reason to >> prefer Sphinx. >> >> - Alon >> >> >> -- > You received this message because you are subscribed to the Google Groups > "emscripten-discuss" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to [email protected]. > For more options, visit https://groups.google.com/d/optout. > -- You received this message because you are subscribed to the Google Groups "emscripten-discuss" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. For more options, visit https://groups.google.com/d/optout.
