Package: autodox
AutodoxTool for generating documentation automatically from code annotations, types,
and docstrings.StatusCodeDocsPackage publishedDenote async functions as suchUsageInstallationpipinstallautodoxNote that Protocols do not support__init__methods before Python 3.11. To use__init__method signatures for Protocols in Python 3.10, use thetyping.Protocolbackport from the 3rd-partytyping_extensionspackage.
Otherwise, the__init__method signature will be overridden with an empty one
named_no_init_or_replace_initand will be ignored by this tool.Document a module from CLIUse the following to document a module with default configuration:autodoxmodule_name[options]>target_file.mdThe output can be configured with the following options:-exclude_name=nameto exclude a specific part of the module by name-exclude_type=typeto exclude any module parts of the given type-package=module_nameto scope a relative import-header_level=numberto increase the hashtag count in headers bynumber-function_format=format- can be one of 'header', 'paragraph', or 'list'-method_format=format- can be one of 'header', 'paragraph', or 'list'-value_format=format- can be one of 'header', 'paragraph', or 'list'-line_length=number- number of chars per line in paragraphs-include_privateto include things prefaced with '_'-include_dunderto include things prefaced with '__'-include_submodulesto include submodules-document_submodulesto run the module documentation for submodules-debugto increase the level of debug statements printed (starts at 0)For experimentation and to learn how the options work, try running the following:autodoxautodox[options]Programmatic accessThe autodox package can also be used by importing and running the desired
documentation function(s). The following are included.dox_a_module(module: ModuleType, options: dict = None) -> strproduces docs for a moduledox_a_value(value: Any, options: dict = None) -> strproduces docs for a valuedox_a_function(function: Callable, options: dict = None) -> strproduces docs for a functiondox_a_class(cls: type, options: dict = None) -> strproduces docs for a classThe valid options for each will be described below. Additionally, there is a
system for setting up hooks that interact with the doc generation process to
change the inputs or outputs, and that will be described below the options for
the fourdox_a_{thing}functions.dox_a_module(module: ModuleType, options: dict = None) -> strProduces docs for a module. Valid options are the following:exclude_names: list[str]- names to exclude from docsexclude_types: list[str]- types to exclude from docsheader_level: int- number of additional hashtags to add to headersinclude_private: bool- if True, includes things with names prefaced by '_'include_dunder: bool- if True, includes things with names prefaced by '__'include_submodules: bool- if True, notes will be made about any additional
modules encountered when analyzing the specified moduledocument_submodules: bool- if True,dox_a_modulewill be called
recursively on any additional modules encountered when analyzing the specified
moduledox_a_value(value: Any, options: dict = None) -> strProduces docs for a value. Valid options are the following:header_level: int- number of additional hashtags to add to headersformat: str- format can be one of 'header', 'paragraph', or 'list'dox_a_function(function: Callable, options: dict = None) -> strProduces docs for a function. Valid options are the following:header_level: int- number of additional hashtags to add to headersdox_a_class(cls: type, options: dict = None) -> strProduces docs for a class. Valid options are the following:exclude_names: list[str]- names to exclude from docsheader_level: int- number of additional hashtags to add to headersinclude_private: bool- if True, includes things with names prefaced by '_'include_dunder: bool- if True, includes things with names prefaced by '__'method_format: str- can be one of 'header', 'paragraph', or 'list'HooksThere are eight events where custom functionality can be run, specified in theEventenum:AFTER_HEADERAFTER_PARAGRAPHAFTER_LISTBEFORE_VALUEAFTER_VALUEBEFORE_FUNCTIONAFTER_FUNCTIONBEFORE_CLASSAFTER_CLASSBEFORE_MODULEAFTER_MODULEHandlers for theBEFORE_events can be set using theset_before_handlerfunction. These handlers will receive the item to be documented and a dict
containing any options passed into thedox_a_{thing}function, and they should
return a tuple containing those two arguments after any modifications are made
to them. Example:fromautodoximportEvent,set_before_handlerfromtypingimportCallabledefhandle_before_function(function:Callable,options:dict):# set an optionoptions['header_level']=2return(function,options)set_before_handler(Event.BEFORE_FUNCTION,handle_before_function)Handlers for theAFTER_events can be set using theset_after_handlerfunction. These handlers will receive the str doc after thedox_a_{thing}function has completed executing, and they should return that document after any
modifications are made. Example:fromautodoximportEvent,set_after_handlerdefhandle_after_function(doc:str):# do some string manipulationreturndoc+'But really, why would you call this function anyway?\n\n'set_after_handler(Event.AFTER_FUNCTION,handle_after_function)Muliple handlers can be set for each event, and they will be executed in order,
passing the output from the first as input to the second, etc. Example:fromautodoximportEvent,set_after_handler# add 'hello world' to the end of each list item in two stepsdefhello(doc:str):returndoc+' hello'defworld(doc:str):returndoc+' world'set_after_handler(Event.AFTER_LIST,hello)set_after_handler(Event.AFTER_LIST,world)TestingThe test suite for this library is currently limited to hooks (14 tests) and a
few edge cases I encountered using the package (12 tests).To test, clone the repository and run the following:python test_hooks.py
python test_doxing.pyISC LicenseCopyleft (c) 2023 k98kurzPermission to use, copy, modify, and/or distribute this software
for any purpose with or without fee is hereby granted, provided
that the above copyleft notice and this permission notice appear in
all copies.THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR
CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.