[issue38975] Add direct anchors to regex syntax documentation
New submission from Baptiste Mispelon <bmispelon@gmail.com>: While writing documentation about regexps for a project I help maintain, I wanted to link to some specific aspects of Python's implementation (in my case, non-capturing groups) which are described on https://docs.python.org/3/library/re.html. There are no visible ¶ anchors for the items in the "Regular Expression Syntax" section. Inspecting the generated HTML, there does seem to be auto-generated ids (like `#index-16` for example) but I wouldn't like to rely on those as I'm not sure how stable they are. I couldn't find how to add the ¶ symbol show up next to the titles but I have a PR that adds a bunch of references so that items can be linked directly. ---------- assignee: docs@python components: Documentation messages: 357831 nosy: bmispelon, docs@python priority: normal severity: normal status: open title: Add direct anchors to regex syntax documentation type: enhancement _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue38975> _______________________________________
Change by Roundup Robot <devnull@psf.upfronthosting.co.za>: ---------- keywords: +patch pull_requests: +16949 stage: -> patch review pull_request: https://github.com/python/cpython/pull/17470 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue38975> _______________________________________
Terry J. Reedy <tjreedy@udel.edu> added the comment: ¶ anchors are generated automatically for headers, but I don't know what the policy might be for items within section. It might be useful to add some subsection headers within the Regular Expression Syntax section. ---------- nosy: +serhiy.storchaka, terry.reedy _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue38975> _______________________________________
Change by Ned Deily <nad@python.org>: ---------- nosy: +mdk _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue38975> _______________________________________
Baptiste Mispelon <bmispelon@gmail.com> added the comment: I've tried using subsection (level 3) for each syntax element and I'm not sure it's a big improvement. Pros: * Visible ¶ anchors which make it easier to copy/paste a reference link Cons: * <h3> headings have a slightly different style (bigger font, no background color) * All the added titles show up in the table of content (might not be a problem) * Lots of re-indenting is needed which makes the diff quite noisy (even without reflowing the paragraphs) I'm not sure what's the best way to share this alternative. A new PR? An extra commit on the existing PR? ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue38975> _______________________________________
participants (4)
-
Baptiste Mispelon -
Ned Deily
-
Roundup Robot
-
Terry J. Reedy