Improve API reference documentation

[zklaus]

Why?

The current API reference documentation (entry point) offers some opportunity for improvements.

A few relatively simple steps can set us up to improve both developer and user experience.

User impact

Developers will find it easier to improve the documentation because fewer guesses on styles and associated resources will be necessary.
Users and developers will profit from an improved and improving documentation.

Goals

This epic will focus important decisions regarding documentation styles. While there likely different valid choices for any of those, making a decision and advertising it appropriately will increase homogeneity in the code base.
As such, the goals of this epic are twofold: First, take decisions on a few key aspects of documentation style; second, advertise them so that they will be taken into account in future developments.

Tasks

Preview Give feedback

1. Docstring format decision and advertisement #946
   type::documentation +1
2. Guidance on rst vs md for documentation #947
   type::documentation +1
3. What should be included in the API reference documentation? #948
   type::documentation +1

This epic is blocked by

Nothing

This epic blocks

Nothing is directly blocked, but addressing this epic will make it easier to improve the documentation.
In particular, it will make it easier to address the fact that there is a relatively large number of warnings and some errors¹ during the building of the docs, see, e.g., the latest log on readthedocs (click on the first python -m sphinx call to expand), which makes it harder to identify issues introduced by newly written documentation and also impedes the ability for incremental docs builds, resulting in an overall harder developer experience for writing docs.
This is true for several projects in the conda ecosystem, but should be tracked with per-project issues.

Footnotes

1. Looks like most of the errors arise when conda classes don't have docstrings themselves, but are derived from other third-party classes. In that case, the docstring is taken from the parent class and often does not follow any of the supported docstring styles. This is also true for classes from the standard library. ↩

[jezdez]

This is a duplicate of conda/conda#13437.

[jezdez]

Reopening since @zklaus asked for more guidance:

• this covers a large surface area about documentation best practice, and would be better suited for the conda/conda-docs repo as such
• the ticket Add type hints and/or reST docstrings conda#13437 does suggest to improve the rendering of the conda API docs though, so it would basically be an implementation of the suggested best practives

@zklaus I'll move this ticket into conda-docs and would love to ask you to turn it into an epic-type issue, with each of the subheadings above to be a separate task-type issue. Would that work?

[zklaus]

@jezdez, I have rewritten this issue in the style of an epic. I could not add the required labels. Let me know if I should do something else.