From: Christian Herdtweck Date: Wed, 19 Aug 2015 12:39:11 +0000 (+0200) Subject: improved docu X-Git-Tag: v1.2~113 X-Git-Url: http://developer.intra2net.com/git/?a=commitdiff_plain;h=db622927ba935a8c9f626c1abd358ef1de622b79;p=pyi2ncommon improved docu --- diff --git a/.gitignore b/.gitignore index 1e0f80c..1530c44 100644 --- a/.gitignore +++ b/.gitignore @@ -5,3 +5,4 @@ __pycache__/ build/ dist/ MANIFEST +_build/ diff --git a/doc/README b/doc/README new file mode 100644 index 0000000..fac3e9b --- /dev/null +++ b/doc/README @@ -0,0 +1 @@ +see about_docu.rst diff --git a/doc/about_docu.rst b/doc/about_docu.rst index 4bca0b0..2c48517 100644 --- a/doc/about_docu.rst +++ b/doc/about_docu.rst @@ -8,24 +8,25 @@ How to generate this documentation * Install Sphinx * change dir into doc * run sphinx-apidoc -o ./ ../ - (this will create one .rst file for each python file in pyi2ncommon directory) -* list all .rst files in doc/index.rst * run make html + (this will create one .rst file for each python file in pyi2ncommon directory) + +Good to know +------------ -How this was created from scratch ---------------------------------- +* this Documentation was initialized using sphinx-quickstart +* doc/conf.py can be used to configure lots of the documentation +* the autodoc extension is responsible for creating .rst files from documentation in .py files +* you should not have to change the my_module_name.rst files or modules.rst since they are auto-created +* by including modules.rst in the toctree of index.rst, all modules' source doc is included in this help +* in conf.py, there is a setup() function in the end which can be used to influence the doc strings +* sometimes, adding . to the end of list items is required (not always as in this example) -* installed Sphinx -* ran sphinx-quickstart -* edited doc/index.rst TODO ---- -* add author name -* add copyright -* before committing run pylint and pep8 -* protect code by:: - -if __name__ == '__main__' +* before committing run pylint and pep8 (--> check.sh) +* automatically get classes and exceptions (and free functions?) into sidebar when opening module doc +* automatically set module name as title for module doc diff --git a/doc/conf.py b/doc/conf.py index b6f67f3..f06f6d2 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -116,7 +116,7 @@ todo_include_todos = True # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'alabaster' +html_theme = 'classic' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the @@ -128,10 +128,10 @@ html_theme = 'alabaster' # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". -#html_title = None +html_title = "libi2ncommon documentation" # A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None +html_short_title = "libi2ncommon docs" # The name of an image file (relative to this directory) to place at the top # of the sidebar. @@ -294,3 +294,10 @@ texinfo_documents = [ # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = {'https://docs.python.org/': None} + +# show doc of class AND of constructor +autoclass_content = 'class' # 'both' not needed if special-members is used +autodoc_default_flags = ['members', 'special-members', 'undoc-members', + 'show-inheritance'] + +autodoc_member_order = 'bysource' diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 0000000..b01883b --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,27 @@ +.. pyi2ncommon documentation master file, created by + sphinx-quickstart on Fri Jul 24 17:51:25 2015. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to pyi2ncommon's documentation! +======================================= + +This library is intended to hold python helper code used everywhere in Intra2Net code. It is starting small but will surely grow... + +Contents: + +.. toctree:: + :maxdepth: 1 + + license.rst + about_docu.rst + modules.rst + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/doc/license.rst b/doc/license.rst new file mode 100644 index 0000000..b17277a --- /dev/null +++ b/doc/license.rst @@ -0,0 +1,20 @@ +Code license +============ + +The software in this package is distributed under the GNU General +Public License version 2 (with a special exception described below). + +A copy of GNU General Public License (GPL) is included in this distribution, +in the file COPYING.GPL. + +As a special exception, if other files instantiate templates or use macros +or inline functions from this file, or you compile this file and link it +with other works to produce a work based on this file, this file +does not by itself cause the resulting work to be covered +by the GNU General Public License. + +However the source code for this file must still be made available +in accordance with section (3) of the GNU General Public License. + +This exception does not invalidate any other reasons why a work based +on this file might be covered by the GNU General Public License. diff --git a/follow.py b/follow.py index f14036b..f113f71 100644 --- a/follow.py +++ b/follow.py @@ -19,72 +19,77 @@ # on this file might be covered by the GNU General Public License. """ -follow.py: follow process output, log files and pipes using select and poll +follow process output, log files and pipes using select and poll Main class is Follower which does the polling and selecting, it is best used - in a with-statement as follows: +in a with-statement as follows:: -with follow('/var/log/messages') as flwr - for line in flwr: - do_something_with(line) + with follow('/var/log/messages') as flwr + for line in flwr: + do_something_with(line) This will read the given file and yield its contents line-by-line until the end of the file. It will then wait for new additions to the file and provide the new lines newly instantaneously Things to note: + * all data must be line-based! -* will only work on Linux (except for sockets maybe) -* create in py2 but try to stay py3-compatibel +* will only work on Linux (except for sockets maybe). +* create in py2 but try to stay py3-compatible. [START: not implemented yet] + If following a log file, a LogParser can be attached that auto-detects some of - the log's structure (like date and time fields, log levels and sources) from - its first few lines.. This can be used anlogously. Of course, you can also - specify the log's structure (to be implemented before the auto-detect...). +the log's structure (like date and time fields, log levels and sources) from +its first few lines.. This can be used anlogously. Of course, you can also +specify the log's structure (to be implemented before the auto-detect...):: + + with follow_log('/var/log/messages') as log_flwr: + for content in log_flwr: + do_something_with(content.datetime, content.log_level, content.text) -with follow_log('/var/log/messages') as log_flwr: - for content in log_flwr: - do_something_with(content.datetime, content.log_level, content.text) [END: not implemented yet] A Follower is an iterator, which means you can do lots of cool things with it, - including (see also itertools package, itertool recipies, "Functional - Programming Howto"): +including (see also itertools package, itertool recipies, "Functional +Programming Howto"):: + + # ignore source and description: + for _, _, text_line in my_follower: + do_something_with(line) -# ignore source and description: -for _, _, text_line in my_follower: - do_something_with(line) + # enumerate: + for line_number, line in enumerate(my_follower) + do_something_with(line, line_number) -# enumerate: -for line_number, line in enumerate(my_follower) - do_something_with(line, line_number) + # combine with other iterator: + for line, other_data in zip(my_follwer, other_iter) + do_something_with(line, other_data) -# combine with other iterator: -for line, other_data in zip(my_follwer, other_iter) - do_something_with(line, other_data) + # filter: + for line in my_follower if test(my_func): + do_something_with(line) -# filter: -for line in my_follower if test(my_func): - do_something_with(line) + # tee: + iter1, iter2 = itertools.tee(my_follower) + --> can read from both (but each line is given to only one of them) -# tee: -iter1, iter2 = itertools.tee(my_follower) ---> can read from both (but each line is given to only one of them) + # for each element, peek at the next one to help do the right thing + for line, next_line in pairwise(my_follower): + do_something_with(line, peek_next_line=next_line) -# for each element, peek at the next one to help do the right thing -for line, next_line in pairwise(my_follower): - do_something_with(line, peek_next_line=next_line) + # create new iterator or generator + for line in my_follwer: + some_result = do_something_with(line) + yield some_result -# create new iterator or generator -for line in my_follwer: - some_result = do_something_with(line) - yield some_result +NOT possible:: -NOT possible: len(my_follower), Follower(my_file, my_file) # (twice the same) + len(my_follower) + Follower(my_file, my_file) # (twice the same) -Christian Herdtweck, Intra2net, July 2015 -(c) Intra2net AG 2015 +.. codeauthor:: Christian Herdtweck, christian.herdtweck@intra2net.com """ from __future__ import print_function @@ -168,22 +173,26 @@ class Follower(object): Will guess if args are just sources or also descriptions of these. All of these are possible: - Follower(src) - Follower(src, desc) - Follower(src1, src2, src3) - Follower(src1, desc1, src2, desc2, src3, desc3) - Follower(src1, src2, desc2, src3) - Follower(src, desc_ignored, desc_used) # warn but accept - Follower(single_list_of_sources_and_descs) + + * Follower(src). + * Follower(src, desc). + * Follower(src1, src2, src3). + * Follower(src1, desc1, src2, desc2, src3, desc3). + * Follower(src1, src2, desc2, src3). + * Follower(src, desc_ignored, desc_used) # warn but accept. + * Follower(single_list_of_sources_and_descs). Not possible: - Follower() - Follower(desc, src) + + * Follower(). + * Follower(desc, src). Descriptions must be strings, they identify the sources in generated - output and are used in error messages + output and are used in error messages + Sources must be file handles, open pipes or open sockets (or anything - else that gives a reasonable fileno(), so help of the select module) + else that gives a reasonable fileno(), so help of the select module) + Sources are not closed! other_args can include flags and timeout diff --git a/template.py b/template.py index 63cdcb7..11e990f 100644 --- a/template.py +++ b/template.py @@ -22,6 +22,8 @@ Module name: Summary of this module Details on what happens here should be specified here but please keep it brief! + +.. codeauthor:: John Doe, john.doe@intra2net.com """ diff --git a/type_helpers.py b/type_helpers.py index 06a7475..a5780be 100644 --- a/type_helpers.py +++ b/type_helpers.py @@ -17,10 +17,9 @@ # on this file might be covered by the GNU General Public License. """ -Helpers for types, like isstr(x) +Helpers for type checking and conversion, like isstr(x) -Christian Herdtweck, Intra2net, August 2015 -(c) Intra2net AG 2015 +.. codeauthor:: Christian Herdtweck, christian.herdtweck@intra2net.com """ from __future__ import print_function