Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: Reformat the oneshot speedup-groups information without the table layout #2248

Open
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

ferdnyc
Copy link

@ferdnyc ferdnyc commented Apr 22, 2023

Summary

  • OS: all
  • Bug fix: no
  • Type: doc
  • Fixes:

Description

IMHO the table layout used for the list of methods sped up by oneshot() was not really working. Horizontal alignment of various methods meant nothing, so having the platforms side-by-side also meant nothing. Blank rows were hard to spot, making the groupings unclear. Basically, it was just a list of groups-of-methods, formatted so it's difficult to read on narrow screens.

This PR folds up each column of the table into a sub-sub-section of a subsection (titled "Method grouping & speedup potential") within the method documentation for oneshot(). Each platform section contains an autonumbered ordered list containing from one to three entries, each of which is a comma-separated list of method names.

Using this format also allowed me to notice that the Solaris and AIX columns were identical, and combine them into a Solaris & AIX section rather than repeating info.

I'm open to changing any or all of this as requested, and of course you're welcome to reject it outright if you feel it's the wrong approach.

Example

In the source, the entries are listed vertically, each on a separate line, which makes editing vastly easier. For example:

    Linux
    """""

    #. :meth:`cpu_num`,
       :meth:`~Process.cpu_percent`,
       :meth:`cpu_times`,
       :meth:`create_time`,
       :meth:`name`,
       :meth:`ppid`,
       :meth:`status`,
       :meth:`terminal`

    #. :meth:`gids`,
       :meth:`num_ctx_switches`,
       :meth:`num_threads`,
       :meth:`uids`,
       :meth:`username`

    #. :meth:`memory_full_info`,
       :meth:`memory_maps`

    *Speedup: +2.6x*

Rendered, that becomes:

image

(Or it may wrap, depending on the viewport width.)

Other changes

Other adjustments I made in the course of doing this:

  1. Fixed the alphabetization in BSD (name was before memory_info), something that would've been tedious to do in the table format, but with this formatting was a simple matter of moving one source line down by two lines.

  2. Updated the .. versionadded for the method from 5.0.0 to 4.5.0, matching other mentions elsewhere in the file.

  3. Moved the .. versionadded above the new subsection, which seemed to be clearer / make more sense, as having it at the very bottom gave the impression that only the last platform was added in 4.5.0.

Signed-off-by: FeRD (Frank Dana) <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant