Skip to content

Comments

Generate python documentation with sphinx#5233

Open
arckoor wants to merge 1 commit intorandombit:masterfrom
arckoor:python-autodoc
Open

Generate python documentation with sphinx#5233
arckoor wants to merge 1 commit intorandombit:masterfrom
arckoor:python-autodoc

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

coveralls commented Jan 13, 2026

Coverage Status

coverage: 90.334% (+0.001%) from 90.333%
when pulling c590c3a on arckoor:python-autodoc
into 5166623 on randombit:master.

@arckoor arckoor force-pushed the python-autodoc branch 2 times, most recently from 29d403f to d6638e7 Compare February 5, 2026 18:10
@arckoor
Copy link
Contributor Author

arckoor commented Feb 19, 2026

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

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