Offer the documentation as PDF and EPUB

[dilyanpalauzov]

SaltStack offers at https://docs.saltstack.com/en/latest/contents.html (top right corner) pretty useful feature to download the whole documentation as PDF or EPUB, so that users can print it, or copy it to some reader.

Use the corresponding Sphinx builders and offer PDF and EPUB also for Cyrus IMAP, as SaltStack does.

[nicolan]

I spent some time today attempting to coerce Sphinx to produce a pdf. Getting pdf2latex functioning on Windows is not as trivial as you might hope for!

End result: use https://miktex.org/download, some futzing of package manager required to install required packages.

Finally managed to produce Cyrus.pdf. I had to change references to your name, Dilyan, as we had originally presented them in a unicode font which pdf2latex was dying on. There was a weird quote issue in one file that required tweaking.

I'm not happy with the output for pdf or epub as it stands: a lot of our monospace code blocks are too wide for the output format and are just truncated. ePub - zipped

See https://github.com/nicolan/cyrus-imapd/tree/docs-pdf-epub for progress so far.

[nicolan]

Tried updating from Sphinx 1.3.6 to Sphinx 1.6.2 and the final output was a lot healthier. Though it killed pdflatex twice and I ended up having to manually trigger the final pdf build by hand, so even if we were to upgrade, it might need more attention before we're up for publishing it in production.

Cyrus.pdf on sphinx 1.6.2

[dilyanpalauzov]

Please publish the pdf and epub results, as they are generated (e.g. by Sphinx 1.7.1), these can be improved over time. This approach is better than not publishing them.

[elliefm]

For clarity, would you want these inside the release tarballs, or on the website, or both?

[dilyanpalauzov]

I mean only the website.

Apart from this make doc-html puts the documentation in doc/html/ but make -C docsrc html puts the same result in docsrc/build. If there is a justification for docsrc/Makefile and there is no reason to have two standard locations for the html output, then both commands should store their output on the same place.

Building the epub format creates a file toc.ncx with the "Table of Content". It contains some items twice and they appear twice in the Table of Content in the epub reader, which is not very nice:

      <navPoint id="navPoint4" playOrder="3">
        <navLabel>
          <text>Get Cyrus</text>
        </navLabel>
        <content src="imap/download/getcyrus.xhtml" />
        <navPoint id="navPoint5" playOrder="3">
          <navLabel>
            <text>Get Cyrus</text>
          </navLabel>
          <content src="imap/download/getcyrus.xhtml" />
        </navPoint>
...
     <navPoint id="navPoint16" playOrder="13">
        <navLabel>
          <text>Notes for Packagers</text>
        </navLabel>
        <content src="imap/download/packagers.xhtml" />
        <navPoint id="navPoint17" playOrder="13">
          <navLabel>
            <text>Notes for Packagers</text>
          </navLabel>
          <content src="imap/download/packagers.xhtml" />
        </navPoint>

This is caused explicitly by the sphinx-doc epub3 builder and can be switched off with epub_tocdup=False.

Adding :numbered: to .. toctree: in docsrc/index.rst reveals that some files are included several times in the Table of Content, in particular:

diff --git a/docsrc/imap/developer.rst b/docsrc/imap/developer.rst
--- a/docsrc/imap/developer.rst
+++ b/docsrc/imap/developer.rst
@@ -6,14 +6,15 @@ IMAP Developer Guide

 Getting Started
 ================
+
+See :ref:`setup` for compilation and installation.
+
 .. toctree::
     :maxdepth: 1

     developer/process
     developer/overview
     developer/github-guide
-    developer/compiling
-    installing
     developer/developer-testing
     developer/jmap

diff --git a/docsrc/imap/download/release-notes/index.rst b/docsrc/imap/download/release-notes/index.rst
--- a/docsrc/imap/download/release-notes/index.rst
+++ b/docsrc/imap/download/release-notes/index.rst
@@ -93,12 +93,3 @@ Series 2: 2.0 - 2.3
     2.1/2.1.x
     2.2/2.2.x
     2.3/index
-
-
-.. toctree::
-    :hidden:
-
-    2.4/index
-    2.4-dav/index
-    2.5/index
-    3.0/index

I think here :glob: is not necessary:

diff --git a/docsrc/developers.rst b/docsrc/developers.rst
--- a/docsrc/developers.rst
+++ b/docsrc/developers.rst
@@ -5,7 +5,6 @@ Developers

 .. toctree::
     :maxdepth: 2
-    :glob:

     contribute
     Contribute docs <imap/developer/documentation>
diff --git a/docsrc/imap/concepts/features/access-control.rst b/docsrc/imap/concepts/features/access-control.rst
--- a/docsrc/imap/concepts/features/access-control.rst
+++ b/docsrc/imap/concepts/features/access-control.rst
@@ -17,8 +17,4 @@ to information contained within the Cyrus IMAP mailspool.
     *   :ref:`imap-admin-access-control-defaults`
     *   :ref:`imap-admin-access-control-identifiers`

-.. toctree::
-    :hidden:
-    :glob:
-
 Back to :ref:`imap-features`
diff --git a/docsrc/imap/download/installation/manage-dav.rst b/docsrc/imap/download/installation/manage-dav.rst
--- a/docsrc/imap/download/installation/manage-dav.rst
+++ b/docsrc/imap/download/installation/manage-dav.rst
@@ -96,7 +96,6 @@ Module-specific information
 ===========================

 .. toctree::
-    :glob:
     :maxdepth: 2

     http/caldav
diff --git a/docsrc/imap/download/release-notes/index.rst b/docsrc/imap/download/release-notes/index.rst
--- a/docsrc/imap/download/release-notes/index.rst
+++ b/docsrc/imap/download/release-notes/index.rst
@@ -44,7 +44,6 @@ Documentation at :cyrus-3.0:`/`.

 .. toctree::
     :maxdepth: 1
-    :glob:

     3.0/index

@@ -55,7 +54,6 @@ Documentation at :cyrus-2.5:`/`.

 .. toctree::
     :maxdepth: 1
-    :glob:

     2.5/index

@@ -64,7 +62,6 @@ Series 2.4

 .. toctree::
     :maxdepth: 1
-    :glob:

     2.4/index
     2.4-dav/index
@@ -78,7 +75,6 @@ Series 1

 .. toctree::
     :maxdepth: 1
-    :glob:

     1/1.x.x

@@ -87,7 +83,6 @@ Series 2: 2.0 - 2.3

 .. toctree::
     :maxdepth: 1
-    :glob:

     2.0/2.0.x
     2.1/2.1.x
diff --git a/docsrc/overview.rst b/docsrc/overview.rst
--- a/docsrc/overview.rst
+++ b/docsrc/overview.rst
@@ -5,7 +5,6 @@ Overview

 .. toctree::
     :maxdepth: 2
-    :glob:

     imap/concepts/features
     imap/concepts/overview_and_concepts

To make imapd.conf bold at https://www.cyrusimap.org/imap/reference/manpages/commands.html#configuration-files, as are cyrus.conf and krb.equiv among others, apply:

diff --git a/tools/config2rst b/tools/config2rst
--- a/tools/config2rst
+++ b/tools/config2rst
@@ -189,10 +189,10 @@ sub print_man2rst {
     # Title
     if (/^\.TH\s+(\S+).*$/) {
         $file = lc $1;
-        my $headlen = length $file;
+        my $headlen = 4 + length $file;
         my $header = "\n\n.. cyrusman:: $file(5)\n\n";
         $header .= ".. _imap-reference-manpages-configs-$file:\n\n";
-        $header .= '=' x $headlen . "\n$file\n" . '=' x $headlen . "\n";
+        $header .= '=' x $headlen . "\n**$file**\n" . '=' x $headlen . "\n";
         $_ = $header;
     }
     # Section Header, zero all of our special indenters

As the .. toctree:: includes :hidden: entries, the sphinx epub3 output needs to be tweaked manually.

The singlehtml, dirhtml and other targets in docsrc/Makefile are missing dependency on the init target.