Improving Documentation at Pycryptodome.org

[AndrewScottWCU]

Could you make improving the documentation at Pycryptodome.org a priority. As present a lot of your API cannot be fathomed out without visiting the likes of StackOverflow to see how things really are expected to work or be used. For example, the documentation of the Crypto.Cipher packages does not enumerate each and every python module in that package, and thus to find out how the they should be used, what modules and functions are available requires finding the source code (which appears to have well written but otherwise inaccessible documentation strings). For example, I had a simple question "Where does the function _create_cipher which is used by AES.py come from. and what type of object does it return?." This will help me discover what methods I can call on it. I've yet to discover the answer.

As another example, AES the documentation does not give a plain example of encrypting with AES. Your examples use encrypt_and_digest, This is not strait encryption and thus causes confusion for people wanting to learn and take advantage of strait AES encryption with, for example, the CBC mode of operation.

Some of the information is buried within subsections such as Symmetric ciphers > modes of operation, but you really have to sleuth it out. You cannot get to the section, Classic Modes of Operation without clicking on Crypto.cipher package and then scrolling to thirds down and clicking the link "Modern Modes of Operation" on the page to reveal probably the most useful subsection in the Crypto.cipher package documentation Classic Modes of Operation on the left side navigation tree (which is otherwise undescoverable).

Please make updating and organizing what is at Pycryptodome.org a priority, because security depends not only on good tools, but the extent to which those tools are used as intended. I know its a hard job, but I think it will have a significant impact in improving the overall developer experience and safe usage of Pycryptodome.