53 files changed, 78 insertions, 39 deletions
diff --git a/doc/manual/abi.rst b/doc/abi.rst
index faf7bcc44..faf7bcc44 100644
--- a/doc/manual/abi.rst
+++ b/doc/abi.rst
diff --git a/doc/manual/bigint.rst b/doc/api_ref/bigint.rst
index 364844fb5..364844fb5 100644
--- a/doc/manual/bigint.rst
+++ b/doc/api_ref/bigint.rst
diff --git a/doc/manual/block_cipher.rst b/doc/api_ref/block_cipher.rst
index 578235a2d..578235a2d 100644
--- a/doc/manual/block_cipher.rst
+++ b/doc/api_ref/block_cipher.rst
diff --git a/doc/manual/cipher_modes.rst b/doc/api_ref/cipher_modes.rst
index 6e78a2c1b..6e78a2c1b 100644
--- a/doc/manual/cipher_modes.rst
+++ b/doc/api_ref/cipher_modes.rst
diff --git a/doc/manual/compression.rst b/doc/api_ref/compression.rst
index 5637a5a68..5637a5a68 100644
--- a/doc/manual/compression.rst
+++ b/doc/api_ref/compression.rst
diff --git a/doc/manual/contents.rst b/doc/api_ref/contents.rst
index 12867c985..2cdfbc4d9 100644
--- a/doc/manual/contents.rst
+++ b/doc/api_ref/contents.rst
@@ -1,13 +1,10 @@
 
-Contents
-========================================
+API Reference
+===================
 
 .. toctree::
+   :maxdepth: 1
 
-   index
-   goals
-   support
-   building
    versions
    secmem
    rng
@@ -38,11 +35,3 @@ Contents
    otp
    ffi
    python
-   cli
-   side_channels
-   packaging
-   configure
-   fuzzing
-   deprecated
-   abi
-   roadmap
diff --git a/doc/manual/credentials_manager.rst b/doc/api_ref/credentials_manager.rst
index bc18c5d8e..bc18c5d8e 100644
--- a/doc/manual/credentials_manager.rst
+++ b/doc/api_ref/credentials_manager.rst
diff --git a/doc/manual/cryptobox.rst b/doc/api_ref/cryptobox.rst
index dbade88af..dbade88af 100644
--- a/doc/manual/cryptobox.rst
+++ b/doc/api_ref/cryptobox.rst
diff --git a/doc/manual/ecc.rst b/doc/api_ref/ecc.rst
index f522bbe3d..f522bbe3d 100644
--- a/doc/manual/ecc.rst
+++ b/doc/api_ref/ecc.rst
diff --git a/doc/manual/ffi.rst b/doc/api_ref/ffi.rst
index 84f729837..84f729837 100644
--- a/doc/manual/ffi.rst
+++ b/doc/api_ref/ffi.rst
diff --git a/doc/manual/filters.rst b/doc/api_ref/filters.rst
index 04baebf5d..04baebf5d 100644
--- a/doc/manual/filters.rst
+++ b/doc/api_ref/filters.rst
diff --git a/doc/manual/fpe.rst b/doc/api_ref/fpe.rst
index 9d77a4086..9d77a4086 100644
--- a/doc/manual/fpe.rst
+++ b/doc/api_ref/fpe.rst
diff --git a/doc/manual/hash.rst b/doc/api_ref/hash.rst
index ec83b7f16..ec83b7f16 100644
--- a/doc/manual/hash.rst
+++ b/doc/api_ref/hash.rst
diff --git a/doc/manual/kdf.rst b/doc/api_ref/kdf.rst
index bc126cbab..bc126cbab 100644
--- a/doc/manual/kdf.rst
+++ b/doc/api_ref/kdf.rst
diff --git a/doc/manual/keywrap.rst b/doc/api_ref/keywrap.rst
index 5c3aac0a3..5c3aac0a3 100644
--- a/doc/manual/keywrap.rst
+++ b/doc/api_ref/keywrap.rst
diff --git a/doc/manual/message_auth_codes.rst b/doc/api_ref/message_auth_codes.rst
index 70b6c9c3b..70b6c9c3b 100644
--- a/doc/manual/message_auth_codes.rst
+++ b/doc/api_ref/message_auth_codes.rst
diff --git a/doc/manual/otp.rst b/doc/api_ref/otp.rst
index bb8bf6fde..133201b4e 100644
--- a/doc/manual/otp.rst
+++ b/doc/api_ref/otp.rst
@@ -1,6 +1,8 @@
 One Time Passwords
 ========================
 
