gh-98731: Improvements to the logging documentation #101618

quicknir · 2023-02-06T20:59:39Z

This PR is probably just a starting point, but hopefully we can begin with this and iterate.

Issue: logging documentation is tough for beginners #98731

ghost · 2023-02-06T21:00:04Z

All commit authors signed the Contributor License Agreement.

vsajip · 2023-05-06T06:14:56Z

Doc/howto/logging.rst

@@ -26,9 +26,11 @@ When to use logging
 ^^^^^^^^^^^^^^^^^^^

 Logging provides a set of convenience functions for simple logging usage. These


Since your change refers to using logger methods rather than the convenience functions, I'd remove this sentence and go with something like "You can access logging functionality by creating a logger via ..."

vsajip · 2023-05-06T06:15:50Z

Doc/howto/logging.rst

-:func:`critical`. To determine when to use logging, see the table below, which
-states, for each of a set of common tasks, the best tool to use for it.
+can be accessed by creating a logger via ``logger = getLogger(__name__)``, and
+then calling :func:`logger.debug`, :func:`logger.info`, :func:`logger.warning`,


Use : meth: here rather than :func: maybe? This applies to similar usages below.

vsajip · 2023-05-06T06:17:44Z

Doc/howto/logging.rst

+then calling :func:`logger.debug`, :func:`logger.info`, :func:`logger.warning`,
+:func:`logger.error` and :func:`logger.critical`. To determine when to use
+logging, see the table below, which states, for each of a set of common tasks,
+the best tool to use for it.

 +-------------------------------------+--------------------------------------+


Did you actually build this documentation locally? If you did, not sure how it got past these errors.

I did not. I will try to build them locally and message if I have issues.

vsajip · 2023-05-06T06:23:22Z

Doc/howto/logging.rst

+module, like ``logging.debug``, rather than creating a logger and calling
+functions on it. These functions operation on the root logger, but can be useful
+as they will call ``basicConfig`` for you if it has not been called yet, like in
+this example.  In larger programs you'll usually want to control this call


Suggested change

this example. In larger programs you'll usually want to control this call

this example. In larger programs you'll usually want to control the logging configuration

vsajip · 2023-05-06T06:23:52Z

Doc/howto/logging.rst

 | server process)                     | appropriate for the specific error   |
 |                                     | and application domain               |
 +-------------------------------------+--------------------------------------+

-The logging functions are named after the level or severity of the events
+The functions are named after the level or severity of the events


Suggested change

The functions are named after the level or severity of the events

The logger methods are named after the level or severity of the events

vsajip · 2023-05-06T06:48:29Z

Doc/library/logging.rst

-   Logs a message with level :const:`WARNING` on the root logger. The arguments
-   are interpreted as for :func:`debug`.
+   Logs a message with level :const:`WARNING` on the root logger. The arguments and behavior
+   are the otherwise same as for :func:`debug`.


Suggested change

are the otherwise same as for :func:`debug`.

are otherwise the same as for :func:`debug`.

vsajip · 2023-05-06T06:48:44Z

Doc/library/logging.rst

-   Logs a message with level :const:`ERROR` on the root logger. The arguments are
-   interpreted as for :func:`debug`.
+   Logs a message with level :const:`ERROR` on the root logger. The arguments and behavior
+   are the otherwise same as for :func:`debug`.


Suggested change

are the otherwise same as for :func:`debug`.

are otherwise the same as for :func:`debug`.

vsajip · 2023-05-06T06:48:59Z

Doc/library/logging.rst

-   Logs a message with level :const:`CRITICAL` on the root logger. The arguments
-   are interpreted as for :func:`debug`.
+   Logs a message with level :const:`CRITICAL` on the root logger. The arguments and behavior
+   are the otherwise same as for :func:`debug`.


Suggested change

are the otherwise same as for :func:`debug`.

are otherwise the same as for :func:`debug`.

vsajip · 2023-05-06T06:49:17Z

Doc/library/logging.rst

