On Mon, Jun 30, 2014 at 12:41 PM, Hamish Willee <[email protected]> wrote:
> 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 .... > I'm really happy to hear that you took the time to look at Sphinx. > 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. > Sphinx can handle the C++ API doc as well (probably better than Jeykll). One thing that I didn't mention before and that really sells Sphinx for me for doing book-sized works is the presence of strong support for indexes, not just tables of contents. > 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. > I agree with most of this. I didn't find Sphinx that difficult to deal with. > 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. > GitHub can preview ReStructured Text documents fine (depending on what extensions you use). GitHub's wiki can also support ReStructured Text pages, not just GitHub-flavored Markdown. > 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. > Templating is pretty easy. It is just Jinja2 templates which are pretty common in Python land. I've done some in the past, mainly by borrowing techniques from existing templates (it ships with a number of them). - 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.
