I would say Sphinx has the exact problem grandparent describes. I've spent a lot of time and frustration trying to figure out what syntax it wants to link to another doc, for example.

Yes, it was harder than it probably should be but now that I've written a book in it I've got it down by heart. Probably needs to be more prominent in the docs:

    # doc1, the destination
    
    .. _introduction:

    Introduction
    ---------------

    asdf asdf…

Then in the source document:

    # doc2, the source

    In the :ref:`Intro <introduction>` or 
    simply :ref:`introduction`,
    blah blah blah.

I made snippets in my editor to help with common tasks such as this.