Policy choice? Don't use "<<<<<<<<" or ">>>>>>>>" as heading underlines

Documentation
1

I very much doubt patch would get confused, but I did a brief double-take when I saw this in multiprocessing.rst:

The :mod:`multiprocessing.sharedctypes` module
>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>

.. module:: multiprocessing.sharedctypes
   :synopsis: Allocate ctypes objects from shared memory.

Although valid ReST, I think there are plenty of other punctuation characters which could be used instead. I’m happy to create a PR.

9 Likes
2

The reccommended underlines per the Developer’s Guide:

Normally, there are no heading levels assigned to certain characters as the structure is determined from the succession of headings. However, for the Python documentation, here is a suggested convention:

# with overline, for parts
* with overline, for chapters
=, for sections
-, for subsections
^, for subsubsections
", for paragraphs

A

2 Likes
3

Seems reasonable to me. > doesn’t appear at all in our standard convention for heading hierarchy, the relevant portion of which for a single document is:

  • =, for sections
  • -, for subsections
  • ^, for subsubsections
  • ", for paragraphs

This document appears to be using the first two as normal, but then uses ~ for h3 section headers and > for h4, instead of ^ and ". There doesn’t appear to be any particular reason why that is so, and while I’ve occasionally seen ~, I haven’t seen > used anywhere else I can recall in the Python (or other) docs for that purpose.

Therefore, it seems find to replace the half dozen or so > headings with the recommended ", just make sure they’re all consistent.

4

Thanks. Should be an easy fix, but I’m done for the night. Hopefully tomorrow.

1 Like
5

I submitted a PR. As it turns out there were no <<<<<<<< underlines. My regex wasn’t anchored at the beginning of the line. Only multiprocessing.rst had the suspect underlines.

On an unrelated note, I see that in the Reference section there are several subsections, with Miscellaneous stuck in the middle. I’ve not yet spent time reading through all that, but in my mind, “miscellaneous” suggests “stuff that didn’t fit anywhere else,” and generally appears at the end. Perhaps it should follow The multiprocessing.dummy module.

6

The PR and backports are merged.

Miscellaneous documents functions in the multiprocessing module and something like Toplevel functions might be a better name. (If there are other non-class functions in the top module documented elsewhere, prefix with Miscellaneous. Other docs have similar sections with ‘functions’ in the name. I don’t know whether there is a better place.