Tracking issue for specification maintenance tasks

[kgryte]

The purpose of this issue is to identify and track various maintenance tasks which have accumulated concerning specification organization and development.

Remaining tasks

• Migrate special cases to use math directives: Migrate documentation of special cases to use math directives #519
• Ensure line length is handled better, so text is readable and reviewable on GitHub without it scrolling off to the right. Either use regular line length settings (80, 88, 100, or 120 char), or set up something like EditorConfig to ensure consistent line endings and spacing.
• Setup linting of Python files (black, pydocstyle) in CI.

Done for v2022

• Move special cases and other explanatory content to a dedicated "notes" section: Reorganize documentation to display parameters and return values more prominently #518
  • PR: Move special cases to notes sections #578
• Add a short sentence about whether the special cases are derived from C99, from some other standard, or are based on analysis or existing practice in array libraries. See Add complex number support to log #514 (comment).
  • PR: Update notes to indicate that branch cuts follow C99 #579
• Use black for automated code formatting and line wrapping (possibly using Git hooks).
  • PR: Run black on .py files (with git-blame-ignore-revs) #575
• Move universal preamble content (e.g., positional parameters, optional parameters, etc) to a dedicated design document.
  • PR: Clean up duplicate blurbs on function conventions; improve fft description #576
• Merge the content in the "branch cuts", "complex number ordering" and "complex numbers" (about equality mostly) design topic pages into a single "complex number support" page.
  • PR: Consolidate complex number design topics and add guidance on value-based promotion #573

[rgommers]

Thanks for summarizing this @kgryte. A few thoughts:

• When doing this, let's try to ensure that large content refactors do not make it harder to use git blame, by using https://docs.github.com/en/repositories/working-with-files/using-files/viewing-a-file#ignore-commits-in-the-blame-view
• Some of this may be a little time-consuming. To me the higher-prio ones, good to get into the v2022 spect, are "move special cases", "move universal preamble", and "use black"
• After that, the "use math directives one", because it's also still a big diff, so makes later maintenance easier if it's done before branching
• Linting in CI and EditorConfig are lower prio, they can be fiddly and don't impact the 2022 content or organization of it

[rgommers]

The v2022 tasks are done. I reorganized the description so it's clear what is left, and removed the milestone.

[kgryte]

As commented in #689 (comment), we should investigate whether we can minimize type annotation duplication. Currently, we copy-paste the type annotation from the signature into the docstring. This increases the risk of drift, and preferably, we'd only need to write these annotations once.

[rgommers]

Sphinx has functionality for that (autodoc_typehints), but like anything autodoc related it had some issues, especially with dealing with type aliases. Not sure if that has been improved recently, but I did try this when initially setting up the docs.

[rgommers]

If I had to deal with this now, I'd dump Sphinx complete in favor of MkDocs / mkdocs-material.

[kgryte]

Sphinx has functionality for that...I'd dump Sphinx completely...

Yeah, we should revisit once we have v2023 released.