I am leaning to prefer Sphinx based on the discussion here too. Jukka, what are your current thoughts?
Regarding docs in the code, given that we have just 2 or 3 files with docs in them, and they span 2 languages, and would require 2 extra tools to support, I think it would be simpler for us to maintain the docs outside those files. I do agree with the point that docs outside the code can more easily get behind, but since it is literally so few files, I think we can (1) mark them clearly as being documented elsewhere, and (2) maintain vigilance on keeping them up to date. - Alon On Tue, Jul 1, 2014 at 7:02 PM, Hamish Willee <[email protected]> wrote: > > 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]> >> 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.
