Resolves #1204.

Codecov Report

coverage has no change and project coverage change: -0.01⚠️

Comparison is base (cbd7690) 92.16% compared to head (80d964e) 92.15%.

❗ Current head 80d964e differs from pull request most recent head df741f3. Consider uploading reports for the commit df741f3 to get more accurate results

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1205      +/-   ##
==========================================
- Coverage   92.16%   92.15%   -0.01%     
==========================================
  Files          97       97              
  Lines       12332    12334       +2     
  Branches     2534     2534              
==========================================
+ Hits        11366    11367       +1     
  Misses        645      645              
- Partials      321      322       +1     

Impacted Files	Coverage Δ
nibabel/info.py	100.00% <ø> (ø)

... and 6 files with indirect coverage changes

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report in Codecov by Sentry.
📢 Do you have feedback about the report comment? Let us know in this issue.

Okay, so it looks like the reason things ended up like this is that there's no way to unify reference links like :ref:`heading` and `text <heading>`_ in Sphinx. We could do something like manually dereference so links_names.rst contains something like:

.. _appendix of the manual: ./legal.html#license
.. _installation: ./installation.html#installation

And README.rst could have:

.. _appendix of the manual: https://nipy.org/nibabel/legal.html#license
.. _installation: https://nipy.org/nibabel/installation.html#installation

It's not great, but we don't really reorganize much.

Sorry if I'm missing something, but couldn't we just use the second option anywhere there's a :ref:?
E.g., we could replace:

* :ref:`User Documentation <manual>` (manual)

with:

* `User Documentation <manual>`_ (manual)

and include:

.. _manual: https://nipy.org/nibabel/manual.html#manual

in links_names.txt?

Also, seems to me like the content in parentheses under the Documentation heading could be removed for a cleaner look.

EDIT: Actually, where do you find this to be a problem? I don't see anything wrong looking at my local build.

The reason not to use an absolute URL in links_names.rst is so that the link stays within site for testing. Right now if I test with python -m http.server -d build, I get https://nipy.org/nibabel/legal.html instead of http://0.0.0.0:8000/legal.html. If for some reason we moved things around, we wouldn't see the breakage until we uploaded the docs to gh-pages.

@effigies please see the proposed changes. Hope I understood correctly.