There's currently no consistency in how code is formatted in docstrings. We have a mix of pretty simple ``code`` and `code`, and also internal references like :class:`SWIFTDataset`.
I think that the preferred formatting guidelines would be:
- Inline code is formatted with double backticks:
``x = 1``.
- Block code is formatted as:
Paragraph text:
.. code-block:: python
x = 1
y = 2
continued text.
- Cross references are formatted in RST. Importantly, full paths (not import aliases) need to be used for sphinx to link things correctly. This means that
:class:`SWIFTDataset` is incorrect, and :class:`swiftsimio.SWIFTDataset` is also incorrect; :class:`swiftsimio.reader.SWIFTDataset` is correct because this leads to the file where the class definition resides. Giving the full paths can get a bit cluttered, but a tilde suppresses the leading part in the sphinx rendered docs, so usually we should use :class:`~swiftsimio.reader.SWIFTDataset` which is then rendered as SWIFTDataset, lined to the API docs.
- Cross references to external packages work in the same way and will link properly with intersphinx. I don't think we need to link to every single external package mentioned but having working links to e.g.
numpy, scipy, matplotlib and the like is nice and not a lot of effort.
- Cross references in sections like "See Also" use a slightly different syntax, I think, but it would be good if these also hyperlinked. I think here you just use:
See Also
--------
~swiftsimio.reader.SWIFTDataset
Optional description goes here.
It would be good to go through and improve the cross-linking and formatting consistency throughout all of the docstrings. I don't know of any way to automate checking this (and it's not clear that you could ever catch someone using ``SWIFTDataset`` instead of :class:`~swiftsimio.reader.SWIFTDataset` automatically), but I can't claim to have looked at everything in ruff and sphinx, it might be that there's something that we can use to catch at least some cases in CI checks. When this is done we should also write down our "house" style for this and make sure that people who can review PRs know about it as something to look for.
All of the above is of course a suggestion and open to discussion/amendment before any implementation. I think I've had my fill of docstring editing for a little while so not going to get to this imminently anyway.
Types for function parameters & return types are a bit different and I think better handled separately: #270.
There's currently no consistency in how code is formatted in docstrings. We have a mix of pretty simple
``code``and`code`, and also internal references like:class:`SWIFTDataset`.I think that the preferred formatting guidelines would be:
``x = 1``.:class:`SWIFTDataset`is incorrect, and:class:`swiftsimio.SWIFTDataset`is also incorrect;:class:`swiftsimio.reader.SWIFTDataset`is correct because this leads to the file where the class definition resides. Giving the full paths can get a bit cluttered, but a tilde suppresses the leading part in the sphinx rendered docs, so usually we should use:class:`~swiftsimio.reader.SWIFTDataset`which is then rendered asSWIFTDataset, lined to the API docs.numpy,scipy,matplotliband the like is nice and not a lot of effort.It would be good to go through and improve the cross-linking and formatting consistency throughout all of the docstrings. I don't know of any way to automate checking this (and it's not clear that you could ever catch someone using
``SWIFTDataset``instead of:class:`~swiftsimio.reader.SWIFTDataset`automatically), but I can't claim to have looked at everything inruffandsphinx, it might be that there's something that we can use to catch at least some cases in CI checks. When this is done we should also write down our "house" style for this and make sure that people who can review PRs know about it as something to look for.All of the above is of course a suggestion and open to discussion/amendment before any implementation. I think I've had my fill of docstring editing for a little while so not going to get to this imminently anyway.
Types for function parameters & return types are a bit different and I think better handled separately: #270.