Bibliography References Link To Tutorials Over Function

Understanding the Issue

In the context of documentation, bibliography references play a crucial role in providing users with additional information and resources. However, there seems to be an odd behavior where if a given reference link is used both in the function docstring and also in a tutorial in the docs, clicking on the reference link in the function docstring takes the user to the reference in the tutorial (instead of the local one in the function). This issue is not limited to a single example, but rather a common problem that affects any reference with this type of "double citation".

What is Double Citation?

Double citation occurs when a reference link is used in both the function docstring and a tutorial in the docs. This can happen when a developer wants to provide additional information or context to a function or method, and they include a reference link to a tutorial or documentation page. However, this can lead to confusion and unexpected behavior, as clicking on the reference link in the function docstring takes the user to the reference in the tutorial instead of the local one in the function.

Example: State Props

One example of this issue is in the state_props.is_antidistinguishable function in the Toqito library. The function docstring includes a reference link to a tutorial in the docs, which is also linked to in the tutorial itself. When a user clicks on the reference link in the function docstring, they are taken to the reference in the tutorial instead of the local one in the function.

### state_props.is_antidistinguishable

```python
def is_antidistinguishable(self, state):
    """
    Checks if the given state is antidistinguishable.

    Parameters
    ----------
    state : State
        The state to check.

    Returns
    -------
    bool
        Whether the state is antidistinguishable.

    References
    ----------
    .. [1] Toqito Documentation: State Props
        <https://toqito.readthedocs.io/en/latest/autoapi/state_props/index.html>
    """

Why Does This Happen?

This issue occurs because of the way that documentation tools handle reference links. When a reference link is used in both the function docstring and a tutorial in the docs, the documentation tool may prioritize the tutorial reference over the local one in the function. This can happen for a variety of reasons, including:

• The tutorial reference may be more up-to-date or accurate than the local reference in the function.
• The tutorial reference may be more comprehensive or detailed than the local reference in the function.
• The documentation tool may be configured to prioritize tutorial references over local references.

How to Fix This Issue

To fix this issue, developers can take a few steps:

• Use unique reference links: Make sure that each reference link is unique and not duplicated in both the function docstring and a tutorial in the docs.
• Use local references: Use local references in the function docstring instead of referencing a tutorial or documentation page.
• Configure the documentation tool: Configure the documentation tool to prioritize local references over tutorial references.

Best Practices

To avoid this issue in the, developers can follow these best practices:

• Use clear and concise reference links: Use clear and concise reference links that are easy to understand and follow.
• Use unique reference links: Use unique reference links that are not duplicated in both the function docstring and a tutorial in the docs.
• Test the documentation: Test the documentation to ensure that reference links are working correctly and taking users to the expected location.

Conclusion

Q: What is double citation, and how does it affect documentation?

A: Double citation occurs when a reference link is used in both the function docstring and a tutorial in the docs. This can lead to confusion and unexpected behavior, as clicking on the reference link in the function docstring takes the user to the reference in the tutorial instead of the local one in the function.

Q: Why does this issue occur?

A: This issue occurs because of the way that documentation tools handle reference links. When a reference link is used in both the function docstring and a tutorial in the docs, the documentation tool may prioritize the tutorial reference over the local one in the function.

Q: How can I fix this issue?

A: To fix this issue, you can take a few steps:

• Use unique reference links: Make sure that each reference link is unique and not duplicated in both the function docstring and a tutorial in the docs.
• Use local references: Use local references in the function docstring instead of referencing a tutorial or documentation page.
• Configure the documentation tool: Configure the documentation tool to prioritize local references over tutorial references.

Q: What are some best practices to avoid this issue?

A: To avoid this issue, you can follow these best practices:

• Use clear and concise reference links: Use clear and concise reference links that are easy to understand and follow.
• Use unique reference links: Use unique reference links that are not duplicated in both the function docstring and a tutorial in the docs.
• Test the documentation: Test the documentation to ensure that reference links are working correctly and taking users to the expected location.

Q: How can I ensure that reference links are working correctly?

A: To ensure that reference links are working correctly, you can:

• Test the documentation: Test the documentation to ensure that reference links are working correctly and taking users to the expected location.
• Use a documentation tool with a built-in link checker: Use a documentation tool with a built-in link checker to identify and fix broken links.
• Regularly review and update documentation: Regularly review and update documentation to ensure that reference links are accurate and up-to-date.

Q: What are some common mistakes that can lead to this issue?

A: Some common mistakes that can lead to this issue include:

• Duplicating reference links: Duplicating reference links in both the function docstring and a tutorial in the docs.
• Using outdated or incorrect reference links: Using outdated or incorrect reference links that are not accurate or up-to-date.
• Not testing the documentation: Not testing the documentation to ensure that reference links are working correctly.

Q: How can I prevent this issue in the future?

A: To prevent this issue in the future, you can:

• Develop a documentation style guide: Develop a documentation style guide that outlines best practices for writing and formatting documentation.
• Use a documentation tool with a built-in link checker: Use a documentation tool with a built-in link checker to identify and fix broken links.
• Regularly review and update documentation: Regularly review and update documentation to ensure that reference links are accurate and up-to-date.