Re: Sphinx integration
Dave Abrahams <[email protected]>
| Newsgroups | gmane.comp.lib.boost.documentation |
|---|---|
| Message-ID | <[email protected]> |
on Tue Sep 27 2011, Mateusz Loskot <mateusz-AT-loskot.net> wrote: > On 27/09/11 01:09, Dean Michael Berris wrote: >> On Tue, Sep 27, 2011 at 9:46 AM, Mateusz Loskot <[email protected]> > >> wrote: >>> >>> Has anyone considered it? >> >> I/we use it in cpp-netlib for both docs and the website. > > So, you write it in reStructuredText, right? > >>> Would it be valid to discuss Sphinx for Boost? >> >> I for one would welcome discussion about it. > > The major problem I have with the current Boost documentation framework > is too big diversity of documenting tools and workflows, lack of content > writing uniformity, none or not ideal source-to-doc > translation (e.g. Doxygen issues). Exactly. And now you're proposing to increase the diversity... unless you mean to rewrite all the existing docs. > Remembering long way of documenting Boost.Geometry, I'm not 100% happy > with the results. Perhaps it's only my opinion. I'm not going to > ignite any fermentation. I'm just curious, if boostdoc/quickbook is > really superior to, say, reStructuredText + Sphinx tandem. The differences run deep. If it was a totally clear cut win for ReST, I'd have pushed for its exclusive adoption years ago. - quickbook is an extensible programming language; ReST is explicitly trying *not* to be programmable - quickbook generates boostbook, which can represent rich semantic information. ReST can't very cleanly express arbitrary semantic or visual markup (bold-italic anyone?) - quickbook is maintained by Boosters when they have the time, docbook is maintained externally - quickbook takes a long time to compile, docbook is Python - quickbook is not really used outside of Boost; docbook is used by manymanymany - there's no usable Emacs editing mode for quickbook; there is for ReST. ... Any ideas about how to address these issues? -- Dave Abrahams BoostPro Computing http://www.boostpro.com