Skip to content

Conversation

@arckoor
Copy link
Contributor

@arckoor arckoor commented Jan 13, 2026

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
Copy link
Contributor Author

arckoor commented Jan 13, 2026

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
Copy link

Coverage Status

coverage: 90.455% (+0.003%) from 90.452%
when pulling f0ffec2 on arckoor:python-autodoc
into 832565b on randombit:master.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants