Move documentation to botan3.py

[arckoor]

~~Adds type hints to python.rst, and fixes some remaining errors in the type hinting. Also documents some things that weren't documented at all until now. I also reordered python.rst and botan3.py so that they are ordered the same way. (I pinky promise the first commit only did reordering and some formatting fixes in the rst)~~

~~To be completely honest, the more I work with python.rst, the less convinced I am. It's a pain to keep it consistent with the actual code (it's still out of date), and more significantly it can't be used to generate inline documentation for IDEs. What about just ditching the handwritten version, moving all the documentation inside botan3.py, and autogenerating the rst file?~~

Reorders botan3.py a bit and moves the documentation to it. Handbook is now autogenerated by sphinx.

[coveralls]

coverage: 91.958%. remained the same when pulling 3368ce31699c072ea6efb3b96b14fe5c86e2fb50 on arckoor:python-types-doc into 258d0fe77049cbeeaf10560aa3d7b40638ca5b25 on randombit:master.

[randombit]

What about just ditching the handwritten version, moving all the documentation inside botan3.py, and autogenerating the rst file?

That could probably work tbh especially because

• There is effectively zero "implementation" in the Python wrapper, it's all public interfaces outside of the ffi decls and code for finding the library to dlopen
• Documentation tool of choice is Sphinx which is anyway a native Python doc generator (aiui)

Only real downside is that the doc would no longer be visible/readable to someone just perusing a git checkout, or an installed version that was installed without Sphinx (in that case we just install the rst files since they are still pretty readable and better than no docs at all)

[arckoor]

Why would it not be visible to someone viewing a git checkout? Sure it would be interleaved with code, but I think in an IDE docstrings should be easily distinguishable from normal code due to coloring. But anyway, if you're on board with this I'll give it a look sometime, but I would go ahead with this PR in the meantime anyway

[randombit]

Why would it not be visible to someone viewing a git checkout? Sure it would be interleaved with code, but I think in an IDE docstrings should be easily distinguishable from normal code due to coloring.

Visible in the sense of someone looking at docs in a git checkout (or more likely, via Github file browser) to get a general sense of what was available would not see anything about the Python binding, they instead have to find src/python/botan3.py and read that. Which, balanced against the docs being out of date or incomplete or harder to use (eg with IDE integrations) is fine.

[arckoor]

@randombit I couldn't resist after all. ~~Note that with sphinx autogenerating it, it requires that it imports it, which in turn requires finding a libbotan-3. I never quite figured out what the recommended procedure is for this in development, so I've just been replacing the dll = CDLL(dll_name) line with dll = CDLL(f"./{dll_name}"), but I obviously can't push that. I suspect CI needs either installation for the docs job to work or some other hotfix I'm not aware of.~~

Turns out you can just overwrite ctypes.CDLL() with a dummy impl that does nothing, python just lets you do that :melting_face:

[arckoor]

@randombit Any chance of getting this and #5096 merged before the next release?