Docs Revamp #64
Docs Revamp #64
Conversation
DirectXMan12
force-pushed
the
docs/revamp
branch
from
329c175
to
f3b8ef0
Compare
|
see a preview at https://fedorapeople.org/~sross/python-gssapi/docs-preview/ |
DirectXMan12
force-pushed
the
docs/revamp
branch
from
f3b8ef0
to
f070c64
Compare
|
In general, this seems good. I've got some comments inline though. Additionally, it's kind of annoying that we need to put the method declaration in the documentation right beneath the method declaration in the code. It feels rather redundant. |
This is because those are actually getting translated into C, and C methods don't have any signature information attached. Therefore, C methods often have a signature line as the first line of their docstring. |
DirectXMan12
force-pushed
the
docs/revamp
branch
from
f070c64
to
7318e29
Compare
|
WRT "IOV": I suspect it stands for IO Vector, but I couldn't actually find any documentation that spelled that out. WRT "OID": We could expand the acronym, but most of the other documentation I've seen just refers to them as OIDs, and doesn't expand the acronym. |
|
I see what you're saying. Looks good once Travis finishes. |
This commit revamps the general structure of the documentation, focusing on more human-readable sections with actual descriptions, and class grouping. It also switches to the ReadTheDocs theme.
Previously, `set_encoding` was only available from `gssapi._utils`. However, `gssapi._utils` was not intended for external use, while `set_encoding` is intended for external use. Now, `set_encoding` is available from the main `gssapi` module.
This commit updates the high-level documentation. Typos were corrected, improvements were made for readability, and more links were inserted. Additionally, two custom Sphinx extensions were added to help with the process: The first extension catches unknown class references and attempts to track them down. The class is searched for as if it were an `:any:` reference. The results from this searched are used, prefering results in the current API level (high-level vs low-level). The second extension adds a convinience role, `:requires-ext`, which inserts a link and some text indicating that a particular extension is required. If the extension is an RFC, a link to the RFC is generated, otherwise, a link to the low-level API module is generated. In the latter case, the text of the link is generated using the first line of the docstring of the low-level module, if it is present. Otherwise, the partial name of the module is used (the '%s' part of 'ext_%s') Finally, as per above, the docstrings of several extensions were updated.
This commit updates the low-level documentation, introducing method signatures as well as fixing typos.
This commit adds a docstring to `gssapi.raw` so that `help(gssapi.raw)` returns useful information.
DirectXMan12
force-pushed
the
docs/revamp
branch
from
7318e29
to
4052a46
Compare
This PR contains a large overhaul of the docs. The general structure of the docs were changed, as well as the style. Additionally, multiple corrections and improvements were made to the docs.
Closes #34