Update some doc/samples for new module/features

Author: hakril

docs/source/conf.py

@@ -14,6 +14,8 @@
 
 import sys
 import os
+import sphinx
+import docutils
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -45,6 +47,7 @@
 ]
 
 autodoc_default_flags = ['inherited-members']
+# autodoc_member_order = "groupwise"
 todo_include_todos = True
 
 # Add any paths that contain templates here, relative to this directory.
@@ -375,5 +378,30 @@ def get_rst(app, what, name, obj, options, lines):
 def get_rst2(app, what, name, obj, options, signature, return_annotation):
     pass
 
+
+# Test code to handle :class:`gdef.STRUCTURE_NAME`
+# demo of custom xref for not-found structures
+# Test was for ref to 'SECURITY_DESCRIPTOR_CONTROL' in SecurityDescriptor.control
+def miss_ref(app, env, node, contnode):
+    # import pdb;pdb.set_trace()
+    if not node["reftype"] == "class":
+        return
+    print(node, node["reftype"], node["reftarget"], contnode)
+    # import pdb;pdb.set_trace()
+
+    if "SECURITY_DESCRIPTOR_CONTROL" not in node["reftarget"]:
+        return
+
+    res = docutils.nodes.reference("", "")
+    py_domain = env.domains["py"]
+    full_name = "windows.generated_def.winstructs.{0}".format(node["reftarget"].rsplit(".", 1)[-1])
+    t = [x for x in py_domain.get_objects() if full_name == x[0]][0]
+    res["refdocname"] = node["refdoc"]
+    res.append(contnode)
+    uri = app.builder.get_relative_uri(node["refdoc"], t[3])
+    res['refuri'] = "{0}#{1}".format(uri, t[0])
+    return res
+
 def setup(app):
     app.add_stylesheet('css/mbasic.css')  # may also be an URL
+    # app.connect('missing-reference', miss_ref)

docs/source/index.rst

@@ -35,7 +35,7 @@ You can install PythonForWindows using the ``setup.py`` at the root of the proje
     python setup.py install
 
 In its current state the project only support Python2 and
-``setup.py`` will raise an :class:`NotImplementedError` is launched from python3.
+``setup.py`` will raise an :class:`NotImplementedError` if launched from python3.
 
 
 .. warning::
@@ -54,6 +54,7 @@ Documentation
    winobject.rst
    native_exec.rst
    winproxy.rst
+   security.rst
    pipe.rst
    utils.rst
    wintrust.rst

docs/source/process.rst

@@ -50,12 +50,6 @@ WinThread
    :show-inheritance:
    :inherited-members:
 
-Token
-'''''
-
-.. autoclass:: Token
-   :members:
-   :inherited-members:
 
 
 PEB Exploration

docs/source/sample.rst

@@ -67,6 +67,18 @@ Output
 .. literalinclude:: samples_output\process_iat_hook.txt
 
 
+.. _token_sample:
+
+Token
+"""""
+
+.. literalinclude:: ..\..\samples\token\token_demo.py
+
+Output
+
+.. literalinclude:: samples_output\token_token_demo.txt
+
+
 .. _sample_system:
 
 
@@ -226,6 +238,17 @@ Output
 
 .. literalinclude:: samples_output\debug_debugger_print_LdrLoaddll.txt
 
+.. _sample_debugger_on_setup:
+
+on_setup
+~~~~~~~~
+
+.. literalinclude:: ..\..\samples\debug\debugger_on_setup.py
+
+
+Output
+
+.. literalinclude:: samples_output\debug_debugger_on_setup.txt
 
 
 Single stepping
@@ -523,3 +546,28 @@ Output
 
 .. literalinclude:: samples_output\pipe_child_send_object.txt
 
+
+.. _sample_security:
+
+:mod:`windows.security`
+"""""""""""""""""""""""
+
+Security Descriptor
+'''''''''''''''''''
+
+.. literalinclude:: ..\..\samples\security\security_descriptor.py
+
+Output
+
+.. literalinclude:: samples_output\security_security_descriptor.txt
+
+.. _sample_security_sacl:
+
+Query SACL
+''''''''''
+
+.. literalinclude:: ..\..\samples\security\query_sacl.py
+
+Output
+
+.. literalinclude:: samples_output\security_query_sacl.txt

docs/source/security.rst

@@ -12,6 +12,12 @@
 
 .. module:: windows.security
 
+This module give access to :class:`SecurityDescriptor` and related structures (``Acl`` & ``Ace``).
+
+.. note::
+
+    See sample :ref:`sample_security`
+
 
 SecurityDescriptor
 """"""""""""""""""
@@ -218,36 +224,36 @@ SystemProcessTrustLabelACE
 
 
 Ace common base
-"""""""""""""""
+'''''''''''''''
 
 These classes are internals and here for completness sake.
 You should not need to instanciate/use them directly.
 
 AceHeader
-'''''''''
+~~~~~~~~~
 
 .. autoclass:: AceHeader
 
 AceBase
-'''''''
+~~~~~~~
 
 .. autoclass:: AceBase
 
 
 MaskAndSidACE
-'''''''''''''
+~~~~~~~~~~~~~
 
 .. autoclass:: MaskAndSidACE
 
 
 CallbackACE
-'''''''''''
+~~~~~~~~~~~
 
 .. autoclass:: CallbackACE
 
 
 ObjectRelatedACE
-''''''''''''''''
+~~~~~~~~~~~~~~~~
 
 .. autoclass:: ObjectRelatedACE
 

docs/source/windows.rst

@@ -16,6 +16,7 @@ The submodules that you might use by themself are:
     * :mod:`windows.native_exec`
     * :mod:`windows.winproxy`
     * :mod:`windows.wintrust`
+    * :mod:`windows.security`
     * :mod:`windows.crypto`
     * :mod:`windows.utils`
     * :mod:`windows.debug`

docs/source/winobject.rst

@@ -10,6 +10,7 @@ This sections describes them by group of relation.
     :maxdepth: 3
 
     process.rst
+    token.rst
     exception.rst
     registry.rst
     network.rst

windows/security.py

@@ -597,7 +597,7 @@ class SecurityDescriptor(gdef.PSECURITY_DESCRIPTOR):
 
         To query the SACL enable the ``SeSecurityPrivilege`` and use the parameter ``query_sacl=True`` on the functions expecting a ``flags``
 
-        see SACL sample
+        see :ref:`Query SACL sample <sample_security_sacl>`
     """
 
     _close_function = winproxy.LocalFree