Generate python documentation with sphinx

[arckoor]

Changes the python documentation to be generated by sphinx.

I added mentions in the doc for things that were previously not there, e.g. TOTP, key wrapping, ...

I also moved a few doc comments from __init__ to the class itself, I had incorrectly assumed that sphinx would generate an extra constructor for those, it does not (so the doc would not be visible at all). At least my intellisense also doesn't pick up on any comments in the init, so I think this is better.

[arckoor]

My proposed reordering would be the following:

• Move the TPM section below RandomNumberGenerator
• Move BlockCipher below SymmetricCipher (and make a # Ciphers section)
• Move _load_buf_or_file to # Internal utilities

The resulting class / section order should be reflected in python.rst.

Reorder within the classes:

• function order: __init__ -> __del__ (and other __functions__) -> handle_ (if applicable) (handle could also be before the other __functions__)
• @classmethods afterwards
• then: algo_name, followed by "info-methods", e.g. key_length, estimated_strength, ...
• then: functions that operate on their class, clear, reset, set_key, ...

Here's a branch where I played that out once (for reference, not for merging). The first commit reorders the classes, the second the functions.

I don't think this is the way to reorder, just one way to do it. I think at least some ideas have merit, so feel free to choose whatever you feel is best and rely on intuition otherwise c:

[coveralls]

coverage: 89.446% (-0.004%) from 89.45% — arckoor:python-autodoc into randombit:master

[arckoor]

@randombit just fyi, without this the python XOF class will not be documented in the manual

[arckoor]

@randombit I've rebased against master to include the padded nist key wrap, could you take a look sometime?

[randombit]

@arckoor Sorry finally taking the time to really think about this and our doc situation in general. Yes change makes sense and mostly looks good. There does seem to be a problem building the docs if PYTHONPATH is not set to include src/python though - after a configure.py and make docs I get

WARNING: autodoc: failed to import 'version_major' from module 'botan3'; the following exception was raised:
Traceback (most recent call last):
  File "/usr/lib/python3.14/site-packages/sphinx/ext/autodoc/_dynamic/_importer.py", line 131, in _import_from_module_and_path
    module = _import_module(module_name, try_reload=True)
  File "/usr/lib/python3.14/site-packages/sphinx/ext/autodoc/_dynamic/_importer.py", line 218, in _import_module
    raise ModuleNotFoundError(msg, name=modname)  # NoQA: TRY301
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
ModuleNotFoundError: No module named 'botan3'
 [autodoc.import_object]
WARNING: autodoc: failed to import 'version_minor' from module 'botan3'; the following exception was raised:
Traceback (most recent call last):
  File "/usr/lib/python3.14/site-packages/sphinx/ext/autodoc/_dynamic/_importer.py", line 131, in _import_from_module_and_path
    module = _import_module(module_name, try_reload=True)
  File "/usr/lib/python3.14/site-packages/sphinx/ext/autodoc/_dynamic/_importer.py", line 218, in _import_module
    raise ModuleNotFoundError(msg, name=modname)  # NoQA: TRY301
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
ModuleNotFoundError: No module named 'botan3'
.......

I think in conf.py where you are doing the various patching for the mock DLL you also need to add a sys.path dir (relative to the conf.py) pointing into src/python.

[randombit]

[CI passes because CI runs everything with PYTHONPATH=src/python set]

[arckoor]

I was for some reason testing with ci_build.py instead of make docs when first opening this, sorry for not catching it earlier. Rebased to master, everything that was added should be documented in the rst file.

[Copilot]

Pull request overview

This PR transitions the Python API reference documentation to be generated via Sphinx autodoc, relying on inline docstrings in botan3.py and updating the RST to use autofunction/autoclass directives.

Changes:

• Move/expand several docstrings from __init__ methods into class docstrings to improve autodoc output.
• Enable Sphinx autodoc and add a ctypes-based mock to allow importing botan3.py during doc builds without a Botan shared library present.
• Rewrite doc/api_ref/python.rst to rely on autodoc directives (and add sections for newly documented features like TOTP and key wrapping).

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
src/python/botan3.py	Updates docstrings to improve Sphinx autodoc coverage and visibility.
src/configs/sphinx/conf.py	Enables autodoc and adds import/mocking logic so botan3 can be imported during documentation builds.
doc/api_ref/python.rst	Replaces hand-written API listings with autofunction/autoclass autodoc directives.

Comments suppressed due to low confidence (2)

src/python/botan3.py:1291

• Single-backtick markup is interpreted as a cross-reference in Sphinx/reST and may warn if the target can't be resolved. Use double backticks for the inline-literal parameter name.

    Set `encrypt` to False for decryption."""

src/python/botan3.py:2750

• For reST/Sphinx docstrings, use double backticks for inline literals. Single backticks are interpreted as a cross-reference and can generate warnings depending on default_role.

    The ``radix`` value should be set to 16 when initializing from a base 16 `str` value.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[arckoor]

The complaint about turning single backticks into double backticks was warranted, even if copilot did miss a lot of instances of it :p
At least on VS Code double backticks render exactly the same as single ones, so for IDEs it shouldn't break anything, and for sphinx it does result in nicer output