Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit b5b8f38

Browse files
Structural Revamp
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.
1 parent fd0690e commit b5b8f38

File tree

6 files changed

+154
-95
lines changed

6 files changed

+154
-95
lines changed

‎.travis.before-deploy.sh

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,3 +19,6 @@ PKG_NAME_VER="python-gssapi-${PYTHON_GSSAPI_VERSION}"
1919

2020
tar -czvf ./tag_build/${PKG_NAME_VER}.tar.gz --exclude='tag_build' --exclude='.git' --transform "s,^\.,${PKG_NAME_VER}," .
2121
sha512sum --binary ./tag_build/${PKG_NAME_VER}.tar.gz > ./tag_build/${PKG_NAME_VER}.sha512sum
22+
23+
# for the docs deploy
24+
pip install -r test-requirements.txt

‎docs-requirements.txt

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
Sphinx >= 1.3.1
2+
sphinx-rtd-theme >= 0.1.7
3+
sphinxcontrib-napoleon >= 0.2.8

‎docs/source/conf.py

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -50,9 +50,9 @@
5050
# built documents.
5151
#
5252
# The short X.Y version.
53-
version = '1.0.0'
53+
version = '1.1.0'
5454
# The full version, including alpha/beta/rc tags.
55-
release = '1.0.0'
55+
release = '1.1.0'
5656

5757
# The language for content autogenerated by Sphinx. Refer to documentation
5858
# for a list of supported languages.
@@ -77,6 +77,7 @@
7777
# If true, the current module name will be prepended to all description
7878
# unit titles (such as .. function::).
7979
#add_module_names = True
80+
add_module_names = False
8081

8182
# If true, sectionauthor and moduleauthor directives will be shown in the
8283
# output. They are ignored by default.
@@ -96,7 +97,7 @@
9697

9798
# The theme to use for HTML and HTML Help pages. See the documentation for
9899
# a list of builtin themes.
99-
html_theme = 'default'
100+
html_theme = 'sphinx_rtd_theme'
100101

101102
# Theme options are theme-specific and customize the look and feel of a theme
102103
# further. For a list of options available for each theme, see the

‎docs/source/gssapi.raw.rst

Lines changed: 68 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -1,138 +1,135 @@
1-
raw Package
2-
===========
1+
Low-Level API
2+
=============
33

4-
:mod:`raw` Package
5-
------------------
4+
The low-level API contains a variety of functions that map directly to the
5+
corresponding C functions. Additionally, it contains several basic wrapper
6+
classes that wrap underlying C structs and automatically deallocate them
7+
when the Python object itself is deallocated.
68

7-
.. automodule:: gssapi.raw
9+
Core RFC 2744
10+
-------------
11+
12+
Names
13+
~~~~~
14+
15+
.. automodule:: gssapi.raw.names
816
:members:
917
:undoc-members:
10-
:show-inheritance:
1118

12-
:mod:`creds` Module
13-
-------------------
19+
Credentials
20+
~~~~~~~~~~~
1421

1522
.. automodule:: gssapi.raw.creds
1623
:members:
1724
:undoc-members:
18-
:show-inheritance:
1925

20-
:mod:`cython_converters` Module
21-
-------------------------------
26+
Security Contexts
27+
~~~~~~~~~~~~~~~~~
2228

23-
.. automodule:: gssapi.raw.cython_converters
29+
.. automodule:: gssapi.raw.sec_contexts
2430
:members:
2531
:undoc-members:
26-
:show-inheritance:
27-
28-
:mod:`exceptions` Module
29-
------------------------
3032

31-
.. automodule:: gssapi.raw.exceptions
33+
.. automodule:: gssapi.raw.message
3234
:members:
3335
:undoc-members:
34-
:show-inheritance:
3536

36-
:mod:`ext_cred_store` Module
37-
----------------------------
37+
Misc
38+
~~~~
3839

39-
.. automodule:: gssapi.raw.ext_cred_store
40+
.. automodule:: gssapi.raw.oids
4041
:members:
4142
:undoc-members:
42-
:show-inheritance:
4343

44-
:mod:`ext_rfc5588` Module
45-
-------------------------
46-
47-
.. automodule:: gssapi.raw.ext_rfc5588
44+
.. automodule:: gssapi.raw.misc
4845
:members:
4946
:undoc-members:
50-
:show-inheritance:
5147

