search

radical-cybertools / radical.utils

Utility classes and tools for various radical projects
Other
8 stars 6 forks source link

Doctree is unwieldy and confusing #375

Closed eirrgang closed 1 year ago

eirrgang commented 1 year ago

The documentation hierarchy is full of duplication and confusing nesting levels. It is also missing targets for package modules, including, simply :py:mod:'radical.utils'

I think it would simplify layout and maintenance to add docstrings to all modules (including package modules), and just use automodule for everything. The separate RST documents for subpackages could be removed. It could also help with #359, where classes are frequently referenced using their import aliases in parent classes.

A minimal patch that would provide module targets and a more readable could just remove some duplication and replace some automodule directives with py:module directives.

andre-merzky commented 1 year ago

Many thanks for the PR, @eirrgang ! Can we close this ticket for now or do you think there are items unaddressed?

eirrgang commented 1 year ago

The issue is minimally resolved. I suggest adding actual module docstrings, but that should be a separate issue, and at the discretion of the core team, I think.