I think the ability to write a large pieces of documentation which aren’t bound to a function, class or module is an important feature. This way you can tell the user about some toplevel abstractions and give a bird eye view on the library or system.
For example, handwritten parts of the documentation can provide some code snippets to demonstrate the ways, how to use the library:
And when you are talking about some function or class, you can reference it.
For example, if I’m talking about
foo function, I can reference it like this
:cl:function:`example/app:foo` and it will appear in the code as
Please, note, that if you don’t include the documentation on
foo function, Sphinx will
complain with this warning:
WARNING: Unused symbol doc EXAMPLE/APP:FOO type function
And this text
:cl:function:`example/app:foo` will not become a link.
To learn, how to fix this problem, read about Autogenerated API.