52-
:mod:`ext_s4u` Module
53-
---------------------
48+
.. automodule:: gssapi.raw.types
49+
:members:
50+
:undoc-members:
5451

55-
.. automodule:: gssapi.raw.ext_s4u
52+
.. automodule:: gssapi.raw.chan_bindings
5653
:members:
5754
:undoc-members:
58-
:show-inheritance:
5955

60-
:mod:`ext_password` Module
61-
---------------------
56+
Extensions
57+
----------
6258

63-
.. automodule:: gssapi.raw.ext_password
59+
The following is a list of GSSAPI extensions supported by the low-level API.
60+
Ones supported by the high-level API are marked as such. Note that while
61+
all of these extensions have bindings, they may not be supported by your
62+
particularly GSSAPI implementation, in which case they will simply not be
63+
compiled.
64+
65+
:rfc:`5588` (GSS-API Extension for Storing Delegated Credentials)
66+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
67+
68+
.. automodule:: gssapi.raw.ext_rfc5588
6469
:members:
6570
:undoc-members:
66-
:show-inheritance:
6771

68-
:mod:`ext_password_add` Module
69-
---------------------
72+
Credential Store Extensions
73+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
7074

71-
.. automodule:: gssapi.raw.ext_password_add
75+
.. automodule:: gssapi.raw.ext_cred_store
7276
:members:
7377
:undoc-members:
74-
:show-inheritance:
7578

76-
:mod:`mech_krb5` Module
77-
-----------------------
79+
:rfc:`6680` (GSS-API Naming Extensions)
80+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7881

79-
.. automodule:: gssapi.raw.mech_krb5
82+
.. automodule:: gssapi.raw.ext_rfc6680
8083
:members:
8184
:undoc-members:
82-
:show-inheritance:
83-
84-
:mod:`message` Module
85-
---------------------
8685

87-
.. automodule:: gssapi.raw.message
86+
.. automodule:: gssapi.raw.ext_rfc6680_comp_oid
8887
:members:
8988
:undoc-members:
90-
:show-inheritance:
9189

92-
:mod:`misc` Module
93-
------------------
90+
Credentials Import-Export Extensions
91+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
9492

95-
.. automodule:: gssapi.raw.misc
93+
.. automodule:: gssapi.raw.ext_cred_imp_exp
9694
:members:
9795
:undoc-members:
98-
:show-inheritance:
9996

100-
:mod:`names` Module
101-
-------------------
97+
DCE (IOV/AEAD) Extensions
98+
~~~~~~~~~~~~~~~~~~~~~~~~~
10299

103-
.. automodule:: gssapi.raw.names
100+
.. automodule:: gssapi.raw.ext_dce
104101
:members:
105102
:undoc-members:
106-
:show-inheritance:
107103

108-
:mod:`oids` Module
109-
------------------
104+
IOV MIC Extensions
105+
~~~~~~~~~~~~~~~~~~
110106

111-
.. automodule:: gssapi.raw.oids
107+
.. automodule:: gssapi.raw.ext_iov_mic
112108
:members:
113109
:undoc-members:
114-
:show-inheritance:
115110

116-
:mod:`sec_contexts` Module
117-
--------------------------
111+
Services4User Extensions
112+
~~~~~~~~~~~~~~~~~~~~~~~~
118113

119-
.. automodule:: gssapi.raw.sec_contexts
114+
.. automodule:: gssapi.raw.ext_s4u
120115
:members:
121116
:undoc-members:
122-
:show-inheritance:
123117

124-
:mod:`types` Module
125-
-------------------
118+
Acquiring Credentials With a Password Extensions
119+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
126120

127-
.. automodule:: gssapi.raw.types
121+
.. automodule:: gssapi.raw.ext_password
122+
:members:
123+
:undoc-members:
124+
125+
.. automodule:: gssapi.raw.ext_password_add
128126
:members:
129127
:undoc-members:
130-
:show-inheritance:
131128

132-
:mod:`named_tuples` Module
133-
--------------------------
129+
Exceptions
130+
----------
134131

135-
.. automodule:: gssapi.raw.named_tuples
132+
.. automodule:: gssapi.raw.exceptions
136133
:members:
137134
:undoc-members:
138135
:show-inheritance:

‎docs/source/gssapi.rst

Lines changed: 60 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,42 +1,84 @@
1-
gssapi Package
1+
High-Level API
22
==============
33

4-
:mod:`creds` Module
5-
--------------------
4+
The high-level API contains three main classes for interacting with GSSAPI,
5+
representing the primary abstractions that GSSAPI provides:
6+
:class:`~gssapi.names.Name`, :class:`~gssapi.creds.Credentials`, and
7+
:class:`~gssapi.sec_contexts.SecurityContext`. Note that classes in
8+
the high-level API inherit from the corresponding classes in the
9+
low-level API, and thus may be passed in to low-level API functions.
10+
11+
Main Classes
12+
------------
13+
14+
.. automodule:: gssapi.names
15+
:members:
16+
:undoc-members:
17+
:inherited-members:
618

719
.. automodule:: gssapi.creds
820
:members:
921
:undoc-members:
10-
:show-inheritance:
22+
:inherited-members:
23+
24+
.. automodule:: gssapi.sec_contexts
25+
:members:
26+
:undoc-members:
27+
:inherited-members:
1128

12-
:mod:`exceptions` Module
29+
Enums and Helper Classes
1330
------------------------
1431

15-
.. automodule:: gssapi.exceptions
32+
The following enumerations from the low-level API are also
33+
used with the high-level API. For convienience, the are
34+
imported in the high-level API :mod:`gssapi` module:
35+
36+
.. autoclass:: gssapi.raw.types.NameType
1637
:members:
1738
:undoc-members:
1839
:show-inheritance:
40+
:noindex:
1941

20-
:mod:`names` Module
21-
-------------------
22-
23-
.. automodule:: gssapi.names
42+
.. autoclass:: gssapi.raw.types.MechType
2443
:members:
2544
:undoc-members:
2645
:show-inheritance:
46+
:noindex:
2747

28-
:mod:`sec_contexts` Module
29-
--------------------------
48+
.. TODO(directxman12): Sphinx doesn't document enums properly yet,
49+
so we need to figure out how to document them.
3050
31-
.. automodule:: gssapi.sec_contexts
51+
.. autoclass:: gssapi.raw.types.RequirementFlag
52+
:show-inheritance:
53+
:noindex:
54+
55+
.. autoclass:: gssapi.raw.types.AddressType
56+
:show-inheritance:
57+
:noindex:
58+
59+
Similiarly, there are a couple classes from the low-level API
60+
that are imported into the high-level API module. These classes
61+
are less likely to be used directly by a user, but are returned
62+
by several methods:
63+
64+
.. autoclass:: gssapi.raw.oids.OID
65+
:members:
66+
:noindex:
67+
68+
.. autoclass:: gssapi.raw.types.IntEnumFlagSet
3269
:members:
3370
:undoc-members:
3471
:show-inheritance:
72+
:noindex:
3573

36-
Subpackages
37-
-----------
38-
39-
.. toctree::
74+
Exceptions
75+
----------
4076

41-
gssapi.raw
77+
The high-level API can raise all of the exceptions that the low-level API
78+
can raise in addition to several other high-level-specific exceptions:
4279

80+
.. automodule:: gssapi.exceptions
81+
:members:
82+
:undoc-members:
83+
:show-inheritance:
84+
:imported-members:

‎docs/source/index.rst

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,14 +3,27 @@
33
You can adapt this file completely to your liking, but it should at least
44
contain the root `toctree` directive.
55
6-
Welcome to Python-GSSAPI's documentation!
7-
====================================
6+
Python-GSSAPI: Python bindings for GSSAPI
7+
=========================================
8+
9+
Python-GSSAPI provides Python bindings for the GSSAPI C bindings as defined
10+
by :rfc:`2744`, as well as several extensions.
11+
12+
The package is organized into two parts: a high-level API and a low-level API.
13+
The high-level API resides in :mod:`gssapi`, and presents an object-oriented
14+
API around GSSAPI.
15+
16+
The other part of Python-GSSAPI is the low-level API, which resides in
17+
:mod:`gssapi.raw`. The low-level API provides thin wrappers around the
18+
corresponding C functions. The high-level API makes use of the low-level API
19+
to access underlying GSSAPI functionality. Additionally certain extensions
20+
are currently only available from the low-level API.
821

922
Contents:
1023

1124
.. toctree::
1225
:maxdepth: 2
13-
26+
1427
gssapi.rst
1528
gssapi.raw.rst
1629

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /