Re: Proposal: move forward to Sphinx
Hideki Yamane <henrich@debian.or.jp> writes:
> I want to discuss with you about making policy doc much modern
> with Sphinx.
> Here's my opinion and PoC
> https://www.slideshare.net/henrich_d/challenge-convert-policy-doc-from-docbook-to-sphinx-77172587
>
> and sample output with Sphinx
> http://www.ma-aya.to/~henrich/debian/policy/
> Please tell me your impression/opinion/etc.
> (I'm not on list, so please cc: me)
I personally would be a huge fan of making this work, since I really
dislike editing XML and completely agree with the barrier to entry
argument. Sphinx is well-maintained and widely known and won't be going
anywhere, which is good. And the example output is encouraging. That
said, I think there are a few requirements we'd want in place before doing
this change:
1. We've always had reasonably good PDF output, and I want to maintain
that. I'm not sure how good Sphinx's pipeline is for that, and as
noted in the slides that would need to be tested. (ePub might be
better than PDF at this point, though.)
2. I don't think the Policy Editors probably have time to help a ton with
the conversion, so it would need to be driven by someone else with time
to rebase it repeatedly (probably by writing conversion scripts),
similar to what was done with the DocBook conversion. We'd also want
all documents in Policy to be moved to restructured text (except the
pure text ones) so that we are on a single format as a result of this
change.
3. Historically, text-like formats have struggled with multiply-nested
lists with multi-paragraph blocks and embedded literal blocks. The
output from Sphinx looks surprisingly good, so maybe its version of
reStructured Text does address all of this. But we'd want to verify
that we can get reasonable results from fairly complex structure.
(There seems to be something weird going on with fonts in definition
lists in your sample output, for instance.)
4. We'd like to be able to divide documents into multiple source files for
ease of editing (I kind of want to do that with Policy, and we're doing
that now for the debconf specification). I'm not sure if Sphinx
supports this?
5. I'd really like to move most of the comments into sidebars or some
other form of embedded set-off text that we can clearly mark as
non-normative, since reading footnotes is a kind of obnoxious
experience in all of our output formats. DocBook has native support
for this in multiple ways (<note>, <tip>, etc.), and I was looking
forward to having that available (although the default formatting is
perhaps a bit too aggressive and we'd need to find a more subtle way of
rendering it). Would we lose that in reStructured Text?
That said, the ease of editing improvement is *substantial*, and might be
worth some regressions on the other points.
Probably the biggest competitor would be to move to Publican, which also
has similar translation support (at least so I am told) and better
rendering, but continues to use DocBook as the underlying source format.
That said, Publican and the DocBook toolchain in general are fairly
complicated, so if Sphinx is easier to use, that would be another nice
advantage.
Definitely happy to hear more opinions on this.
--
Russ Allbery (rra@debian.org) <http://www.eyrie.org/~eagle/>
Reply to: