Consider using something other than urllib.parse to demonstrate API docs? Plus dummy examples

[smheidrich]

The API docs for urllib.parse included in the theme demos don't feature a single method, only functions and classes without methods, so IMHO it's kind of a bad example to show what typical API docs will look like. Would you be open to using another module for the API docs demo and/or maybe adding some dummy class examples to that page manually?

The latter option would also be good because another thing that differentiates themes is how well they deal with overly long package/module or class/function names, e.g. Alabaster vs Insipid:

 

As such names are rare in Python's standard library, the only (?) way to get this to show would probably be dummy examples. Although maybe they should be on a separate page so people aren't put off themes just because of this edge case.

Thoughts?

[andrei-korshikov]

Also urllib.parse isn't good due to incorrect arguments rendering (well, maybe rendering is correct, but docstrings are not). You can see it on above Insipid screenshot.

Look at qs: percent-encoded query string to be parsed string, qs is not bold. Next string keep_blank_values: flag indicating whether blank values in is bold, but that's not right behavior, only parameter name should be bold.

[pradyunsg]

If someone knows of an existing package to exercise this, I'll happily reuse that. Absent that, I'd also be OK with adapting the demo documentation to use a custom .py file to run autodoc on.

[stevepiercy]

I'm not sure if any of Pyramid's API has better docstrings. At least it renders without errors, unlike urllib.

python3.12/urllib/parse.py:docstring of urllib.parse.quote:13: ERROR: Unexpected indentation.

I would suggest registry.

I'm happy to submit a PR if any of these are agreeable to others.

[cmarqu]

I might suggest asyncio.staggered - it

• exists in the standard library since 3.8 (https://github.com/python/cpython/blob/3.8/Lib/asyncio/staggered.py)
• has type annotations,
• uses the async keyword,
• uses Google-style docstrings for Napoleon,
• uses code in the docstring,
• parses without errors,
• is small.

While not as perfect as a specially crafted file, it is a clear improvement over urllib.parse IMO.

[cmarqu]

Ah well, I got sucked into writing an all-in-one example Python file (not done yet).