-   Logs a message with level :const:`ERROR` on the root logger. The arguments are
-   interpreted as for :func:`debug`. Exception info is added to the logging
+   Logs a message with level :const:`ERROR` on the root logger. The arguments and behavior
+   are the otherwise same as for :func:`debug`. Exception info is added to the logging


Suggested change

are the otherwise same as for :func:`debug`. Exception info is added to the logging

are otherwise the same as for :func:`debug`. Exception info is added to the logging

Doc/library/logging.rst

bedevere-bot · 2023-05-06T06:50:36Z

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

vsajip · 2023-05-06T06:52:41Z

Also @quicknir please remember to sign the CLA and resolve the build errors.

vsajip · 2023-07-22T14:33:40Z

Hi @quicknir, are you planning to work on this in the near future?

quicknir · 2023-08-14T23:01:13Z

@vsajip Hey, yes, I should have some time to work on this soon.

vsajip · 2023-11-23T08:03:49Z

Hi @quicknir - any idea when you might have time to progress this?

quicknir · 2023-12-06T13:26:20Z

@vsajip Hey, sorry for the hold up. I think I will have some time in mid January; going to try to make it a goal to have this merged in Jan-Feb.

vsajip · 2024-03-09T16:48:56Z

Any chance you'll be able to work on this soon, @quicknir?

quicknir · 2024-03-11T23:19:38Z

@vsajip hey, I integrated all your feedback, rebased, built the docs locally (fixing another issue in the process). Hopefully we can power this through :-).

vsajip · 2024-03-12T22:51:09Z

Thanks. The docs build is failing because of warnings, I'm not yet sure if it's caused by your changes but hope to look more closely soon.

quicknir · 2024-03-12T23:04:42Z

@vsajip I suspect that they are, they all look like this

Warning: py:meth reference target not found: logger.debug
/home/runner/work/cpython/cpython/Doc/howto/logging.rst:28: WARNING: py:meth reference target not found: logger.debug

But I'm not sure I understand exactly why it's happening.

miss-islington-app · 2024-03-13T15:59:12Z

Thanks @quicknir for the PR, and @vsajip for merging it 🌮🎉.. I'm working now to backport this PR to: 3.11.
🐍🍒⛏🤖

miss-islington-app · 2024-03-13T15:59:12Z

Thanks @quicknir for the PR, and @vsajip for merging it 🌮🎉.. I'm working now to backport this PR to: 3.12.
🐍🍒⛏🤖

…01618) (cherry picked from commit 7f418fb) Co-authored-by: Nir Friedman <quicknir@gmail.com> Co-authored-by: Vinay Sajip <vinay_sajip@yahoo.co.uk>

bedevere-app · 2024-03-13T15:59:22Z

GH-116733 is a backport of this pull request to the 3.11 branch.

…01618) (cherry picked from commit 7f418fb) Co-authored-by: Nir Friedman <quicknir@gmail.com> Co-authored-by: Vinay Sajip <vinay_sajip@yahoo.co.uk>

bedevere-app · 2024-03-13T15:59:28Z

GH-116734 is a backport of this pull request to the 3.12 branch.

quicknir · 2024-03-13T16:14:31Z

@vsajip thanks for your patience, and cheers on merging it :-)

GH-116733) (cherry picked from commit 7f418fb)

GH-116734) (cherry picked from commit 7f418fb)

…01618) Co-authored-by: Vinay Sajip <vinay_sajip@yahoo.co.uk>

quicknir requested a review from vsajip as a code owner February 6, 2023 20:59

bedevere-bot added the awaiting review label Feb 6, 2023

bedevere-bot mentioned this pull request Feb 6, 2023

logging documentation is tough for beginners #98731

Closed

bedevere-bot added docs Documentation in the Doc dir skip news labels Feb 6, 2023

vsajip requested changes May 6, 2023

View reviewed changes

bedevere-bot removed the awaiting review label May 6, 2023

bedevere-bot added the awaiting changes label May 6, 2023

vsajip requested a review from CAM-Gerlach May 6, 2023 06:51

Improvements to logging documentation

34f3e79

