DOC: Merged duplicate README and index sections

[ZviBaratz]

Resolves #1204.

[codecov[bot]]

Codecov Report

Patch coverage has no change and project coverage change: -0.01 :warning:

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

:exclamation: 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.

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

[effigies]

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.

[ZviBaratz]

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.

[effigies]

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.

[ZviBaratz]

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