From 7c0674641b28cd73fc0eea2ba91c1e03bf99e3fc Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Mon, 16 Dec 2013 10:11:00 -0800 Subject: Rework the index to give people a better lay of the land --- docs/index.rst | 35 +++++++++++++++++++++++++++++------ 1 file changed, 29 insertions(+), 6 deletions(-) (limited to 'docs/index.rst') diff --git a/docs/index.rst b/docs/index.rst index 776c9d37..dd20a4a4 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -32,9 +32,24 @@ existing libraries: * Poor introspectability, and thus poor testability. * Extremely error prone APIs, and bad defaults. +Layout +------ -Contents --------- +``cryptography`` is broadly divided into two levels. One with safe +cryptographic recipes, "cryptography for humans" if you will. These are safe +and easy to use and don't require developers to make many decisions. + +The other level is low-level cryptographic primitives. These are often +dangerous and can be used incorrectly. They require making decisions and having +an in-depth knowledge of the cryptographic concepts at work. Because of the +potential danger in working at this level, this is referred to as the "hazmat" +layer. + +We recommend using the recipes layer whenever possible, and falling back to the +hazmat layer only when necessary. + +The recipes layer +~~~~~~~~~~~~~~~~~ .. toctree:: :maxdepth: 2 @@ -42,15 +57,23 @@ Contents architecture exceptions glossary - contributing - security - community Hazardous Materials -------------------- +~~~~~~~~~~~~~~~~~~~ .. toctree:: :maxdepth: 2 hazmat/primitives/index hazmat/backends/index + + +The ``cryptography`` open source project +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. toctree:: + :maxdepth: 2 + + contributing + security + community -- cgit v1.2.3 From df8bfea7df603a41c6c83a77b7fb93531b408a48 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Mon, 16 Dec 2013 10:17:48 -0800 Subject: DOn't assume people know that contraction --- docs/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/index.rst') diff --git a/docs/index.rst b/docs/index.rst index dd20a4a4..8e879b05 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -42,8 +42,8 @@ and easy to use and don't require developers to make many decisions. The other level is low-level cryptographic primitives. These are often dangerous and can be used incorrectly. They require making decisions and having an in-depth knowledge of the cryptographic concepts at work. Because of the -potential danger in working at this level, this is referred to as the "hazmat" -layer. +potential danger in working at this level, this is referred to as the +"hazardous materials" or "hazmat" layer. We recommend using the recipes layer whenever possible, and falling back to the hazmat layer only when necessary. -- cgit v1.2.3 From 2cfbc12d9111c17d48882a3db24de77375fcc9b1 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Mon, 16 Dec 2013 10:19:00 -0800 Subject: Be consistent --- docs/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/index.rst') diff --git a/docs/index.rst b/docs/index.rst index 8e879b05..232ee63f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -58,8 +58,8 @@ The recipes layer exceptions glossary -Hazardous Materials -~~~~~~~~~~~~~~~~~~~ +The hazardous materials layer +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. toctree:: :maxdepth: 2 -- cgit v1.2.3 From be980532c4714e29d9afcec439eca8550343142c Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Mon, 16 Dec 2013 10:24:26 -0800 Subject: A foolish consistency is a really cool idea -- Samuel Clemens --- docs/index.rst | 1 - 1 file changed, 1 deletion(-) (limited to 'docs/index.rst') diff --git a/docs/index.rst b/docs/index.rst index 232ee63f..381063df 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -67,7 +67,6 @@ The hazardous materials layer hazmat/primitives/index hazmat/backends/index - The ``cryptography`` open source project ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- cgit v1.2.3 From 1a9bbf24301a9b0dc76ede1128d74ca629075888 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Tue, 24 Dec 2013 10:59:50 -0800 Subject: Document our API stability policy. Fixes #312 --- docs/index.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/index.rst') diff --git a/docs/index.rst b/docs/index.rst index 381063df..70558bda 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -75,4 +75,5 @@ The ``cryptography`` open source project contributing security + api-stability community -- cgit v1.2.3