+.. versionadded:: 2.2.0
+
 One time password schemes are a user authentication method that relies on a
 fixed secret key which is used to derive a sequence of short passwords, each of
 which is accepted only once. Commonly this is used to implement two-factor
diff --git a/doc/manual/passhash.rst b/doc/api_ref/passhash.rst
index 4ef26f7be..4ef26f7be 100644
--- a/doc/manual/passhash.rst
+++ b/doc/api_ref/passhash.rst
diff --git a/doc/manual/pbkdf.rst b/doc/api_ref/pbkdf.rst
index 92f59f278..92f59f278 100644
--- a/doc/manual/pbkdf.rst
+++ b/doc/api_ref/pbkdf.rst
diff --git a/doc/manual/pkcs11.rst b/doc/api_ref/pkcs11.rst
index 781777264..781777264 100644
--- a/doc/manual/pkcs11.rst
+++ b/doc/api_ref/pkcs11.rst
diff --git a/doc/manual/psk_db.rst b/doc/api_ref/psk_db.rst
index 2668c6bad..2668c6bad 100644
--- a/doc/manual/psk_db.rst
+++ b/doc/api_ref/psk_db.rst
diff --git a/doc/manual/pubkey.rst b/doc/api_ref/pubkey.rst
index 6f867103f..6f867103f 100644
--- a/doc/manual/pubkey.rst
+++ b/doc/api_ref/pubkey.rst
diff --git a/doc/manual/python.rst b/doc/api_ref/python.rst
index 5022d9bf8..5022d9bf8 100644
--- a/doc/manual/python.rst
+++ b/doc/api_ref/python.rst
diff --git a/doc/manual/rng.rst b/doc/api_ref/rng.rst
index 0fc9da388..0fc9da388 100644
--- a/doc/manual/rng.rst
+++ b/doc/api_ref/rng.rst
diff --git a/doc/manual/secmem.rst b/doc/api_ref/secmem.rst
index 8dd479b7e..8dd479b7e 100644
--- a/doc/manual/secmem.rst
+++ b/doc/api_ref/secmem.rst
diff --git a/doc/manual/srp.rst b/doc/api_ref/srp.rst
index 9fcb1a196..9fcb1a196 100644
--- a/doc/manual/srp.rst
+++ b/doc/api_ref/srp.rst
diff --git a/doc/manual/stream_ciphers.rst b/doc/api_ref/stream_ciphers.rst
index dfee40970..dfee40970 100644
--- a/doc/manual/stream_ciphers.rst
+++ b/doc/api_ref/stream_ciphers.rst
diff --git a/doc/manual/tls.rst b/doc/api_ref/tls.rst
index 74f8bf79a..74f8bf79a 100644
--- a/doc/manual/tls.rst
+++ b/doc/api_ref/tls.rst
diff --git a/doc/manual/tpm.rst b/doc/api_ref/tpm.rst
index 7598c4bd8..7598c4bd8 100644
--- a/doc/manual/tpm.rst
+++ b/doc/api_ref/tpm.rst
diff --git a/doc/manual/tss.rst b/doc/api_ref/tss.rst
index 947b835d0..947b835d0 100644
--- a/doc/manual/tss.rst
+++ b/doc/api_ref/tss.rst
diff --git a/doc/manual/versions.rst b/doc/api_ref/versions.rst
index 511141b75..511141b75 100644
--- a/doc/manual/versions.rst
+++ b/doc/api_ref/versions.rst
diff --git a/doc/manual/x509.rst b/doc/api_ref/x509.rst
index fac9ae838..fac9ae838 100644
--- a/doc/manual/x509.rst
+++ b/doc/api_ref/x509.rst
diff --git a/doc/manual/building.rst b/doc/building.rst
index 9fa2aa6e1..9bc5c03ad 100644
--- a/doc/manual/building.rst
+++ b/doc/building.rst
@@ -87,7 +87,7 @@ For instance::
 will set up a build that only includes RSA, OAEP, PSS along with any
 required dependencies. Note that a minimized build does not by default
 include any random number generator, which is needed for example to
