phpDocumentor / guides

Guides library to parse documentation
MIT License
30 stars 15 forks source link

[Bug]: Not consecutive ordered list wrongly combined #1003

Closed brotkrueml closed 2 months ago

brotkrueml commented 2 months ago

Summary

When using something like this:

TYPO3 Core includes two MFA providers:

1. Time-based one-time password (TOTP)

The most common MFA implementation. A QR-code is scanned (or alternatively,
a shared secret can be entered) to connect an Authenticator app such as Google
Authenticator, Microsoft Authenticator, 1Password, Authly or others to the
system and then synchronize a token, which changes every 30 seconds.

On each log-in, after successfully entering the password, the 6-digit code
shown by the Authenticator App must be entered.

2. Recovery codes

This is a special provider which can only be activated if at least one other
provider is active, as it's only meant as a fallback provider, in case the
authentication credentials for the "main" provider(s) are lost. It is encouraged
to activate this provider, and keep the codes at a safe place.

The output is like:

ordered-list

This should not be considered as an ordered reST list, a renumbering should not happen (like for 2. -> 1.)

Expected output

Leave the numbering as is. Also, do not mark it as a list, as only one item is available.

linawolf commented 2 months ago

Sphinx also treates such constructs as ordered lists with one item and ppl use this for example to display bignums, see https://typo3.slack.com/archives/C028JEPJL/p1714991828602269

Therefore I made a PR to preserve the ordering, But such constructs will still be interpreted as lists with one item.

If desired you can escape the dot of the list ordering to prevent a list from being parsed:

TYPO3 Core includes two MFA providers:

1\. Time-based one-time password (TOTP)

The most common MFA implementation. A QR-code is scanned (or alternatively,
a shared secret can be entered) to connect an Authenticator app such as Google
Authenticator, Microsoft Authenticator, 1Password, Authly or others to the
system and then synchronize a token, which changes every 30 seconds.

On each log-in, after successfully entering the password, the 6-digit code
shown by the Authenticator App must be entered.

2\. Recovery codes

This is a special provider which can only be activated if at least one other
provider is active, as it's only meant as a fallback provider, in case the
authentication credentials for the "main" provider(s) are lost. It is encouraged
to activate this provider, and keep the codes at a safe place.