Nicola, et alia.,
Firstly, I apologize that I haven't made a hang-out in ages -- for
reasons too long, boring and personal to get into -- but I'll stick my
head above the ramparts long enough to cause some trouble...
On 09/16/2015 08:50 PM, Nicola Nye wrote:
<snip>
Equally, there are some documentation issues that are affected by our
current straddling of two worlds. Read on for a discussion of the
issues and down to the options and recommendation.
I'd love to have your input (particularly Nic Bernstein on the docs
angle!) if you agree or disagree so we can make for a more unified
Cyrus presence.
*Issues*
1) Branding
<snip>
2) Docs logistics
The docs repo is separate to source which is causing friction keeping
man pages updated.
Yes! We need to get cyrus-docs into cyrus-imapd, and eliminate the
problems caused by the split repos. Bron and I discussed this some time
back, when I had tackled config2rst, and needed to find a target home
for the resultant doc/rst/imapd.conf.rst
We want man pages in two formats: *nix for actual man pages to ship
and install with cyrus, and html for web presentation.
Nice to have: ship a snapshot of all current docs (not just man pages)
along with source distribution.
3) Sphinx vs wiki
We have been working towards making the content on cyrus.foundation to
be the most up to date. This is using Sphinx, which allows us to
generate, from the same source, man pages as well as web pages. (And
even pdf or single page html). So we get nicer output format options.
Clearer history in the git log than you get from wiki.
Cyrusimap docs are held in mediawiki. Not so great for man pages. But
it's much easier for third party contributor to pitch in and help out:
they don't need to learn rst, they don't need a phabricator account,
they don't need to navigate git.
I like the git/sphinx combo for the audit trail it provides (blame) and
the easy ability to back out errant changes. I am not a MediaWiki
expert, barely a novice, so if it offers the same capabilities...
But perhaps more importantly, the existing docs on cyrus.foundation make
use of the nifty macros and such in Sphinx, in order that they can
include references to, or portions of, man pages. The aforementioned
config2rst, for example, was purposefully written such that it adds
useful delimiters into the resultant imapd.config.rst to facilitate
this, thus eliminating duplication of information.
For an example of this, check out the page on automatic creation of
mailboxes, which makes heavy use of this to present the actual
imapd.conf settings to the user, in context:
https://docs.cyrus.foundation/imap/features/automatic-creation-of-mailboxes.html
Which is produced by the simple code here:
https://docs.cyrus.foundation/_sources/imap/features/automatic-creation-of-mailboxes.txt
This ensures that the docs for the website (or package inclusion, why
not?) will always accurately reflect the actual settings in
lib/imapoptions, tracking changes as they're made.
Is there any parallel in MediaWiki?
For all of these reasons, I vote for solution 1, below.
Cheers,
-nic (ducking back below the wall...)
*Possible solutions*
<snip>
Option 1: Single domain, unify git repos, use sphinx everywhere
--------------------------------------------------------------------------------
Moving the git repo to cyrusimap (or anywhere) isn't hard. (a job for
Bron)
Get rid of separate cyrus-docs repo. Put cyrus-docs stuff back inside
cyrus-imapd/docs for easier man page generation and tagging of docs
versions with source, and shipping of current docs with source.
Put sphinx on cyrusimap to replace the wiki. This requires either:
1.
working out how to set up the existing generated docs for use with
sphinx,
2.
or make all the stuff in cyrus-imapd/doc into rst so it works with
sphinx. We can still ship the built html.
Option 2: Single domain, unify git repos, use wiki for docs
-----------------------------------------------------------------------------
Put sphinx on cyrusimap.org just for generating man page html. Leave
the existing wiki where it is for documentation. (Requires porting the
page updates I made from cyrus.foundation onto the wiki).
This means the only thing left in the cyrus-docs git repo would be the
man pages, at which point it makes more sense to put them back into
the cyrus-source repo.
We can still ship docs with the release if we tie in a wiki export
into the release-building process. (A job for Ellie and I)
Option 3: Single domain, separate git repos, use sphinx for docs
----------------------------------------------------------------------------------
Move all services to cyrusimap.org, but still leaves us with all the
docs logistics and sphinx and wiki chafe points. Not recommended.
*Recommendation*
I am leaning towards suggesting option 2. Anything that makes
documentation support easier is a good! But we'd still like to retain
the usefulness of sphinx for generating two output formats from single
source man pages.
*What Now?
*
Discuss! I imagine those folks who come to the Hangout in the next few
meetings will kick it around and we'll come to a decision next week.
Nicola
--
Nic Bernstein n...@onlight.com
Onlight Inc. www.onlight.com
6525 W Bluemound Rd., Ste 24 v. 414.272.4477
Milwaukee, Wisconsin 53213-4073 f. 414.290.0335
