Sphinx offers a great balance for me, with its ability to have free-form markdown-like (restructured text) files, combined with the ability to bring in documentation from comments/docstrings in the source code (via "autodoc").