Resurrect docs interlinking #2427
Conversation
It's been lost as a part of pypa#2097
|
This change includes a commit from #2425 so if it's accepted earlier, it's okay to close that PR. I've recovered references to orphans in order for nitpicks to be satisfied. I hope that @alvyjudy will clean that up once we have automatic breakage enforcement in place. I've also noticed some document duplicates that will probably need to be dropped but I'm not trying to decide on any refactoring as a part of this PR: I just want the build to be green and correct. In general, this should prevent contributors from supporting broken docs. |
| @@ -31,5 +31,4 @@ setuptools changes. You have been warned. | |||
| :maxdepth: 1 | |||
|
|
|||
| developer-guide | |||
| formats | |||
There was a problem hiding this comment.
This one was renamed to python_eggs and is currently linked from deprecated/index TOC.
| build_meta | ||
| pkg_resources | ||
| references/keywords | ||
| roadmap | ||
| setuptools |
There was a problem hiding this comment.
I've linked the orphans here but they'll need to be cleaned up separately. I think it's out of scope of this PR.
cc @alvyjudy
| ======== | ||
| Keywords | ||
| ======== | ||
|
|
There was a problem hiding this comment.
Needed to be linkable from TOC
| To peek into how this legacy keyword is used, consult our :ref:`guide on | ||
| deprecated practice (WIP)` | ||
| To peek into how this legacy keyword is used, consult our :doc:`guide on | ||
| deprecated practice (WIP) <../deprecated/index>` |
There was a problem hiding this comment.
best guess since archeology wasn't helpful
| Example WIP |
| @@ -46,7 +46,7 @@ that were built most recently. | |||
|
|
|||
| If you have to manage automated builds for multiple packages, each with | |||
| different tagging and rotation policies, you may also want to check out the | |||
| `alias`_ command, which would let each package define an alias like ``daily`` | |||
| :ref:`alias <alias>` command, which would let each package define an alias like ``daily`` | |||
There was a problem hiding this comment.
Honestly, the markup for the commands has to be remade to use the built-in command/option roles but I just used the existing labels for now. Quick and dirty.
| functionalities_rewrite | ||
| miscellaneous |
There was a problem hiding this comment.
@alvyjudy this may need a careful cleanup in the future
| @@ -8,19 +8,19 @@ unless you need the associated ``setuptools`` feature. | |||
| ``include_package_data`` | |||
| If set to ``True``, this tells ``setuptools`` to automatically include any | |||
| data files it finds inside your package directories that are specified by | |||
| your ``MANIFEST.in`` file. For more information, see the section below on | |||
There was a problem hiding this comment.
@alvyjudy here and in many other places (even outside of this PR) the text keeps referring to sections "below" and "above" while those are no longer in the same document. JFYI if you're up to reading through the whole documentation to find such places...
| @@ -98,9 +98,9 @@ unless you need the associated ``setuptools`` feature. | |||
| added to the tests to be run. If the named suite is a package, any | |||
| submodules and subpackages are recursively added to the overall test suite. | |||
|
|
|||
| Specifying this argument enables use of the `test`_ command to run the | |||
| Specifying this argument enables use of the :ref:`test <test>` command to run the | |||
There was a problem hiding this comment.
<test> is necessary to have test as an anchor and not the title that may be set in the other document under the label.
| @@ -1,3 +1,5 @@ | |||
| .. _Automatic Resource Extraction: | |||
There was a problem hiding this comment.
I had to re-add some labels that have been removed in the original refactoring to make such places linkable. We need to consider enabling sphinx's built-in autolabel extension instead. But this would be a separate effort because it would involve cleaning everything up and making sure there are no title duplicates.
cc @alvyjudy
| @@ -6,13 +6,13 @@ Package Discovery and Namespace Package | |||
|
|
|||
| .. note:: | |||
| a full specification for the keyword supplied to ``setup.cfg`` or | |||
| ``setup.py`` can be found at :ref:`keywords reference <keywords_ref>` | |||
| ``setup.py`` can be found at :doc:`keywords reference <keywords>` | |||
There was a problem hiding this comment.
:ref: links labels, while :doc: links documents (by filename)
| @@ -82,8 +82,8 @@ Automatic package discovery | |||
| For simple projects, it's usually easy enough to manually add packages to | |||
| the ``packages`` keyword in ``setup.cfg``. However, for very large projects | |||
| , it can be a big burden to keep the package list updated. ``setuptools`` | |||
| therefore provides two convenient tools to ease the burden: ``find: `` and | |||
| ``find_namespace: ``. To use it in your project: | |||
| therefore provides two convenient tools to ease the burden: :literal:`find:\ ` and | |||
There was a problem hiding this comment.
w/o :literal:, escaping the spaces does not work.
| -a \ | ||
| -n \ | ||
| -W \ |
There was a problem hiding this comment.
these are especially important in our goal to make sphinx strict
|
@webknjaz it really cringes me how many mistakes I have made while working on the docs. I had planned on getting an outline out there and add in the details later (obviously the second step didn't happen and I feel quite embarrassed by such work ethics:(. I think I will go through them these days and fix the issues. Again big thanks for pointing them out |
webknjaz
force-pushed
the
maintenance/resurrect-docs-interlinking
branch
from
79168bd
to
0cff2e7
Compare
webknjaz
force-pushed
the
maintenance/resurrect-docs-interlinking
branch
from
0cff2e7
to
3d9fc0b
Compare
|
@alvyjudy hey! Don't feel ashamed. Your initial contribution was good, it's okay to miss things sometimes. I only added comments for you so that it'd be easier to track stuff when you get to it in the spirit of collaboration :) Also, it's totally not your fault that strict mode was off in the sphinx setup. Now that it'll be fixed and enforced, it'll be a helpful tool for everyone to catch mistakes. |
|
@jaraco mind labeling this PR as |
Summary of changes
This change eliminates all the sphinx warnings and recovers
all the broken interdoc references, and gets rid of the
syntactic typos.
Fixes #2424
Pull Request Checklist