quicknir force-pushed the nf-logging-docs branch from b89cfa1 to 34f3e79 Compare March 11, 2024 23:18

vsajip added 2 commits March 13, 2024 14:56

Fix grammar.

077ab25

Attempt to remove causes of warnings.

2746201

vsajip approved these changes Mar 13, 2024

View reviewed changes

bedevere-app bot added awaiting merge and removed awaiting changes labels Mar 13, 2024

vsajip merged commit 7f418fb into python:main Mar 13, 2024

bedevere-app bot removed the awaiting merge label Mar 13, 2024

vsajip added the needs backport to 3.11 only security fixes label Mar 13, 2024

vsajip added the needs backport to 3.12 only security fixes label Mar 13, 2024

bedevere-app bot removed the needs backport to 3.11 only security fixes label Mar 13, 2024

bedevere-app bot removed the needs backport to 3.12 only security fixes label Mar 13, 2024

vsajip pushed a commit that referenced this pull request Mar 13, 2024

[3.11] gh-98731: Improvements to the logging documentation (GH-101618) (

039fd9e

GH-116733) (cherry picked from commit 7f418fb)

vsajip pushed a commit that referenced this pull request Mar 13, 2024

[3.12] gh-98731: Improvements to the logging documentation (GH-101618) (

0cca762

GH-116734) (cherry picked from commit 7f418fb)

vstinner pushed a commit to vstinner/cpython that referenced this pull request Mar 20, 2024

pythongh-98731: Improvements to the logging documentation (pythonGH-1…

48313cb

…01618) Co-authored-by: Vinay Sajip <vinay_sajip@yahoo.co.uk>

adorilson pushed a commit to adorilson/cpython that referenced this pull request Mar 25, 2024

pythongh-98731: Improvements to the logging documentation (pythonGH-1…

5724f68

…01618) Co-authored-by: Vinay Sajip <vinay_sajip@yahoo.co.uk>

diegorusso pushed a commit to diegorusso/cpython that referenced this pull request Apr 17, 2024

pythongh-98731: Improvements to the logging documentation (pythonGH-1…

4ca8184

…01618) Co-authored-by: Vinay Sajip <vinay_sajip@yahoo.co.uk>

		@@ -26,9 +26,11 @@ When to use logging
		^^^^^^^^^^^^^^^^^^^

		Logging provides a set of convenience functions for simple logging usage. These

	this example. In larger programs you'll usually want to control this call
	this example. In larger programs you'll usually want to control the logging configuration

	The functions are named after the level or severity of the events
	The logger methods are named after the level or severity of the events

	are the otherwise same as for :func:`debug`.
	are otherwise the same as for :func:`debug`.

Uh oh!

gh-98731: Improvements to the logging documentation #101618

gh-98731: Improvements to the logging documentation #101618

Uh oh!

Conversation

quicknir commented Feb 6, 2023 • edited by bedevere-bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ghost commented Feb 6, 2023 • edited by ghost Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

bedevere-bot commented May 6, 2023

Uh oh!

vsajip commented May 6, 2023

Uh oh!

vsajip commented Jul 22, 2023

Uh oh!

quicknir commented Aug 14, 2023

Uh oh!

vsajip commented Nov 23, 2023

Uh oh!

quicknir commented Dec 6, 2023

Uh oh!

vsajip commented Mar 9, 2024

Uh oh!

quicknir commented Mar 11, 2024

Uh oh!

vsajip commented Mar 12, 2024

Uh oh!

quicknir commented Mar 12, 2024

Uh oh!

miss-islington-app bot commented Mar 13, 2024

Uh oh!

miss-islington-app bot commented Mar 13, 2024

Uh oh!

bedevere-app bot commented Mar 13, 2024

Uh oh!

bedevere-app bot commented Mar 13, 2024

Uh oh!

quicknir commented Mar 13, 2024

Uh oh!

Uh oh!

quicknir commented Feb 6, 2023 •

edited by bedevere-bot

Loading

ghost commented Feb 6, 2023 •

edited by ghost

Loading