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] 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 e9a59f4e..5044bc4e 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 00000000..33e75683 --- /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 8087b430..cd27d3fd 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 89a907de..67e7a766 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 00000000..ab8bd32c --- /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