Skip to content

Use the correct internal link format in Rebel Engine API#90

Merged
DanielaOrtner merged 1 commit into
RebelToolbox:mainfrom
madmiraal:update-internal-link-format
Jul 23, 2024
Merged

Use the correct internal link format in Rebel Engine API#90
DanielaOrtner merged 1 commit into
RebelToolbox:mainfrom
madmiraal:update-internal-link-format

Conversation

@madmiraal
Copy link
Copy Markdown
Contributor

Currently, when building Rebel Documentation, links from Rebel Engine API to other pages in Rebel Documentation are not tested, because they are created as external links. This has allowed various broken internal Rebel Documentation links (see #89). Furthermore, tutorial links are ignoring the alternative text provided, and tutorial links to sections are creating two links: one to the section that uses the URI fragment as the alternative text, and one to the page (that also ignores the alternative text).

This PR applies RebelToolbox/RebelDocumentation#35 to the Rebel Engine API i.e. it improves cross-referencing from the Rebel Engine API to other pages and sections in Rebel Documentation. Links to Rebel Documentation i.e. links to https://docs.rebeltoolbox.com/<lang>/<version>... are created as internal links, which are tested when Rebel Documentation is built.

Links to Rebel Documentation pages are created as:

  • :doc:`/full/path/to/page`
  • :doc:`Alternative text </full/path/to/page>`

Links to sections in Rebel Documentation pages are created as:

  • :ref:`full/path/to/page:section heading`
  • :ref:`Alternative text <full/path/to/page:section heading>`

In addition, it uses the same function for:

<tutorials>
    <link title="Alternative text">
        https://docs.rebeltoolbox.com/en/latest/full/path/to/page
    </link>
    <link title="Alternative text">
        https://docs.rebeltoolbox.com/en/latest/full/path/to/page#section-heading
    </link>
</tutorials>

and

<description>
    ... [url=https://docs.rebeltoolbox.com/en/latest/full/path/to/page]
    Alternative text[/url]...
    ... [url=https://docs.rebeltoolbox.com/en/latest/full/path/to/page#section-heading]
    Alternative text[/url]...
</description>

Finally, it improves the look and feel of tutorial links. Specifically:

  1. Links are created with the specified alternative text.
  2. When referencing a section, only a single link with the specified alternative text is created.

Converts Rebel Engine API links to Rebel Documentation i.e.
links to https://docs.rebeltoolbox.com/<lang>/<version> to
use the internal link format:

Links to Rebel Documentation pages:
- :doc:`/full/path/to/page`
- :doc:`Alternative text </full/path/to/page>`

Links to sections in Rebel Documentation pages:
- :ref:`full/path/to/page:section heading`
- :ref:`Alternative text <full/path/to/page:section heading>`

And use the same function for:
<tutorials>
    <link title="Alternative text">
        https://docs.../full/path/to/page
    </link>
    <link title="Alternative text">
        https://docs.../full/path/to/page#section-heading
    </link>
</tutorials>

and

<description>
    ... [url=https://docs.../full/path/to/page]
    Alternative text[/url]...
    ... [url=https://docs.../full/path/to/page#section-heading]
    Alternative text[/url]...
</description>
@madmiraal madmiraal added the PR Type: Enhancement Your current game will work better. label Jul 22, 2024
@DanielaOrtner DanielaOrtner self-requested a review July 23, 2024 09:25
Copy link
Copy Markdown
Contributor

@DanielaOrtner DanielaOrtner left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for changing to the correct link format :)

@DanielaOrtner DanielaOrtner merged commit f5399a9 into RebelToolbox:main Jul 23, 2024
@madmiraal madmiraal deleted the update-internal-link-format branch July 23, 2024 14:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

PR Type: Enhancement Your current game will work better.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants