From 50b04933645e50fb6c4f83260c0fc3d5e32729db Mon Sep 17 00:00:00 2001 From: hakril Date: Fri, 14 Jun 2024 16:19:44 +0200 Subject: [PATCH] Upgrade sphinx conf + update some doc --- docs/source/_static/css/mbasic.css | 2 ++ docs/source/com.rst | 2 +- docs/source/conf.py | 23 +++++++++++++---------- docs/source/crypto.rst | 7 ------- docs/source/evtlog.rst | 4 ---- docs/source/index.rst | 20 ++++++++++++-------- docs/source/object_manager.rst | 4 ---- docs/source/task_scheduler.rst | 4 ---- docs/source/windows.rst | 6 ++++-- windows/winobject/event_log.py | 5 ++++- windows/winobject/object_manager.py | 5 ----- windows/winobject/system.py | 2 +- 12 files changed, 37 insertions(+), 47 deletions(-) diff --git a/docs/source/_static/css/mbasic.css b/docs/source/_static/css/mbasic.css index 940b19b..3ad15bf 100644 --- a/docs/source/_static/css/mbasic.css +++ b/docs/source/_static/css/mbasic.css @@ -18,6 +18,8 @@ div.body { div.bodywrapper { margin-right: 20px; } +.sphinxsidebarwrapper { overflow-y: scroll; } + div.admonition-todo { border-top: 2px solid red; border-bottom: 2px solid red; diff --git a/docs/source/com.rst b/docs/source/com.rst index d650ab7..394d4d0 100644 --- a/docs/source/com.rst +++ b/docs/source/com.rst @@ -18,7 +18,7 @@ It's possible to directly call `COM` interface from python. All you need is the There are three ways to get the definition of the code interface: * By using it from :mod:`windows.generated_def.interfaces` - * By writing it yourself : `_ + * By writing it yourself : ``_ * By generating it. To generate a `COM` interface you need its definition from the ".c" file. diff --git a/docs/source/conf.py b/docs/source/conf.py index 8c26300..ce90c25 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -46,9 +46,16 @@ extensions = [ 'sphinx.ext.todo', ] -autodoc_default_flags = ['inherited-members'] +autodoc_default_options = { + "members": True, + "inherited-members": True + +} + +# autodoc_default_flags = ['members', 'inherited-members'] # autodoc_member_order = "groupwise" todo_include_todos = True +toc_object_entries_show_parents = "hide" # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -71,16 +78,16 @@ copyright = u'2015-2020, Clement Rouault' # built documents. # # The short X.Y version. -version = '0.6' +version = '1.0' # The full version, including alpha/beta/rc tags. -release = '0.6' +release = '1.0.0' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. # # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. -language = None +language = "en" # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: @@ -368,10 +375,6 @@ epub_exclude_files = ['search.html'] #epub_use_index = True -# Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'https://docs.python.org/2.7': None} - - def get_rst(app, what, name, obj, options, lines): pass @@ -403,5 +406,5 @@ def miss_ref(app, env, node, contnode): return res def setup(app): - app.add_stylesheet('css/mbasic.css') # may also be an URL - # app.connect('missing-reference', miss_ref) + app.add_css_file ('css/mbasic.css') # may also be an URL + app.connect('missing-reference', miss_ref) diff --git a/docs/source/crypto.rst b/docs/source/crypto.rst index ad60aa5..444141f 100644 --- a/docs/source/crypto.rst +++ b/docs/source/crypto.rst @@ -34,13 +34,6 @@ import_pfx Certificate """"""""""" -.. warning:: - - The classes described here are still under test and possible rewrite/refactor. - - The classes, methods and properties described here will problably change as I haven't yet had the time - to try it out in real cases and figure out the final look of the API I want to do. - .. note:: See sample :ref:`sample_crypto_certificate` diff --git a/docs/source/evtlog.rst b/docs/source/evtlog.rst index caaf31d..26fa10e 100644 --- a/docs/source/evtlog.rst +++ b/docs/source/evtlog.rst @@ -19,10 +19,6 @@ For now, the best thing to do is look at the sample: See sample :ref:`sample_event_log` -.. warning:: - - This API have not been tested on real case yet and may be subject to changes. - EvtlogManager """"""""""""" diff --git a/docs/source/index.rst b/docs/source/index.rst index 051312d..a13211a 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -14,9 +14,7 @@ Its goal is to offer abstractions around some of the OS features in a (I hope) p It also tries to make the barrier between python and native execution thinner in both ways. There is no external dependencies but it relies heavily on the ``ctypes`` module. - -Some of this code is clean (IMHO) and some parts are just a wreck that works for now. -Let's say that the codebase evolves with my needs and my curiosity. +Let's say that the codebase evolves with my needs, my researches and my curiosity. If you have any issue, question, suggestion do not hesitate to contact me. I am always glad to have feedbacks from people using this project. @@ -44,13 +42,19 @@ You can also install PythonForWindows by cloning it and using the ``setup.py`` a python setup.py install -Python3 +Encoding & unicode +^^^^^^^^^^^^^^^^^^ + +PythonForWindows support `python2.7` & `python3` and is currently tested for `Python2.7`, `3.6` & `3.11` via `Github Workflow `_ + +Since 1.0.0, the code uses "wide APIs" whenever possible and accept/returns python3 `str` (py2.7 `unicode` type) almost everywhere. Any functions/APIs not accepting unicode string can be considered a bug if its not stated explicitly in the documentation. + + +Python2 ^^^^^^^ -python3 support is still in beta. -All the tests pass on master, but I did not test it heavily on real case. -Do not hesitate report bugs and issues. - +PythonForWindows continues to support python2.7 as its the only way to have it running on `Windows XP` & `Windows Server 2003` which are sadly still seen in production. +Encoding errors at print time might be awkward for unicode string on python2, see the `PythonForWindows encoding guide `_ in the documentation. Documentation """"""""""""" diff --git a/docs/source/object_manager.rst b/docs/source/object_manager.rst index 105b324..7f4fe21 100644 --- a/docs/source/object_manager.rst +++ b/docs/source/object_manager.rst @@ -12,10 +12,6 @@ The :class:`ObjectManager` instance is accessible via :py:attr:`windows.system.o See sample at :ref:`sample_object_manager` -.. warning:: - - This API have not been tested on real cases yet and may be subject to changes. - ObjectManager """"""""""""" diff --git a/docs/source/task_scheduler.rst b/docs/source/task_scheduler.rst index ae091a1..4777b4d 100644 --- a/docs/source/task_scheduler.rst +++ b/docs/source/task_scheduler.rst @@ -10,10 +10,6 @@ The :class:`TaskService` is accessible via :py:attr:`windows.system.task_schedul See sample :ref:`sample_scheduled_task` -.. warning:: - - This API have not been tested on real cases yet and may be subject to changes. - TaskService """"""""""" diff --git a/docs/source/windows.rst b/docs/source/windows.rst index 65d249c..ad1b1fa 100644 --- a/docs/source/windows.rst +++ b/docs/source/windows.rst @@ -34,8 +34,10 @@ The ``system`` object See sample :ref:`sample_system` -.. currentmodule:: windows.winobject +.. module:: windows.winobject.system .. autoclass:: windows.winobject.system.System - :no-show-inheritance: + :members: + :show-inheritance: + :inherited-members: diff --git a/windows/winobject/event_log.py b/windows/winobject/event_log.py index 8a85d2e..6596b5c 100644 --- a/windows/winobject/event_log.py +++ b/windows/winobject/event_log.py @@ -548,7 +548,10 @@ class ChannelConfig(EvtHandle): return EvtPublisher(chaninfo(self, gdef.EvtChannelConfigOwningPublisher).value) def publishers(self): - "TEST" + """ The list of Publisher publishing on the channel. seems pertinent for Legacy channel like "System" + + :type: [:class:`EvtPublisher`] - A list of :class:`EvtPublisher` + """ return [EvtPublisher(pub) for pub in chaninfo(self, gdef.EvtChannelPublisherList).value] @property diff --git a/windows/winobject/object_manager.py b/windows/winobject/object_manager.py index e1ac456..f0de7f3 100644 --- a/windows/winobject/object_manager.py +++ b/windows/winobject/object_manager.py @@ -200,11 +200,6 @@ class KernelObject(object): class ObjectManager(object): """Represent the object manager. - - .. note:: - - For now, it only offers the ``root`` :class:`KernelObject`. But I want a ``manager`` object accessible - from ``windows.system`` just like other API and not directly the ``root`` directory. """ @property diff --git a/windows/winobject/system.py b/windows/winobject/system.py index 339700a..f492ba3 100644 --- a/windows/winobject/system.py +++ b/windows/winobject/system.py @@ -134,7 +134,7 @@ class System(object): Same as os.environ on py3 Custom dict built on GetEnvironmentStringsW() on py2 - :type: :class:`dict` -- {unicode: unicode} + :type: :class:`dict` -- {:class:`unicode`: :class:`unicode`} """ if windows.pycompat.is_py3: return os.environ # Py3 environ is already unicode