Merge pull request #1805 from anarcat/pdf-docs

improvements to the PDF version of the documentation

README.rst

@@ -3,7 +3,7 @@
 .. highlight:: bash
 
 What is BorgBackup?
-===================
+-------------------
 
 BorgBackup (short: Borg) is a deduplicating backup program.
 Optionally, it supports compression and authenticated encryption.
@@ -20,7 +20,7 @@ downloaded Borg, ``docs/installation.rst`` to get started with Borg.
 .. _installation manual: https://borgbackup.readthedocs.org/en/stable/installation.html
 
 Main features
--------------
+~~~~~~~~~~~~~
 
 **Space efficient storage**
   Deduplication based on content-defined chunking is used to reduce the number
@@ -82,7 +82,7 @@ Main features
     complete license
 
 Easy to use
------------
+~~~~~~~~~~~
 
 Initialize a new backup repository and create a backup archive::
 
@@ -114,7 +114,7 @@ Now doing another backup, just to show off the great deduplication:
 For a graphical frontend refer to our complementary project `BorgWeb <https://borgweb.readthedocs.io/>`_.
 
 Checking Release Authenticity and Security Contact
-==================================================
+--------------------------------------------------
 
 `Releases <https://github.com/borgbackup/borg/releases>`_ are signed with this GPG key,
 please use GPG to verify their authenticity.
@@ -130,7 +130,7 @@ The public key can be fetched from any GPG keyserver, but be careful: you must
 use the **full fingerprint** to check that you got the correct key.
 
 Links
-=====
+-----
 
 * `Main Web Site <https://borgbackup.readthedocs.org/>`_
 * `Releases <https://github.com/borgbackup/borg/releases>`_,
@@ -144,7 +144,7 @@ Links
 * `License <https://borgbackup.readthedocs.org/en/stable/authors.html#license>`_
 
 Compatibility notes
-===================
+-------------------
 
 EXPECT THAT WE WILL BREAK COMPATIBILITY REPEATEDLY WHEN MAJOR RELEASE NUMBER
 CHANGES (like when going from 0.x.y to 1.0.0 or from 1.x.y to 2.0.0).

docs/book.rst

@@ -0,0 +1,22 @@
+.. include:: global.rst.inc
+
+Borg documentation
+==================
+
+.. when you add an element here, do not forget to add it to index.rst
+
+.. toctree::
+    :maxdepth: 3
+
+    introduction
+    installation
+    quickstart
+    usage
+    deployment
+    faq
+    support
+    resources
+    changes
+    internals
+    development
+    authors

docs/conf.py

@@ -193,18 +193,18 @@
 #latex_paper_size = 'letter'
 
 # The font size ('10pt', '11pt' or '12pt').
-#latex_font_size = '10pt'
+latex_font_size = '12pt'
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-  ('index', 'Borg.tex', 'Borg Documentation',
-   'see "AUTHORS" file', 'manual'),
+  ('book', 'Borg.tex', 'Borg Documentation',
+   'The Borg Collective', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
 # the title page.
-#latex_logo = None
+latex_logo = '_static/logo.png'
 
 # For "manual" documents, if this is true, then toplevel headings are parts,
 # not chapters.
@@ -214,7 +214,7 @@
 #latex_show_pagerefs = False
 
 # If true, show URL addresses after external links.
-#latex_show_urls = False
+latex_show_urls = 'footnote'
 
 # Additional stuff for the LaTeX preamble.
 #latex_preamble = ''

docs/index.rst

@@ -6,6 +6,8 @@ Borg Documentation
 
 .. include:: ../README.rst
 
+.. when you add an element here, do not forget to add it to book.rst
+
 .. toctree::
    :maxdepth: 2
 

docs/introduction.rst

@@ -0,0 +1,8 @@
+Introduction
+============
+
+.. this shim is here to fix the structure in the PDF
+   rendering. without this stub, the elements in the toctree of
+   index.rst show up a level below the README file included
+
+.. include:: ../README.rst