From 18f3d64e4ca3b775e47083a3b7065f7308f8c877 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Antoine=20Beaupr=C3=A9?= Date: Thu, 3 Nov 2016 12:38:31 -0400 Subject: [PATCH 1/3] PDF docs: add logo and fix authors the PDF documentation looks much better with those --- docs/conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 26d405d11..8087b4300 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -199,12 +199,12 @@ htmlhelp_basename = 'borgdoc' # (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ ('index', 'Borg.tex', 'Borg Documentation', - 'see "AUTHORS" file', 'manual'), + '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. From 5def2350d06b1bdcb5d5ec5e3880bdbaa5bbbc78 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Antoine=20Beaupr=C3=A9?= Date: Thu, 3 Nov 2016 12:54:07 -0500 Subject: [PATCH 2/3] fix PDF rendering structure without those changes, all of the toctree document headings do not show up. they are considered to be "below" the last heading of the README file. we also remove the "Notes" section from the readme as there is only one note, regarding the fork. we introduce a stub "introduction" element in the toctree, otherwise it is impossible for the PDF rendered to render the README correctly. this is to workaround a bug in the PDF renderer. --- README.rst | 12 ++++++------ docs/book.rst | 22 ++++++++++++++++++++++ docs/conf.py | 2 +- docs/index.rst | 2 ++ docs/introduction.rst | 8 ++++++++ 5 files changed, 39 insertions(+), 7 deletions(-) create mode 100644 docs/book.rst create mode 100644 docs/introduction.rst diff --git a/README.rst b/README.rst index e9a59f4ee..5044bc4e6 100644 --- a/README.rst +++ b/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 `_. Checking Release Authenticity and Security Contact -================================================== +-------------------------------------------------- `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 `_ * `Releases `_, @@ -144,7 +144,7 @@ Links * `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). diff --git a/docs/book.rst b/docs/book.rst new file mode 100644 index 000000000..33e756839 --- /dev/null +++ b/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 diff --git a/docs/conf.py b/docs/conf.py index 8087b4300..cd27d3fda 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -198,7 +198,7 @@ htmlhelp_basename = 'borgdoc' # 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', + ('book', 'Borg.tex', 'Borg Documentation', 'The Borg Collective', 'manual'), ] diff --git a/docs/index.rst b/docs/index.rst index 89a907dee..67e7a7663 100644 --- a/docs/index.rst +++ b/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 diff --git a/docs/introduction.rst b/docs/introduction.rst new file mode 100644 index 000000000..ab8bd32c4 --- /dev/null +++ b/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 From aeb10d1a85649fcb099898ede07ffb2a63b2de39 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Antoine=20Beaupr=C3=A9?= Date: Thu, 3 Nov 2016 13:57:49 -0400 Subject: [PATCH 3/3] show URLs in PDF, better font --- docs/conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index cd27d3fda..8163bc7e1 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -193,7 +193,7 @@ htmlhelp_basename = 'borgdoc' #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]). @@ -214,7 +214,7 @@ latex_logo = '_static/logo.png' #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 = ''