On documentation formatting

1

Pytorch 2.13 introduces nn.LinearCrossEntropyLoss.
So its documentation isn’t a legacy and is thoroughly reviewed.

There are some issues I see everywhere (e.g. this unmerged PR).

  1. Attributes should be :attrs:.
  2. Classes should be :class:.
  3. Functions should be :func:.
  4. Python constants should be double-backticked.
  5. Values (and mathematical intervals) should be single-backticked or :math:.
  6. Text (variable names) in math should be \text{}.
  7. “Expresions” like options=None, out_features != (), vmap(grad(...)) should be ??.

What do we see in the source?

1-7. Every rule can be not implied, without any markup.
8. pp. 1-3 can be as p.4.
9. pp. 4 and 5 are messed (e.g. in Default: ).
10. “Lists” are not recognized.
11. Let’s highlight/separate Defaults?

Any thoughts on this?

2

Good catch, I think you could open a PR to fix this!

3

@valerian.rey , thanks for reply.

But it is a systematic issue. What about a systematic solution?

And… That PR has not been merged.

4

But it is a systematic issue. What about a systematic solution?

That would be nice yeah. Do you think it’s possible to create a kind of documentation linter to check / fix this? As far as I know, documentation linting libraries are pretty bad in Python. There are projects like GitHub - PyCQA/docformatter: Formats docstrings to follow PEP 257 · GitHub but it’s not good enough (and it doesnt do anything for text highlighting I think) and not very active. So it’s probably easier to just create you own script for that. But there will always be some ambiguous cases I think, so this script alone cannot fix everything. Maybe AI can also help but it’s gonna be a huge waste of token if it’s regularly run against the whole codebase.

Btw to get your PRs reviewed I think you should comment: @pytorchbot label "module: docs", which will automatically tag the people responsible for the docs.

5

The second (first?) part is review traditions (on documentation strings).

BTW, PyTorch’s Docstring Guidelines lists just some of those rules.

6

I’ve posted this as an issue.