Task: Simple First PR to NumPy - Update internal links

[bmwoodruff]

If you have never contributed a PR to an open-source project before, then here is a short task that can get you started.

At the triage meeting on May 1, we discussed an improvement to NumPy that is wanted and welcome. As you spend time in the documentation, you'll notice that occasionally the links for internal functions are missing (or perhaps broken). These are simple to fix and provide a great chance to practice the PR (pull request) process. We'll be in the documentation a lot over the next 3 months, so we can tackle this bit by bit.

Make sure you start by reading the style guide. In particular, the tiny bit at the bottom about common reST concepts is crucial. Many of the missing links appear because someone used double back ticks, when all they needed were single back ticks. Here's some examples.

``default_rng`` #appears as monospace. Should be avoided for numpy functions
`default_rng` #creates internal link to default_rng, of which the only one is numpy.random.default_rng
`~default_rng` #same as above, the tilde isn't needed
`numpy.random.default_rng` #creates internal link to numpy.random.default_rng
`~numpy.random.default_rng` #creates internal link to numpy.random.default_rng, but the link text is default_rng

In many places in the code you'll see spots where people have added an extra tilde that isn't needed. We don't need to remove the tilde. We can replace the double back ticks with single back ticks, when the monospaced item is a function inside NumPy. If two classes have a function with the same name, then you may need the tilde.

After you've made changes, remember to build the docs locally on your machine and verify the links were appropriately created. Some NumPy functions don't have docs attached (perfect, let's try to generate some with AI). In this case, when we try to create a single backticked internal link, we get an error in the docs build process.

Functions that are not part of NumPy have also been double backticked (displaying as monspace). These can be improved as well, using more Sphinx markup. The bit below creates a link to the python function secrets.randbits. See this implemented at https://numpy.org/devdocs/reference/random/parallel.html.

:py:func:`secrets.randbits`

The OSS maintainers would prefer this be done bit by bit. They manually check each change, and would prefer to NOT have to spend hours checking hundreds of links all at once. A few here and there is fine. If someone wants to write a script to do all the replacements, and that script can be run and verified by the maintainers, then they would welcome that as well.

If you decide to pick up this task, please leave a comment below.

Remember that PRs should not be submitted directly to numpy. Either @bmwoodruff or @InessaPawson needs to review the work first. Here a possible workflow.

• Make changes locally on a feature branch, and test them (build the docs for this example).
• After you've tested things work, push the changes to the feature branch of your numpy fork.
• Create an issue here in genai-numpy with an @bmwoodruff tag letting me know your work needs review. Include a link to the recent commit to your feature branch.
• Once you have approval, you can submit the PR to numpy.

[bmwoodruff]

Contributing to an open source project can be difficult. There's an initial mental hurdle to pass, namely that your work will be completely open and you have no idea how things will turn out. Mars Lee created the following comic to help newcomers alleviate the anxiety that comes with doing so. It's a fun read.

https://heyzine.com/flip-book/3e66a13901.html#page/1

[otieno-juma]

@bmwoodruff Hello Ben, I'm interested in working on this issue. Could you spare some time this week? I would appreciate your guidance on a few things. Starting might be a bit of a challenge, but once I have a complete idea, then I will be okay moving forward.