-generate keys, nonces and IVs. See :doc:`rng` on which random number
+generate keys, nonces and IVs. See :doc:`api_ref/rng` on which random number
 generators are available.
 
 Cross Compiling
@@ -477,8 +477,8 @@ Building the Python wrappers
 The Python wrappers for Botan use ctypes and the C89 API so no special
 build step is required, just import botan2.py
 
-See :doc:`Python Bindings <python>` for more information about the
-Python bindings.
+See :doc:`Python Bindings <api_ref/python>` for more information about
+the Python bindings.
 
 Configure Script Options
 ---------------------------
diff --git a/doc/manual/cli.rst b/doc/cli.rst
index eccc4499c..eccc4499c 100644
--- a/doc/manual/cli.rst
+++ b/doc/cli.rst
diff --git a/doc/contents.rst b/doc/contents.rst
new file mode 100644
index 000000000..6617e3d6b
--- /dev/null
+++ b/doc/contents.rst
@@ -0,0 +1,21 @@
+
+Contents
+========================================
+
+.. toctree::
+
+   index
+   goals
+   support
+   building
+   api_ref/contents
+   cli
+   deprecated
+   roadmap
+   credits
+   abi
+   packaging
+   security
+   side_channels
+   dev_ref/contents
+
diff --git a/doc/credits.rst b/doc/credits.rst
index fcad67d73..a2b48bf24 100644
--- a/doc/credits.rst
+++ b/doc/credits.rst
@@ -8,6 +8,8 @@ and beautification by scripts. The fields are name (N), email (E),
 web-address (W), PGP key ID and fingerprint (P), description (D),
 snail-mail address (S), and Bitcoin address (B).
 
+.. highlight:: none
+
 ::
 
   N: Alexander Bluhm
diff --git a/doc/manual/deprecated.rst b/doc/deprecated.rst
index 41f00d0d5..41f00d0d5 100644
--- a/doc/manual/deprecated.rst
+++ b/doc/deprecated.rst
diff --git a/doc/manual/configure.rst b/doc/dev_ref/configure.rst
index 1e0043be4..1e0043be4 100644
--- a/doc/manual/configure.rst
+++ b/doc/dev_ref/configure.rst
diff --git a/doc/dev_ref/contents.rst b/doc/dev_ref/contents.rst
new file mode 100644
index 000000000..05adaa331
--- /dev/null
+++ b/doc/dev_ref/contents.rst
@@ -0,0 +1,18 @@
+Developer Reference
+=====================
+
+This section contains information useful to people making
+contributions to the library
+
+.. toctree::
+   :maxdepth: 1
+
+   contributing
+   configure
+   fuzzing
+   release_process
+   todo
+   os
+   oids
+   reading_list
+   mistakes
diff --git a/doc/contributing.rst b/doc/dev_ref/contributing.rst
index 13c331ac4..738579bb2 100644
--- a/doc/contributing.rst
+++ b/doc/dev_ref/contributing.rst
@@ -1,6 +1,9 @@
 
+Notes for New Contributors
+===================================
+
 Source Code Layout
-=================================================
+-------------------------------------------------
 
 Under ``src`` there are directories
 
@@ -15,7 +18,7 @@ Under ``src`` there are directories
 * ``python/botan2.py`` is the Python ctypes wrapper
 
 Library Layout
