Document cgitb.text and cgitb.html

[masklinn]

BPO	29920
Nosy	@masklinn, @berkerpeksag, @vadmium, @serhiy-storchaka, @iritkatriel
PRs	bpo-29920: Document cgitb.text and cgitb.html #849 [3.6] bpo-29920: Document cgitb.text() and cgitb.html() functions (GH-849) #1527 [3.5] bpo-29920: Document cgitb.text() and cgitb.html() functions (GH-849) #1528

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2022-04-02.18:57:18.192>
created_at = <Date 2017-03-27.13:16:48.967>
labels = ['type-feature', '3.7', 'docs']
title = 'Document cgitb.text and cgitb.html'
updated_at = <Date 2022-04-02.18:57:18.191>
user = 'https://github.com/masklinn'

bugs.python.org fields:

activity = <Date 2022-04-02.18:57:18.191>
actor = 'iritkatriel'
assignee = 'docs@python'
closed = True
closed_date = <Date 2022-04-02.18:57:18.192>
closer = 'iritkatriel'
components = ['Documentation']
creation = <Date 2017-03-27.13:16:48.967>
creator = 'xmorel'
dependencies = []
files = []
hgrepos = []
issue_num = 29920
keywords = []
message_count = 8.0
messages = ['290608', '290612', '293072', '293394', '294926', '294929', '294949', '416578']
nosy_count = 6.0
nosy_names = ['xmorel', 'docs@python', 'berker.peksag', 'martin.panter', 'serhiy.storchaka', 'iritkatriel']
pr_nums = ['849', '1527', '1528']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue29920'
versions = ['Python 3.7']

[masklinn]

Currently, cgitb documents the hook (enable) and somewhat unclearly the ability to dump the HTML traceback to stdout, but despite that being technically available it does not document the ability to dump the traceback to a string as either text or html.

Possible further improvement: make cgitb.html and cgitb.text implicitly call sys.exc_info() if not given a parameter (much like cgitb.handler does).

[masklinn]

PR targetted to master rather than 2.7

[berkerpeksag]

New changeset c07b3a1 by Berker Peksag (masklinn) in branch 'master':
bpo-29920: Document cgitb.text() and cgitb.html() functions (GH-849)
c07b3a1

[serhiy-storchaka]

The main functions of the cgitb module are enable() and handler(). I would describe them first, and text() and html() at the end (maybe in separate subsection). Actually the main part of the descriptions of text() and html() can be shared and placed in a paragraph preceding them: "The following two functions handle..."

Note that the documented name of the first parameter is "info", but actual name is "einfo".

[masklinn]

Should I close this since the PR was merged?

[serhiy-storchaka]

I suggest to move the descriptions of text() and html() after handle(). And I don't know what to do with the discrepancy in the parameter name.

[berkerpeksag]

Please don't close it yet. I agree with Serhiy's comments in msg293394, but I couldn't find time to address his comments yet (plus we still need to backport the documentation update to 3.5 and 3.6 branches)

[iritkatriel]

Closing as the backport to 3.5/3.6 is no longer relevant and also cgitb is deprecated under 594.