Unifying the Cyrus World

[Nic Bernstein]

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                             nic at 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

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.andrew.cmu.edu/pipermail/cyrus-devel/attachments/20150917/3ee83ffc/attachment-0001.html