-========================================
+----------------------------------------
 
 * ``base`` defines some high level types
 * ``utils`` contains various utility functions and types
@@ -47,7 +50,7 @@ Library Layout
   secret sharing, all or nothing transform, and others
 
 Sending patches
-========================================
+----------------------------------------
 
 All contributions should be submitted as pull requests via GitHub
 (https://github.com/randombit/botan). If you are planning a large
@@ -85,7 +88,7 @@ addition the new API functionality must be exposed to Python and a
 test written in Python.
 
 Git Usage
-========================================
+----------------------------------------
 
 Do *NOT* merge ``master`` into your topic branch, this creates
 needless commits and noise in history. Instead, as needed, rebase your
@@ -100,7 +103,7 @@ probably be a single commit. Only split commits as needed to help with
 review/understanding of the change.
 
 Python
-========================================
+----------------------------------------
 
 Scripts should be in Python whenever possible.
 
@@ -122,7 +125,7 @@ useful modules such as graphviz or matplotlib, regardless if it is available
 from a stock CPython install. Prefer Python3 for new scripts of this sort.
 
 Build Tools and Hints
-========================================
+----------------------------------------
 
 If you don't already use it for all your C/C++ development, install
 ``ccache`` now and configure a large cache on a fast disk. It allows for
@@ -140,7 +143,7 @@ of total coverage. This coverage build requires the development headers for
 zlib, bzip2, liblzma, OpenSSL, TrouSerS (libtspi), and Sqlite3.
 
 Copyright Notice
-========================================
+----------------------------------------
 
 At the top of any new file add a comment with a copyright and a reference to the
 license, for example::
@@ -154,7 +157,7 @@ If you are making a substantial or non-trivial change to an existing file, add
 or update your own copyright statement at the top of each file.
 
 Style Conventions
-========================================
+----------------------------------------
 
 When writing your code remember the need for it to be easily understood by
 reviewers and auditors, both at the time of the patch submission and in the
@@ -198,10 +201,10 @@ Use ``::`` to explicitly refer to the global namespace (eg, when calling an OS
 or external library function like ``::select`` or ``::sqlite3_open``).
 
 Use of External Dependencies
-========================================
+----------------------------------------
 
 Compiler Dependencies
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~
 
 The library should always be as functional as possible when compiled with just
 C++11. However, feel free to use the C++11 language. Little mercy is given to
@@ -220,7 +223,7 @@ into something with a conditional jump, but code intended to be const-time
 should in any case be annotated so it can be checked at runtime with tools.
 
 Operating System Dependencies
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If you're adding a small OS dependency in some larger piece of code, try to
 contain the actual non-portable operations to utils/os_utils.* and then call
@@ -235,7 +238,7 @@ or for Windows Vista/2008 Server (the oldest versions still supported by
 Microsoft).
 
 Library Dependencies
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Any external library dependency - even optional ones - is met with as one PR
 submitter put it "great skepticism".
diff --git a/doc/manual/fuzzing.rst b/doc/dev_ref/fuzzing.rst
index 519bae4e1..519bae4e1 100644
--- a/doc/manual/fuzzing.rst
+++ b/doc/dev_ref/fuzzing.rst
diff --git a/doc/mistakes.rst b/doc/dev_ref/mistakes.rst
index 75cdb4993..9f89e3059 100644
--- a/doc/mistakes.rst
+++ b/doc/dev_ref/mistakes.rst
@@ -1,4 +1,7 @@
 
+Mistakes
+===========
+
 These are mistakes made early on in the project's history which are difficult to
 fix now, but mentioned in the hope they may serve as an example for others.
 
diff --git a/doc/oids.txt b/doc/dev_ref/oids.rst
index 674d88d84..674d88d84 100644
--- a/doc/oids.txt
+++ b/doc/dev_ref/oids.rst
diff --git a/doc/os.rst b/doc/dev_ref/os.rst
index a06e787ff..c41e7d1fe 100644
--- a/doc/os.rst
+++ b/doc/dev_ref/os.rst
@@ -1,8 +1,5 @@
-Botan OS information
-========================================
-
 OS Features
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+========================================
 
 A summary of OS features as defined in ``src/build-data/os``.
 
@@ -60,4 +57,4 @@ A summary of OS features as defined in ``src/build-data/os``.
    "winsock2", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", "X", "X"
 
 .. note::
-   This file is auto generated by ``src/scripts/update_docs.py``. Dont modify it manually.
+   This file is auto generated by ``src/scripts/update_docs.py``. Don't modify it manually.
diff --git a/doc/reading_list.txt b/doc/dev_ref/reading_list.rst
index f35ae6ed7..b39046803 100644
--- a/doc/reading_list.txt
+++ b/doc/dev_ref/reading_list.rst
@@ -1,9 +1,11 @@
+Reading List
+================
 
 These are papers, articles and books that are interesting or useful from the
 perspective of crypto implementation.
 
 Papers
-==================
+--------
 
 Implementation Techniques
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -62,7 +64,7 @@ Public Key Side Channels
   https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Zertifizierung/Interpretationen/AIS_46_ECCGuide_e_pdf.pdf
 
 Books
-=======
+------
 
 * "Handbook of Elliptic and Hyperelliptic Curve Cryptography"
   Cohen and Frey https://www.hyperelliptic.org/HEHCC/
@@ -72,7 +74,7 @@ Books
   Covers code, lattice, and hash based cryptography
 
 Standards
-============
+-----------
 
 * IEEE 1363 http://grouper.ieee.org/groups/1363/
   Very influential early in the library lifetime, so a lot of terminology used
diff --git a/doc/release_process.rst b/doc/dev_ref/release_process.rst
index ea95aac8c..d1418777f 100644
--- a/doc/release_process.rst
+++ b/doc/dev_ref/release_process.rst
@@ -1,6 +1,8 @@
 Release Process and Checklist
 ========================================
 
+.. highlight:: shell
+
 .. note::
 
    This information is only useful if you are a developer of botan who
diff --git a/doc/todo.rst b/doc/dev_ref/todo.rst
index 5e784cead..a16f53103 100644
--- a/doc/todo.rst
+++ b/doc/dev_ref/todo.rst
@@ -1,4 +1,4 @@
-Projects
+Todo List
 ========================================
 
 Feel free to take one of these on if it interests you. Before starting
diff --git a/doc/manual/goals.rst b/doc/goals.rst
index 840e1bd81..840e1bd81 100644
--- a/doc/manual/goals.rst
+++ b/doc/goals.rst
diff --git a/doc/manual/index.rst b/doc/index.rst
index d61d508e4..50808c271 100644
--- a/doc/manual/index.rst
+++ b/doc/index.rst
@@ -12,7 +12,7 @@ source may not be required on your system.
 
 .. only:: html and website
 
-   You can also download this manual as a `PDF <https://botan.randombit.net/manual/botan.pdf>`_.
+   You can also download this manual as a `PDF <https://botan.randombit.net/handbook/botan.pdf>`_.
 
 Examples
 ----------
diff --git a/doc/manual/packaging.rst b/doc/packaging.rst
index f77000b89..f77000b89 100644
--- a/doc/manual/packaging.rst
+++ b/doc/packaging.rst
diff --git a/doc/manual/roadmap.rst b/doc/roadmap.rst
index c5a25c3df..c5a25c3df 100644
--- a/doc/manual/roadmap.rst
+++ b/doc/roadmap.rst
diff --git a/doc/manual/side_channels.rst b/doc/side_channels.rst
index f18625911..f18625911 100644
--- a/doc/manual/side_channels.rst
+++ b/doc/side_channels.rst
diff --git a/doc/manual/support.rst b/doc/support.rst
index 1d6ccc440..1d6ccc440 100644
--- a/doc/manual/support.rst
+++ b/doc/support.rst