This is a course on software documentation for researchers developed by the Research Software Engineering team and IT Services at the University of Sheffield.
I appreciate not all Python projects will be scientifically aligned but many would be.
This would encourage the use of Type Hints which code bases benefit from having as there are linters which can check type hints are consistent and correct which in turn reduces the amount of errors that can arise when running code (using Type Hints in examples could easily be a separate issue though).
There is also a convention for adding examples sections to docstrings and these can even form the basis of tests for a package via the standard libraries doctest (and of course pytest supports doctest.
Using Type Hints and adding Examples could easily be their own issues so listing below to facilitate creation of these if it is desirable to do so.
The Scientific Python Documentation Tutorial recommends using numpydoc formatted docstrings in Python as they work well with Sphinx's
autodocandautosummaryextensions.I appreciate not all Python projects will be scientifically aligned but many would be.
This would encourage the use of Type Hints which code bases benefit from having as there are linters which can check type hints are consistent and correct which in turn reduces the amount of errors that can arise when running code (using Type Hints in examples could easily be a separate issue though).
There is also a convention for adding
examplessections to docstrings and these can even form the basis of tests for a package via the standard libraries doctest (and of course pytest supports doctest.Using Type Hints and adding Examples could easily be their own issues so listing below to facilitate creation of these if it is desirable to do so.