Improve generated docstring readability and NumPy-style structure

[munechika-koyo]

Follow-up to #836 for #835.

PR #836 corrected docstring normalization before snippet expansion, subplot C/F ordering documentation, and the projection parameter declaration.
Expanded docstrings are still serialized as single-line escaped literals in built Python sources, and several shared templates contain malformed NumPy-style sections or parameter entries.

This PR makes generated docstrings readable as multiline literals and fixes the remaining structural problems across the package.

Changes

• Write expanded multiline docstrings as triple-quoted literals while preserving their normalized content, literal characters, and build idempotence.
• Correct section headings, indentation, parameter declarations, and return descriptions across shared templates and module docstrings.
• Remove duplicate section headings introduced by ticker snippets and restore separate parameter entries in colorbar and beeswarm documentation.
• Document semantic legend styling keywords as typed parameter entries, with shared value and alias explanations in Notes.
• Extend the installed-package checker with NumPy-style parsing and regression checks, and add numpydoc to the typing and development dependencies.

Validation

• 43 tests passed across test_docstrings.py and test_docstring_helpers.py.
• Built an sdist, built a wheel from that sdist, and installed the wheel into a temporary directory.
• Checked all 1,349 docstrings in project-owned production code using numpydoc.docscrape.NumpyDocString and confirmed that generated literals match the source expansion.
• Passed installed-package checks for malformed structure and unresolved placeholders.
• Verified runtime docstring equality and Sphinx Napoleon conversion for 18 representative APIs.

[codecov]

Codecov Report

❌ Patch coverage is 98.01980% with 2 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
ultraplot/tests/test_docstrings.py	97.91%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!

[cvanelteren]

Can you rebase this back on main. There is some older commits in here.

[cvanelteren]

not sure why this is removed?

[munechika-koyo]

Numpydoc doesn't allow this format in this area. “Other parameters” must follow the same style as “Parameters”.

[cvanelteren]

we should still have the linkback in the existing docs tho

[munechika-koyo]

Isn't it enough to show them only in the existing "See also" section?

[cvanelteren]

Are you intending to do a full sweep of the doc strings to make them numpy compliant or are these just cherry picked? Need to brush up on my numpy docstrings. In general many of the doc strings used a style that I am not too familiar with but the new code I added I just did in the same style.

[munechika-koyo]

Are you intending to do a full sweep of the doc strings to make them numpy compliant or are these just cherry picked? Need to brush up on my numpy docstrings. In general many of the doc strings used a style that I am not too familiar with but the new code I added I just did in the same style.

First, I tried to check the generated docstrings by inspecting cherry-picked sections, but now I am considering a more comprehensive approach, like using ruff for docstring checks as well as code linting.

[cvanelteren]

@munechika-koyo I would halt on moving further. We first started with that the formatting is wrong, I believe this was fixed recently. As the docs are not compatible already with numpy docstrings we don't need to retrofit this. It requires a stance on what UltraPlot wants to be, I think doc string compliance to numpy is not high on it -- as we could also move away from dynamic doc strings which is higher on my list I think in terms of urgency.