Improve API reference documentation

zklaus commented 1 month ago

Checklist

[X] I added a descriptive title
[X] I searched open reports and couldn't find a duplicate

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
- [ ] #946
- [ ] #947
- [ ] #948

This epic is blocked b

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[^1] 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.

[^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 commented 1 month ago

This is a duplicate of conda/conda#13437.

jezdez commented 1 month ago

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 conda/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 commented 1 month ago

@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.

conda / conda-docs