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 On Sun, Jun 29, 2014 at 10: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 .... > > 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]> 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. > -- 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.
