Hi Bruce In my last message I wrote: "I have not used Sphinx but I will review it and respond properly. My uninformed 10 second view is that Markdown/wiki text is easier to learn and use than ReStructured text. There is also a real "ease of use" benefit of markdown on Github because it can be previewed by the author (on the site) without them having to learn the Jekyll toolchain. The ability to publish to PDF or ePub is great - but is not IMO a key selection criteria."
A few hours later .... Yes, Sphinx would also be a capable tool for the job. It is a more mature product, with more output formats, inbuilt support for internationalisation, good source cross referencing, and some excellent extensions. It "understands" that you're trying to create a document hierarchy and automatically supports all the indexing and output HTML to support that. It has plenty of good documentation, an active community, and good support. It wasn't obvious to me exactly how the documentation of the C++ code would work, but clearly it would simplify things if we could use a single toolchain. Jekyll is a less "refined" product, but its documentation is just as good, and it has an active community and support network. Jekyll does not force any structure or look and feel out of the box, which means that starting from scratch would be much harder. However you don't have to start from scratch - there is an existing "good" project (e.g. jekyllrb.com sources) which answers the open questions. I think a Jekyll site will be easier for anyone to customise and understand than a Sphinx configuration. My feeling would be very different if the main requirement was to extract the comments from source code. A reason to choose Jekyll would be that it uses Markdown rather than ReStructured text. When hosting on Github this means authors can preview during development and get a pretty good idea of what it will look like without having to install the doc toolchain. They also have only one markup language to learn across wiki. This would be an advantage if most of you are only editing occasionally. My only concern with Sphinx is that I'm not sure how easy it will be to modify the themes as needed, while I've got enough experience with Jekyll to know I can get it to do what we need. If I hadn't any experience of either solution I would be leaning towards Sphinx. I'm more than happy to go with the "will of the community" as both solutions would be effective. Thoughts? Regards H On Thursday, 19 June 2014 15:09:35 UTC+10, Bruce Mitchener wrote: > > On Thu, Jun 19, 2014 at 1:16 AM, Alon Zakai <[email protected] > <javascript:>> wrote: > >> Hi everyone, >> >> We are planning to start an overhaul of the emscripten documentation >> soon, that is, of the contents of the wiki on github. One option might be >> to move to Jekyll, which is convenient as it has good github integration. >> >> If you have any thoughts on the current docs and how they can be >> improved, let's discuss here. >> > > I really like working with Sphinx and ReStructured Text: > http://sphinx-doc.org/ > > I've used it (successfully) to produce thousands of pages of technical > documentation, encompassing multiple books. We publish these materials in > HTML, PDF and ePub. We've written our own extensions as needed and it has > been pretty easy. > > I can't say enough positive things about it and only have a few relatively > minor complaints. > > - Bruce > > -- 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.
