Let's go with Sphinx! Following my investigation I agree with Bruce's recommendation that Sphinx is *more capable* and will make some tasks (like linking to code) a lot easier. I still don't like ReStructured Text but it isn't a compelling reason not to use the tool. I also don't think the (perceived) simplicity of Jekyll is enough of a benefit if it makes some tasks harder.
If there is a strong objection in the next couple of days we can reconsider, but otherwise I am assuming we will be moving forward with Sphinx. On Wednesday, 2 July 2014 03:48:22 UTC+10, Alon Zakai wrote: > > 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. > Doxygen supports JavaScript, but Breathe does not - so there is no easy way to import JavaScript automatically into Sphinx. However if we're going to have source-code documentation in the library in either case, Sphinx does this much better. Basically it has features to "understand" code (C++, JavaScript) so that these are indexed, and are easy to link to with a consistent syntax. Jekyll doesn't really understand anything other than page variables defined in the front-matter, so support for code indexing and linking would need to be added (or done manually :-) ) > 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] > <javascript:>> 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.
