Vinay Sajip added the comment:
I'm not sure this issue tracker is the best place to have an extended
discussion about documentation - perhaps we should move this to a mailing list
such as python-list.
I'm not sure what you read first, but the logging documentation main page has a
box marked "Important" right at the top, which says: "This page contains the
API reference information. For tutorial information and discussion of more
advanced topics, see ..." and then links to the basic and advanced tutorials
and cookbook.
The basic tutorial starts with information on when to use logging (including
links to the convenient-for-beginners logging.XXX() functions), discusses the
different logging levels, and then gives a simple example:
import logging
logging.warning('Watch out!') # will print a message to the console
logging.info('I told you so') # will not print anything
So I don't see where your statement "No example of quick usage (the first one
is for `Logger.debug`, and that's not a generic one)" comes from, nor "The
top-level function are documented at the end of the document, albeit they are
the quickest way to use and understand `logging`". Although they are *listed*
low down, there are *links* to them very early in the basic tutorial - in the
very first paragraph of "When to use logging".
With reference to your rough proposed structure,
"Introduction to logging (with short example)" - the beginning of the basic
tutorial does this.
"Configuration (a separated chapter to describe file format, dict schema, and
stuff)" - outline is described in the advanced tutorial, details are found in
the specific page on the API reference for the logging.config module.
"Module references (logging, logging.config, logging.handler, etc.)" - this is
as it is now.
"Cookbook & Tutorials" - these are separated from the reference documentation
but otherwise seem to broadly follow what you're referring to here.
Bear in mind that opinions on (and reactions to) documentation are fairly
subjective. For example, you seem to find the Django documentation problematic,
but I don't, and it's widely regarded as one of the best documentation sets for
any Python project, and has contributed a lot to Django's success.
If you really want to take this on, I don't think a patch is the best way to
proceed, because there will be a *lot* of changes due to things moving around,
etc. and one would need to build the documentation from the changed sources to
get the full effect of the changes, unlike when reviewing source code. Instead,
you could create a project on ReadTheDocs which takes copies of the logging
documentation source pages and changes them to provide your alternative vision
of how the documentation should look. This will allow easier side-by-side
comparison for anyone who wants to review and compare the alternatives. If it's
generally felt (e.g. by people on python-dev) that the new version is better
than the current, then bringing the changes back shouldn't be too hard. What do
you think?
----------
_______________________________________
Python tracker <rep...@bugs.python.org>
<http://bugs.python.org/issue28499>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe:
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
